Linux Toolchain

This web page describes a way to install a working AVR 64-bit toolchain ("avr-gcc") based on using the Arduino IDE software. The Arduino IDE is normally used with a graphical user interface (GUI) to write programs in the Arduino style, but all the avr-gcc command line programs are inside the IDE, and with a little work you can run them from the command line. 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 the command line.

If you don't want to go through these steps to make use of the IDE's programs, there is a simpler way to do it, but the avr-gcc software that ends up being installed is quite a bit older than what Ardiuno provides and there may be issues related to that. Scroll to the bottom of this page, or click here to see these instructions.

Important: The information below assumes you are at least moderately familiar with using the one of the "shell" programs and its command line interface, and with basic Unix-type commands for moving around the file system and doing simple operations. If you are not familiar with using the command line interface we suggest you take a look at this web page for a short tutorial on the subject.

Warning: Some of the steps below require administrator or "root" privileges. When using the command line 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 system. Subsequent uses of "sudo" may not ask for the password if done shortly after the first one was done.

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. The downloaded file may have a name like "arduino-1.8.15-linux64.tar.xz". The extracted files can be placed anywhere, but in this example we'll put them in the "/usr/local" directory. Assuming the downloaded file is in your home directory, do the following steps.

    $ unxz arduino-1.8.19-linux64.tar.xz
    $ cd /usr/local
    $ sudo tar xf ~/arduino-1.8.19-linux64.tar
    $ sudo ln -s arduino-1.8.19 arduino

This has installed the Arduino IDE files in /usr/local and they can be reached from the command line in /usr/local/arduino.

Step 2: Find the AVR Toolchain

Using the command line, you'll need to find the AVR toolchain that is inside the Arduino IDE. First use the "cd" command to go to /usr/local and then do another "cd" to get inside the Arduino IDE package. Assuming you installed it in /usr/local as described above do something like this.

    $ cd /usr/local/
    $ cd arduino

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

    $ cd 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  builtin_tools_versions.txt  include  libexec
    bin  etc                         lib      x86_64-pc-linux-gnu
    
    $ ls bin
    arduinoOTA     avr-cpp        avr-gcc-ar      avr-gprof    avr-objdump
    avr-addr2line  avrdude        avr-gcc-nm      avr-ld       avr-ranlib
    avr-ar         avr-elfedit    avr-gcc-ranlib  avr-ld.bfd   avr-readelf
    avr-as         avr-g++        avr-gcov        avr-man      avr-size
    avr-c++        avr-gcc        avr-gcov-dump   avr-nm       avr-strings
    avr-c++filt    avr-gcc-7.3.0  avr-gcov-tool   avr-objcopy  avr-strip

Now that you have found the AVR toolchain files, get the full path to the AVR toolchain with the "pwd".

    $ pwd
    /usr/local/arduino/hardware/tools/avr

Make a note of the path since you will need that for the next step.

Step 3: Install Link to AVR Toolchain

The next step is to 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. In the example below we also create a "/usr/local/bin" directory since we'll need that later.

    $ cd /usr/local
    $ sudo ln -s arduino/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 program that runs inside the command line 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 like this, but may be different if you have installed other software packages.

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

In this case the system will search the "/usr/local/sbin" directory for the program, then the "/usr/local/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 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 Linux, with names like "bash", "zsh", "tcsh", etc., and the choice of which file to edit depends on the shell your system 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.

• If you are using the "bash" shell follow the steps below to edit the .bash_profile file in your home directory, or create a new one if it doesn't exist.
• If you are using the "zsh" shell follow the steps below to edit the .zshrc file in your home directory, or create a new one if it doesn't exist.

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!: To make this change to the PATH take effect it is necessary to close the current command line 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/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

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 command line 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 "linux-avrdude.zip" from the class web site (Click here). Wherever the zip file ends up, find it and double-click on it to extract the "avrdude.sh" file (unless that has already done that for you).

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.

In the command line window, do the following steps to install the file in /usr/local/bin and make it executable. The following example shows the steps to do if the "avrdude.sh" ended up in the Downloads folder.

    $ cd $HOME/Downloads
    $ chmod +x avrdude.sh
    $ sudo mv avrdude.sh /usr/local/bin/avrdude
    $ cd $HOME

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

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.

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 the "make" Program

Linux installations may already have the "make" program installed. You can check with the "which" command to find out if it's installed.

    $ which make
    /usr/bin/make

If the "which" command doesn't show an installed "make", you should install it with the command.

    $ sudo apt-get install make

Step 7: Enable Arduino Downloading

The step below allows you to program an Arduino board as your normal user rather than doing it as "root" (generally a good idea). To do this you need to add yourself to the Linux group that controls the Arduino when it's attached. The Arduino is usually in the "dialout" group so you need to be added to that group.

    $  sudo usermod -a -G dialout your_username

where "your_username" is whatever username you use when logging in to the system.

Step 8: 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 command line 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/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-pc-linux-gnu

    $ 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: ....

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

Using Linux Packages for avr-gcc Installation

This section describes another way to install the avr-gcc software that is easier to do, but seems to install an older version of the programs. If you have already done the preceding steps to install the toolchain and it seems to be working you don't need to do the following steps.

The easiest way to install a working toolchain for doing command line compiling and downloading of programs to AVR microcontrollers is by installing some packages that are available in most Linux distributions. However is appears that most of these packages install a somewhat older version of the avr-gcc toolchain.

For Debian and Ubuntu Linux the following packages need to be installed.

• gcc-avr
• binutils-avr
• gdb-avr
• avr-libc
• avrdude

The installation can be done with the command

    sudo apt-get install gcc-avr binutils-avr gdb-avr avr-libc avrdude

This may also cause several other packages to be installed. Check to see if the "make" program is present on the system. If not also do "sudo apt-get install make" to install it.