The USC Andrew and Erna Viterbi School of Engineering USC Ming Hsieh Department of Electrical Engineering University of Southern California

EE 459Lx - Embedded System Design Laboratory

AVR Toolchain for 64-bit macOS

by
Allan Weber

USC Dept. of Electrical and Computer Engineering
Last edited: July 11, 2020

The current release of macOS (10.15, a.k.a. "Catalina") has made it necessary to use an AVR development toolchain that consists of 64-bit executable programs. The previous toolchain used in EE459 consisted of 32-bit programs and can no longer be used. This web page describes a way to install a working AVR 64-bit toolchain based on using the Arduino IDE software. The Arduino IDE application actually contains a nearly complete copy of most of the AVR toolchain programs and with a little work these can be run from a Terminal window. Since Arduino appears to be periodically releasing new versions of their IDE, and this includes updated versions of the AVR toolchain, you can take advantage of this and use the toolchain software from within the Arduino IDE from a Terminal window.

Important: The information below assumes you are at least moderately familiar with using the Terminal program and its command line interface, and with basic Unix-type commands for moving around the file system and doing simple operations. The program that runs inside the Terminal window to accept typed commands and then does something is called the "shell" program. As of macOS 10.15 it appears the default shell program is "zsh". Earlier versions of macOS used the "bash" shell. You can display the value of the "SHELL" variable to see what shell program you are using. For example,

    $ printenv SHELL
    /bin/bash

shows that the "bash" shell is being used. You need to know which shell program is being used since that affects some of the steps below.

Warning: Some of the steps below require administrator privileges. When using the Terminal program this is done with the "sudo" command to run single command as the adminstrator. The first time the "sudo" is typed, the system will ask for your password, meaning the password you use to login to the Mac. Subsequent uses of "sudo" may not ask for the password if done shortly after the first one was done.

Note: Everything below is about setting this up on a macOS system. However, the Windows version of the Arduino IDE also includes the AVR toolchain software so with some changes, the process should also work on Windows. Unfortunately the author has limited Windows skills so he will leave it to someone else to figure out the details.

Step 1: Install the Arduino IDE

Download and install a version of the Arduino IDE that is version 1.8.10 or later. Version 1.8.10 appears to be the first that contained the avr-gcc software as 64-bit binaries. This is just a matter of downloading the ".zip" file, unzipping it to get the Arduino software with the green, round icon, and then putting it someplace like the system Applications folder or in the Applications folder inside your home folder. It doesn't make any difference where it goes as long as you can find it using the Terminal program as described in the next step.

The Mac may have to be convinced to let you run the Arduino software. Double-click on the Arduino IDE application to start it up. It should first display the Arduino splashscreen and then a window where you can start typing a program. If that happens you can quit the program and move on the step 2 below. However if it instead puts up a warning that the Mac doesn't want to start the program since it's from an unknown developer, you will need to convice the Mac to run the program. From the Apple menu, open up the System Preferencess and then click on the "Security & Privacy" icon, and on the screen that appears, click on the "General" tab. Towards the bottom of the window there should be place where you can confirm that you want to start the Arduino IDE application. Once the Arduino IDE starts, you can quit it and the issue should be fixed.

Step 2: Find the AVR Toolchain

Using a Terminal windows, you'll need to find the AVR toolchain that is inside the Arduino IDE. First use the "cd" command to find the Arduino.app file and then do another "cd" to get inside the Arduino.app package. What looks like a single file on the Mac, like the Arduino.app package, is actually a directory full of subdirectories containing various things and the Terminal program can be used to get inside this directory structure. Assuming you installed it in the top level Applications folder do something like this.

    $ cd /Applications/Arduino.app

If the location is in a folder that has spaces in the path name, make sure to put quotes around the path. For example

    $ cd "/Users/weber/My Apps/Arduino.app"

Now dig deeper into the directory struction to find the AVR toolchain.

    $ cd Contents/Java/hardware/tools/avr

This was the path to it as of the time this web page was written but it may change so be prepared to hunt for it if the above paths are no longer correct.

Doing an "ls" at this point should show that you are in the AVR toolchain directory and "ls bin" will show the subdirectory with the compiler, linker, downloader, etc.

    $ ls
    avr                             etc                             libexec
    bin                             include                         x86_64-apple-darwin16.1.0
    builtin_tools_versions.txt      lib

    $ ls bin
    arduinoOTA      avr-c++filt     avr-gcc-5.4.0   avr-gcov-tool   avr-man         avr-readelf
    avr-addr2line   avr-cpp         avr-gcc-ar      avr-gdb         avr-nm          avr-size
    avr-ar          avr-elfedit     avr-gcc-nm      avr-gprof       avr-objcopy     avr-strings
    avr-as          avr-g++         avr-gcc-ranlib  avr-ld          avr-objdump     avr-strip
    avr-c++         avr-gcc         avr-gcov        avr-ld.bfd      avr-ranlib      avrdude

Now that you have found the AVR toolchain files, get the full path to the AVR toolchain with the "pwd -P" command and make a copy of this string for pasting later.

    $ pwd -P
    /Applications/Arduino.app/Contents/Java/hardware/tools/avr

Step 3: Install Link to AVR Toolchain

Put a link to the above AVR toolchain directory someplace where you can add it to the executable search path. A recommended place is in the "/usr/local" directory. Move to the /usr/local directory and make a symbolic link using the path to the AVR toolchain that you copied above. Make sure to put the path in quotes if it contain any spaces in the directory names. In the example below we also create a "/usr/local/bin" directory since we'll need that later.

    $ cd /usr/local
    $ sudo ln -s /Applications/Arduino.app/Contents/Java/hardware/tools/avr avr
    $ sudo mkdir bin
    $ cd $HOME

You now have a "/usr/local/avr" directory with the toolchain programs. The last command above ("cd $HOME") does a "cd" back to your home directory.

Step 4: Adjust PATH Variable

The environment variable "PATH" contains a list of directories (separated by colons - ":") that the system will search through when you tell it to execute a program. It starts by searching the first directory listed for the program, and goes down the list until if find the program in one of them and runs it. To make the Arduino avr-gcc toolchain work properly it's very important the the PATH variable be set properly. The default value of the PATH variable is set by the system, but often modified by user-written commands that get run when the shell starts up.

You will need to modify the executable search path to add a couple directories (/usr/local/bin and /usr/local/avr/bin) to the path. The easiest way to do this is to edit one of the shell start-up files in your home directory to add a command that adds the correct directories to the start of the search path. Unfortunately, the choice of which file to edit depends on the the shell your Mac is using, as found at the top of this web page from the SHELL variable.

To open one of these files with the BBedit editor, use the "Open..." item under the "File" menu and navigate to your home directory. Files that start with a period, like the one you are trying to edit, are hidden and don't normally appear in the list of files to open. To find them, click on the "Options" button at the bottom of the box showing the files, and then click the "Show hidden items". The hidden files should now appear and you can select the one you need to open.

Edit the file and add this line to it.

    export PATH=/usr/local/bin:/usr/local/avr/bin:$PATH

This adds the /usr/local/bin and /usr/local/avr/bin directories to the start of the executable search path. To make this take effect it is necessary to kill the current Terminal window and open up a new one. To confirm that the path is now correct you can print it out.

    $ printenv PATH
    /usr/local/bin:/usr/local/avr/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin

It should show /usr/local/bin as the first directory, and /usr/local/avr/bin after it. If the /usr/local/bin directory shows up twice like in the example above you can ignore this since it won't affect things.

Step 5: Install the "avrdude" Program

The "avrdude" program for downloading code to the AVR microcontroller that comes with the Arduino IDE works when used directly from a Terminal window but it needs to be told where the "avrdude.conf" configuration file is located. The simplest fix for this is to create an "avrdude" shell script that invokes the Arduino IDE's "avrdude" program and supplies the path to the configuration file as an argument on the command line.

You can put this shell script anywhere but it needs to be in a directory in your search path that is ahead of the /usr/local/avr/bin directory where the real "avrdude" program is located. In step 3 above we created a "/usr/local/bin" directory, and in step 4 we put that directory ahead of the /usr/local/avr/bin directory in the PATH variable, so that would be the preferred place to put the script.

Use your text editor to create a file containing the three lines below, and then save it with the filename "avrdude".

    #!/bin/sh
    AVRDIR="/usr/local/avr"
    exec -a "$0" "$AVRDIR/bin/avrdude" "-C" "$AVRDIR/etc/avrdude.conf" "$@"

Once the file has been created, change the protection mode on the file so it's executable, move it to the /usr/local/bin directory, and tell macOS to allow executing it.

    $ chmod +x avrdude
    $ sudo mv avrdude /usr/local/bin/
    $ xattr -d com.apple.quarantine /usr/local/bin/avrdude

Once the above is done, when you run "avrdude", it will cause the three line "avrdude" file you created to execute the real "avrdude" program in the Arduino IDE and supply the correct arguments to it. Since it's not in the Arduino.app folder, it's not affected by updating to a newer Arduino.app and should work with any newer version.

If you try typing the commmand avrdude at this point, it may display some lines about options available when invoking the program, or it may display an error messages about no programming device specified. In either case this shows the program is being executed and you can move to the next step.

Important: The above will only work if your PATH variable is such that the copy of avrdude you just created is found before the one in /usr/local/avr/bin. If you followed the instructions in step 4 above this should be the case. Otherwise you may have to make adjustments to the PATH, or put avrdude someplace else to make it all work.

Step 6: Install a Working "make" Program

In some releases of the macOS, the "make" program that comes with it is mostly non-functional. Try typing "make --version" and see what happens. If it responds with a some lines showing the version number and some copyright notices, then it will probably work and you can skip the rest of this section. However if it responds with a message about how Apple's Xcode developer software needs to be installed, then a new working version of "make" will have to be installed. There are a few different ways to get a working "make" on the system.

If you decide to use the pre-complied "make" from our web site, download the "macos-make.zip" file and unzip it. It contains the executable "make" program that can be installed in some place like /usr/local/bin.

    $ unzip macos-make.zip
    $ sudo mv make /usr/local/bin/

Whatever directory "make" is installed in, that directory must be in the executable search path ahead of /usr/bin where Apple's "make" is normally installed.

If you decide to compile it yourself from Gnu sources, be advised that the normal way to build the "make" program from sources uses a working copy of "make" already on the system. Since you probably don't have that follow the instructions in the "README" file to use the provided "build.sh" script to build the "make" program. After the program is compiled, decide where to put the executable "make", perhaps /usr/local/bin, and move it there. Make sure whatever directory you put it in is also included in your executable search path. If not, edit the shell startup file as shown above to include it.

Step 7: Test Installation

At this point all the command line operations for compiling and downloading AVR software should be working. You might have to kill and re-open the Terminal window you used to install the software for some of it to work but after that it should work normally. First use the "which" command to confirm which program execute when you type the command. It will print out the program that will execute and check to make sure they are the ones in either /usr/local/bin or /usr/local/avr/bin. You can skip the test for the "make" program if you didn't install a new one in the section above.

    $ which make
    /usr/local/bin/make

    $ which avr-gcc
    /usr/local/avr/bin/avr-gcc

    $ which avrdude
    /usr/local/bin/avrdude

Next, you should be able to test running each program and have it print out their version numbers.

    $ make --version
    GNU Make 4.2.1
    Built for x86_64-apple-darwin15.5.0

    $ avr-gcc --version
    avr-gcc (GCC) 7.3.0

    $ avrdude --help
    (this prints lots of stuff but at the end...)
    avrdude version 6.3-20190619, URL: ....

Some of these commands may cause the Mac to put a box on the screen saying this program is from an unknown developer and it refuses to run it. If that happens, go to the "System Preferences" under the Apple menu and click on the "Security & Privacy" icon. In the bottom half of the screen is should list the program you tried to run and give you the option to allow running it. When you try running it again it may put up another box asking if you sure you want to run it. Confirm that you do and the program will probably run. After all that the program will run in the future without asking.

At this point the only thing left to do is to try compiling and downloading a program.