|
|
|
by
Allan Weber
USC Dept. of Electrical and Computer Engineering
Last edited: March 14, 2025
This web page describes a way to install a working AVR 64-bit toolchain based on using the version 2 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 Number 1: 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 administrator. The first time the "sudo" is typed, the system will ask for your password, meaning the password you use to login to the Mac. When typing the password on the keyboard, the characters are not shown on the screen, nor will it show little black circles indicating characters have been typed. It will look like nothing has been typed, but finish entering the password and then press Return. Subsequent uses of "sudo" may not ask for the password if done shortly after the first one was done.
Warning Number 2: Starting in version 11 of the macOS ("Big Sur") Apple has added extra security "features" that can interfere with using the Terminal application for this class. To see if you are affected by this, open a Terminal window and type the command "ls Desktop". If you see a list of the files that are visible on the desktop screen, you can skip the rest of this section. However if you get a warning about the operation not permitted, you will need to follow the instructions below to fix things.
Once the change above has been made, try doing the "ls Desktop" test again to see if the desktop files can be seen.
Warning Number 3:The Apple Xcode developer tools are not required in order to run the avr-gcc software. If during the installation steps below the Mac asks about installing Xcode, you can cancel that since it's not needed. If Xcode has already been installed it should not affect running the avr-gcc software.
Step 0: Remove Any Old Toolchain Package
If you had previously installed the AVR toolchain from the "CrossPack" distribution, you should remove that toolchain so it doesn't get in the way of the programs you are installing below. If you aren't sure if that software is installed, check for it with the command line interface operation
$ ls /usr/local
If you see any file or directories listed that start with "CrossPack-AVR" that means the CrossPack software has been installed and needs to be removed.
The CrossPack software has to be removed by using a command line interface operation. To remove it, use the command
$ cd /usr/local
$ sudo rm -rf CrossPack-AVR-20131216 CrossPack-AVR
After that, try doing the "ls /usr/local/" operation again and check that the CrossPack entries have been removed.
Step 1: Install the Arduino IDE
Download and install version 2 of the Arduino IDE. At the present time version 2.3.4 is the latest version.
Do not download any version that starts with "1" or says it's a "release candidate" or "hourly build" since these are configured differently and will not work with our setup. Installing the Arduino IDE is just a matter of downloading the ".dmg" file, double clicking on it to mount the installation volume, and then dragging the "Arduino IDE.app" as shown below to someplace like the system Applications folder or in the Applications folder inside your home folder.
Note: If the Arduino application has a round icon rather than the square one shown above, then you have downloaded and installed version 1 of the Arduino IDE.
Once the Arduino IDE has been installed, double-click on the icon of the Arduino IDE application to start it up. When the program starts it has to do a lot of installation of additional files so it may take several seconds before it shows 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 convince the Mac to run the program by following these steps.
Once the Arduino IDE starts, you can quit it and the issue should be fixed.
Step 2: Find the AVR Toolchain
When the Arduino IDE is started in the previous step it installs a bunch of software in your "Library" folder in a folder called "Arduino15". The toolchain programs that we need for EE109 are in that collection of files.
Using a Terminal windows, you'll need to find the AVR toolchain that is inside the Arduino15 folder. First use the "cd" command to find the Arduino15 folder and go inside it.
$ cd Library/Arduino15
Now dig deeper into the directory struction to find the AVR toolchain.
$ cd packages/arduino/tools/avr-gcc/7.3.0-atmel3.6.1-arduino7
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 lib
bin libexec
include x86_64-apple-darwin16.1.0
$ ls bin
avr-addr2line avr-elfedit avr-gcc-ranlib avr-ld.bfd avr-readelf
avr-ar avr-g++ avr-gcov avr-man avr-size
avr-as avr-gcc avr-gcov-dump avr-nm avr-strings
avr-c++ avr-gcc-7.3.0 avr-gcov-tool avr-objcopy avr-strip
avr-c++filt avr-gcc-ar avr-gprof avr-objdump
avr-cpp avr-gcc-nm avr-ld avr-ranlib
Now that you have found the AVR toolchain files, you need to get the full path to the AVR toolchain. This can be done by typing the command "pwd -P" which will then print out your current location in the file system.
$ pwd -P
/Users/myusername/Library/Arduino15/packages/arduino/tools/avr-gcc/7.3.0-atmel3.6.1-arduino7
Make a copy of this output string (just the output that was printed by the command, not the "pwd -P" part) for pasting in the next step.
Step 3: Install Link to AVR Toolchain
We now want to configure things so the system will execute the AVR toolchain programs that are in the directory you just found in the previous step. To do this we first want to put a link to that directory in one of the places commonly used to hold programs that are executed. A recommended place is in the "/usr/local" directory. We'll use the "cd" command to move to the /usr/local directory and then make a symbolic link using the path to the AVR toolchain that you copied above. In the example below we also create a "/usr/local/bin" directory since we’ll need that later.
Note: In the example below we don't show the full path to the avr-gcc directory since it's too wide for the web page to display, but you'll need to use the full path that you found above with the "pwd -P" command when you type the command. In other words don't just copy what we show below with the "missing stuff" in the middle.
$ cd /usr/local
$ sudo ln -s /Users/myusername/Library/...missing stuff.../7.3.0-atmel3.6.1-arduino7 avr
$ sudo mkdir bin
$ cd $HOME
^^^
Make sure to have "avr" at the end of line 2
Note that on this command line after you paste in the path to the files in the Ardunino application, there is a space and "avr" at the very end of the command that you will have to add manually.
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 program that runs inside the Terminal window to accept typed commands and then do something is called the "shell" program. Whenever a command is typed, the shell has to find that program for the system to execute. The environment variable "PATH" contains a list of directories that the shell will search through when you tell it to execute a program. We can see the current setting of the PATH variable with the command "printenv PATH" which will print out the list of directories, separated by colons (":"), that will be searched.
The list typically looks something like this, but may be different if you have installed other software packages.
$ printenv PATH
/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin
In this case the system will search the "/usr/local/bin" directory for the program, then the "/usr/bin" directory, etc., down the list until if find the program in one of the directories and runs it. 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.
To make the Arduino avr-gcc toolchain work properly it's very important the PATH variable be set correctly so it includes the directories where the avr-gcc programs have been installed. The easiest way to do this is to edit one of the files in your home directory that the shell program refers to when starting to include a command that adds the correct directories to the list. Unfortunately there are several shell programs available for use with macOS, with names like "bash", "zsh", "tcsh", etc., and the choice of which file to edit depends on the shell your Mac is using. You need to determine which shell program you are using in order to proceed with the the installation. This can be done by displaying the value of the "SHELL" environment variable by typing the command "printenv SHELL". For example,
$ printenv SHELL
/bin/bash
shows that the "bash" shell is being used. Once you identify which shell program you are using you can follow the steps below.
Before editing the file, do one of the following commands
$ touch .bash_profile
or
$ touch .zshrc
If the file already exists, doing this command won't have any effect on the file, but if the doesn't exist it will create a new empty file that you can edit.
To open one of these files with the Visual Studio Code 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, hold down the command (⌘) and shift keys, and type a period ('.'). The list of files shows should refresh and now show all the hidden files that start with a period. You can select the one you need to open.
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. Make sure to save the modified file.
IMPORTANT!: Once you have made the change to the files that sets the PATH variable, close the Terminal window you were using and open up a fresh one. Changes to the PATH variable only take effect when a new Terminal window is opened. 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.
Download the file "macos-avrdude2.zip" from the class web site (click here). If it asks you where to put the file, find the "Desktop" folder and put the file there. If it doesn't ask, it will probably put the .zip file in your "Downloads" folder. In that case use the graphical user interface to move the .zip file from the Downloads folder to the Desktop. Once the .zip file is on the Desktop, find it and double-click on it to extract the "avrdude2.sh" file (unless the Mac has already done that for you).
You can put this shell script in any directory that is in the PATH variable but a convenient place is in the "/usr/local/bin" directory that was created in step 3 and added to the PATH in step 4.
In the Terminal windows, do the following steps to install the file in /usr/local/bin and make it executable.
$ cd $HOME/Desktop
$ chmod +x avrdude2.sh
$ sudo mv avrdude2.sh /usr/local/bin/avrdude
$ xattr -d com.apple.quarantine /usr/local/bin/avrdude
$ cd $HOME
Note: If the "xattr" command above doesn't work, just ignore this since Apple may have changed their OS that used to require this step.
Once the above steps have been done to create the "avrdude" script, when you run "avrdude", it will cause the "avrdude" file you created to execute the real "avrdude" program in the AVR toolchain and supply the correct arguments to it.
If you try typing the command 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.
Step 6: Install a Working "make" Program
In order to compile and download the programs to your Arduino, a working version of the "make" utility needs to be on your system. Apple usually provides this as part of the system software, but in some releases of the macOS, the "make" program that comes with it is mostly non-functional. In the Terminal window, type the command "make --version" and see what happens.
If it responds with a some lines showing the version number and some copyright notices, like this
$ make --version
GNU Make 3.81
Copyright (C) 2006 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.
There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
This program built for i386-apple-darwin11.3.0
then the "make" provided by Apple will probably work fine and you can skip the rest of this step and proceed to Step 7.
If it responds with a message about how Apple's developer tools need to be installed like this
$ make --version
xcode-select: note: no developer tools were found at '/Application/Xcode.app',
requesting install. Choose an option in the dialog to download the command line
developer tools.
and may put up a dialog about "The 'make' command requires the command line developer tools.", then click the "Not now" button in the dialog and follow the steps below to install a working version of "make".
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, which may not be exactly the same as those shown below. IMPORTANT: When you try running one of the programs, if a dialog appears on the screen about how the program "cannot be opened because the developer cannot be verified" follow the instructions at the end of this section to override this restriction, then come back and repeat the test to make sure the program can be run.
$ 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.