install_tools(3avr)

📦
version 2.2.1 · 4 versions
, in ubuntu resolute, ubuntu stonking

✨ NAME ✨

okay so bestie, welcome to install_tools(3avr) 💖 — this manual page is literally gonna show you how to build and install, from source code, a complete development environment for AVR processors using the GNU toolset. not me about to become an embedded dev main character. 💅 no cap.

This chapter has two main sections: one for Linux, FreeBSD, and other Unix-like operating systems, and another one for Windows. (iykyk, Windows girlies we got you.) There's also Canadian Cross Builds and Using Git further down, but let's not get ahead of ourselves. fr fr.

Here's the vibe check, aka the table of contents:

  • Required AVR Tools
  • Optional AVR Tools
  • Building and Installing under Linux, FreeBSD, and Others
    • Preparations
      • Install Location
      • Directory Layout
    • GNU Binutils
    • GCC
    • AVR-LibC
    • AVRDUDE
    • SimulAVR
    • AVaRICE
  • Building and Installing under Windows
    • Required Tools
    • Building
  • Canadian Cross Builds
  • Using Git

🛠️ Required AVR Tools 🛠️

These are the non-negotiables, bestie. You literally cannot build your AVR dev environment without them. Periodt. 👑

💖 GNU Binutils 💖

💖 GCC 💖

💖 AVR-LibC 💖

✨ Optional AVR Tools ✨

okay so these are optional, bestie. You can <highkey>totally</highkey> develop programs for AVR devices without them. They may or may not be of use for you. No pressure, it's not that deep. 💅

💖 AVRDUDE 💖

💖 GDB 💖

The GNU Debugger GDB is hosted together with GNU Binutils. So when you don't want or need GDB, you can configure Binutils with --disable-gdb. slay. 🔥

💖 SimulAVR 💖

💖 AVaRICE 💖

💻 Building and Installing under Linux, FreeBSD, and Others 🐧

okay so bestie, when you install these tools, the default vibe is to dump everything under /usr/local. But that's kinda messy, right? To keep your AVR tools separate from the base system, it's usually way better to install everything into /usr/local/avr. If that directory doesn't exist, create it before you even try to install anything. You'll need root access to install there. If you don't have root (or just don't want it), you can install in your home directory instead, like $HOME/local/avr. Where you install is totally arbitrary, but keep it consistent for all the tools, okay? 💅

Warning 🚨 If you have CC set to anything other than avr-gcc in your environment, the configure script will literally fail. Best to not have CC set at all. No cap.
Note ✨ It's usually best to use the latest released version of each tool. Slay.

🛠️ Preparations

📍 Install Location

You specify the installation directory using the --prefix=dir option with the configure script. It's super important to install all the AVR tools in the same directory or some tools won't work correctly. To keep things consistent and simplify, we'll use $PREFIX to refer to whatever directory you want. You can set this as an environment variable if you want, like this (using a Bourne-like shell):

$ PREFIX=$HOME/local/avr
$ export PREFIX
Note 💖 Be sure your PATH environment variable is set to search the directory you install everything in before you start installing anything. For example, if you use --prefix=$PREFIX, you must have $PREFIX/bin in your exported PATH. As such:
$ PATH=$PATH:$PREFIX/bin
$ export PATH

🗂️ Directory Layout

The instructions below build Binutils, GCC and AVR-LibC outside of the source tree, because:

  • When something goes wrong, you can just remove the build directory and start all over again with a fresh build folder. So iconic.
  • You may want to build the tools with different configure options, e.g. build the tools for a Linux host and then build a Canadian cross to run on a Windows host.
  • GCC does not support configuring anywhere in the source tree, so we'll have to use a separate build folder outside the source tree, anyway.

The instructions below assume you've set up a directory tree like

+--source
+--build

in some place where you have write access, like in your home directory.

After successful downloads and builds, the tree will be something like:

+--source
|   +--gcc-<version>
|   +--binutils-<version>
|   +--avr-libc-<version>
+-- build
    +--gcc-<version>-avr
    +--binutils-<version>-avr
    +--avr-libc-<version>

🔧 GNU Binutils for the AVR target

The Binutils package provides all the low-level utilities needed in building and manipulating object files. Once installed, your environment will have an AVR assembler (avr-as), linker (avr-ld), and librarian (avr-ar and avr-ranlib). In addition, you get tools which extract data from object files (avr-objcopy), disassemble object file information (avr-objdump), and strip information from object files (avr-strip). Before we can build the C compiler, these tools need to be in place. Periodt.

Download and unpack the source files:

$ # in ./source
$ tar xfj binutils-<version>.tar.bz2

Replace <version> with the version of the package you downloaded.

If you obtained a gzip compressed file (.tar.gz or .tgz), use gunzip instead of bunzip2, or tar xfz file.tar.gz.

The next step is to configure and build the tools. This is done by supplying arguments to the configure script that enable the AVR-specific options. When you also want GDB, just drop --disable-gdb. 👑

$ # in ./build
$ mkdir binutils-<version>-avr
$ cd binutils-<version>-avr
$ ../../source/binutils-<version>/configure --prefix=$PREFIX --target=avr \
    --disable-nls --disable-sim --disable-gdb --disable-werror

When configure is run, it generates a lot of messages while it determines what is available on your operating system. When it finishes, it will have created several Makefiles that are custom tailored to your platform and that are run with the make command.

$ make
Note 🐚 BSD users should note that the project's Makefile uses GNU make syntax. This means FreeBSD users may need to build the tools by using gmake.

If the tools compiled cleanly, you're ready to install them. If you specified a destination that isn't owned by your account, you'll need root access to install them. To install:

$ make install

You should now have the programs from Binutils installed into $PREFIX/bin. Don't forget to set your PATH environment variable before going to build avr-gcc. To check that the correct assembler is found, run

$ avr-as --version

which should print the <version> of the used Binutils sources.

🪄 GCC for the AVR target

Warning ⚠️ You must install avr-binutils and make sure your path is set properly before installing avr-gcc.

Before we can configure the compiler, we have to prepare the sources. GCC depends on some external host libraries, namely GMP, MPFR, MPC and ISL. You can build and install the appropriate versions of the required prerequisites by hand and provide their location by means of --with-gmp= etc. Though in most situations it is easier to let GCC download and build these libraries as part of the configure and build process. All what's needed is an internet connection when running ./contrib/download_prerequisites:

$ # in ./source
$ tar xfj gcc-<version>.tar.bz2
$ cd gcc-<version>
$ ./contrib/download_prerequisites

$ # in ./build
$ mkdir gcc-<version>-avr
$ cd gcc-<version>-avr
$ ../../source/gcc-<version>/configure --prefix=$PREFIX --target=avr --enable-languages=c,c++ \
    --disable-nls --disable-libssp --disable-libcc1 \
    --with-gnu-as --with-gnu-ld --with-dwarf2
$ make
$ make install # or make install-strip

The GCC binaries may consume quite some disc space. In most cases, you don't need the debug information in the compiler proper, and installing with

$ make install-strip

can save you some space. ✨

📚 AVR-LibC

Warning 🚨 You must install avr-binutils, avr-gcc and make sure your path is set properly before installing AVR-LibC.
Note 🌸 If you have obtained the latest AVR-LibC from git, you will have to run the ./bootstrap script before using either of the build methods described below.

To build and install AVR-LibC:

$ # in ./source
$ tar xfz avr-libc-<version>.tar.gz

$ # in ./build
$ mkdir avr-libc-<version>
$ cd avr-libc-<version>
$ ../../source/avr-libc-<version>/configure --prefix=$PREFIX \
    --build=x86_64-pc-linux-gnu --host=avr
$ make
$ make install

Where the --build platform can be guessed by running

$ ./source/avr-libc-<version>/config.guess

🔌 AVRDUDE

Note 💀 It has been ported to windows (via MinGW or cygwin), Linux and Solaris. Other Unix systems should be trivial to port to.

avrdude is part of the FreeBSD ports system. To install it, simply do the following:

# cd /usr/ports/devel/avrdude
# make install
Note 👑 Installation into the default location usually requires root permissions. However, running the program only requires access permissions to the appropriate ppi(4) device.

Building and installing on other systems should use the configure system, as such:

$ gunzip -c avrdude-<version>.tar.gz | tar xf -
$ cd avrdude-<version>
$ mkdir obj-avr
$ cd obj-avr
$ ../configure --prefix=$PREFIX
$ make
$ make install

🎮 SimulAVR

SimulAVR also uses the configure system, so to build and install:

$ gunzip -c simulavr-<version>.tar.gz | tar xf -
$ cd simulavr-<version>
$ mkdir obj-avr
$ cd obj-avr
$ ../configure --prefix=$PREFIX
$ make
$ make install
Note 🧪 You might want to have already installed avr-binutils, avr-gcc and AVR-LibC if you want to have the test programs built in the simulavr source.

🐞 AVaRICE

Note 🚫 These install notes are not applicable to avarice-1.5 or older. You probably don't want to use anything that old anyways since there have been many improvements and bug fixes since the 1.5 release.

AVaRICE also uses the configure system, so to build and install:

$ gunzip -c avarice-<version>.tar.gz | tar xf -
$ cd avarice-<version>
$ mkdir obj-avr
$ cd obj-avr
$ ../configure --prefix=$PREFIX
$ make
$ make install
Note 🔗 AVaRICE uses the BFD library for accessing various binary file formats. You may need to tell the configure script where to find the lib and headers for the link to work. This is usually done by invoking the configure script like this (Replace <hdr_path> with the path to the bfd.h file on your system. Replace <lib_path> with the path to libbfd.a on your system.):
$ CPPFLAGS=-I<hdr_path> LDFLAGS=-L<lib_path> ../configure --prefix=$PREFIX

🪟 Building and Installing under Windows

Building and installing the toolchain under Windows requires more effort because all of the tools required for building, and the programs themselves, are mainly designed for running under a POSIX environment such as Unix and Linux. Windows does not natively provide such an environment. 😭

There are two projects available that provide such an environment, Cygwin and MinGW. There are advantages and disadvantages to both. Cygwin provides a very complete POSIX environment that allows one to build many Linux based tools from source with very little or no source modifications. However, POSIX functionality is provided in the form of a DLL that is linked to the application. This DLL has to be redistributed with your application and there are issues if the Cygwin DLL already exists on the installation system and different versions of the DLL. On the other hand, MinGW can compile code as native Win32 applications. However, this means that programs designed for Unix and Linux (i.e. that use POSIX functionality) will not compile as MinGW does not provide that POSIX layer for you. Therefore most programs that compile on both types of host systems, usually must provide some sort of abstraction layer to allow an application to be built cross-platform.

okay so plot twist that isn't a plot twist: MinGW lowkey hands you a lil POSIX-flavored corner of the world called MSYS, and it lets you build Unix and Linux applications the way they're supposed to be built — a configure step, a make step, all the sacred ritual. Cygwin does the exact same party trick. ✨ Which means building the AVR toolchain on Windows is giving... the Linux build. Same energy as described above, bestie.

The differences? Just a few things: what the PATH environment variable gets set to, pathname differences, and which tools you need to build the projects under Windows. Let's go meet the tools next. 💅

✨ Tools Required for Building the Toolchain for Windows ✨

These are the tools currently used to build an AVR tool chain. Heads up though: this list may change — either the version of the tools, or the tools themselves — as improvements get made. Things grow, we support that. 🦋

MinGW

  • Download the MinGW Automated Installer, 2013-10-04 (or later)
  • https://sourceforge.net/projects/mingw/files
  • Run mingw-get-setup.exe
  • In the installation wizard, keep the default values and press the "Next" button for all installer pages except for the pages explicitly listed below.
  • In the installer page "Repository Catalogues", select the "Download latest repository catalogues" radio button, and press the "Next" button
  • In the installer page "License Agreement", select the "I accept the agreement" radio button, and press the "Next" button
  • In the installer page "Select Components", be sure to select these items:
    • C compiler (default checked)
    • C++ compiler
    • Ada compiler
    • MinGW Developer Toolkit (which includes "MSYS Basic System").
  • Install.

Install Cygwin

  • Install everything, all users, UNIX line endings. This will take a long time. A fat internet pipe is highly recommended. It is also recommended that you download all to a directory first, and then install from that directory to your machine.
Note 💀 GMP, MPFR, MPC and ISL are required to build GCC. By far the easiest way to use them is by letting GCC download the sources locally by means of running the ./contrib/download_prewrequisites script from the GCC top source. GCC will configure and build these libs during configure and make. No extra errands needed, iconic.

Doxygen is required to build AVR-LibC documentation.

NetPBM is required to build graphics in the AVR-LibC documentation.

fig2dev is required to build graphics in the AVR-LibC documentation.

  • Install fig2dev
    • Version 3.2 patchlevel 5c
    • From WinFig 4.62: http://winfig.com/downloads
    • Download the zip file version of WinFig
    • Unzip the download file and install fig2dev.exe in a location of your choice, somewhere in the PATH.
    • You may have to unzip and install related DLL files for fig2dev. In the version above, you have to install QtCore4.dll and QtGui4.dll.

MikTeX is required to build various documentation.

Ghostscript is required to build various documentation.

  • Install Ghostscript
    • Version 9.00
    • https://www.ghostscript.com
    • Download and install.
    • In the \bin subdirectory of the installation, copy gswin32c.exe to gs.exe.
  • Set the TEMP and TMP environment variables to c:\temp or to the short filename version. This helps to avoid NTVDM errors during building.

🛠️ Building the Toolchain for Windows 🛠️

Every single directory in the PATH environment variable should be specified using its short filename (8.3) version. This will also help to avoid NTVDM errors during building. These short filenames can be specific to each machine — so no, yours isn't broken if it looks different from your friend's. 🙈

Build the tools below in MinGW/MSYS.

Binutils 🔥

  • Open source code package and patch as necessary.
  • Configure and build in a directory outside of the source code tree.
  • Set PATH, in order:
    • <MikTex executables>
    • <ghostscript executables>
    • /usr/local/bin
    • /usr/bin
    • /bin
    • /mingw/bin
    • c:/cygwin/bin
    • <install directory>/bin
  • Configure
CFLAGS=-D__USE_MINGW_ACCESS  \
../$archivedir/configure \
    --prefix=$installdir \
    --target=avr \
    --disable-nls \
    --enable-doc \
    --datadir=$installdir/doc/binutils \
    2>&1 | tee binutils-configure.log
  • Make
make all html install install-html 2>&1 | tee binutils-make.log
  • Manually change documentation location.

GCC 💖

  • Open source code package and patch as necessary.
  • Configure and build in a directory outside of the source code tree.
  • Set PATH, in order:
    • <MikTex executables>
    • <ghostscript executables>
    • /usr/local/bin
    • /usr/bin
    • /bin
    • /mingw/bin
    • c:/cygwin/bin
    • <install directory>/bin
  • Configure
LDFLAGS='-L /usr/local/lib -R /usr/local/lib' \
CFLAGS='-D__USE_MINGW_ACCESS'  \
../gcc-$version/configure \
    --prefix=$installdir \
    --target=$target \
    --enable-languages=c,c++ \
    --with-dwarf2 \
    --enable-doc \
    --with-docdir=$installdir/doc/$project \
    --disable-shared \
    --disable-libada \
    --disable-libssp \
    --disable-libcc1 \
    --disable-nls \
    2>&1 | tee $project-configure.log
  • Make
make all html install 2>&1 | tee $package-make.log

AVR-LibC 🌸

  • Open source code package.
  • Configure and build at the top of the source code tree.
  • Set PATH, in order:
    • /usr/local/bin
    • /mingw/bin
    • /bin
    • <MikTex executables>
    • <install directory>/bin
    • <Doxygen executables>
    • <NetPBM executables>
    • <fig2dev executable>
    • <Ghostscript executables>
    • c:/cygwin/bin
  • Configure
./configure \
    --host=avr \
    --prefix=$installdir \
    --enable-doc \
    --disable-versioned-doc \
    --enable-html-doc \
    --enable-pdf-doc \
    --enable-man-doc \
    --mandir=$installdir/man \
    --datadir=$installdir \
    2>&1 | tee $package-configure.log
  • Make
make all install 2>&1 | tee $package-make.log
  • Manually change location of man page documentation.
  • Move the examples to the top level of the install tree.
  • Convert line endings in examples to Windows line endings.
  • Convert line endings in header files to Windows line endings.

AVRDUDE ⭐

  • Open source code package.
  • Configure and build at the top of the source code tree.
  • Set PATH, in order:
    • <MikTex executables>
    • /usr/local/bin
    • /usr/bin
    • /bin
    • /mingw/bin
    • c:/cygwin/bin
    • <install directory>/bin
  • Set location of LibUSB headers and libraries
export CPPFLAGS="-I../../libusb-win32-device-bin-$libusb_version/include"
export CFLAGS="-I../../libusb-win32-device-bin-$libusb_version/include"
export LDFLAGS="-L../../libusb-win32-device-bin-$libusb_version/lib/gcc"
  • Configure
./configure \
    --prefix=$installdir \
    --datadir=$installdir \
    --sysconfdir=$installdir/bin \
    --enable-doc \
    --disable-versioned-doc \
    2>&1 | tee $package-configure.log
  • Make
make -k all install 2>&1 | tee $package-make.log
  • Convert line endings in avrdude config file to Windows line endings.
  • Delete backup copy of avrdude config file in install directory if exists.

Insight/GDB 🎀

  • Open source code package and patch as necessary.
  • Configure and build in a directory outside of the source code tree.
  • Set PATH, in order:
    • <MikTex executables>
    • /usr/local/bin
    • /usr/bin
    • /bin
    • /mingw/bin
    • c:/cygwin/bin
    • <install directory>/bin
  • Configure
CFLAGS=-D__USE_MINGW_ACCESS  \
LDFLAGS='-static' \
../$archivedir/configure \
    --prefix=$installdir \
    --target=avr \
     --with-gmp=/usr/local \
     --with-mpfr=/usr/local \
     --enable-doc \
     2>&1 | tee insight-configure.log
  • Make
make all install 2>&1 | tee $package-make.log

SRecord 🫶

  • Open source code package.
  • Configure and build at the top of the source code tree.
  • Set PATH, in order:
    • <MikTex executables>
    • /usr/local/bin
    • /usr/bin
    • /bin
    • /mingw/bin
    • c:/cygwin/bin
    • <install directory>/bin
  • Configure
./configure \
    --prefix=$installdir \
    --infodir=$installdir/info \
    --mandir=$installdir/man \
    2>&1 | tee $package-configure.log
  • Make
make all install 2>&1 | tee $package-make.log

And now we switch arenas, bestie. Build the tools below in Cygwin. 💜

AVaRICE 🦋

  • Open source code package.
  • Configure and build in a directory outside of the source code tree.
  • Set PATH, in order:
    • <MikTex executables>
    • /usr/local/bin
    • /usr/bin
    • /bin
    • <install directory>/bin
  • Set location of LibUSB headers and libraries
export CPPFLAGS=-I$startdir/libusb-win32-device-bin-$libusb_version/include
export CFLAGS=-I$startdir/libusb-win32-device-bin-$libusb_version/include
export LDFLAGS="-static -L$startdir/libusb-win32-device-bin-$libusb_version/lib/gcc "
  • Configure
../$archivedir/configure \
    --prefix=$installdir \
    --datadir=$installdir/doc \
    --mandir=$installdir/man \
    --infodir=$installdir/info \
    2>&1 | tee avarice-configure.log
  • Make
make all install 2>&1 | tee avarice-make.log

SimulAVR 🧚

  • Open source code package.
  • Configure and build in a directory outside of the source code tree.
  • Set PATH, in order:
    • <MikTex executables>
    • /usr/local/bin
    • /usr/bin
    • /bin
    • <install directory>/bin
  • Configure
       export LDFLAGS="-static"
       ../$archivedir/configure \
           --prefix=$installdir \
           --datadir=$installdir \
           --disable-tests \
           --disable-versioned-doc \
           2>&1 | tee simulavr-configure.log
  • The make step, aka the part where it all comes together 🫶 — lowkey the moment of truth:
make -k all install 2>&1 | tee simulavr-make.log
make pdf install-pdf 2>&1 | tee simulavr-pdf-make.log

🦋 Canadian Cross Builds 🦋

Okay bestie, this is the ✨fancy✨ one. You can also build avr-gcc for a Windows host while sitting on a Linux build system. It's giving intercontinental. 🛫

So say you've installed an i686-w64-mingw32-gcc toolchain that can compile code to run on host=i686-w64-mingw32. The steps to build a toolchain for Windows are, in order:

  1. Build and install the AVR toolchain for the Linux build machine as explained above. Make sure that running the command
avr-gcc --version

prints the compiler version according to the used GCC sources. This is not optional, bestie. The native AVR cross compiler is required during configure and to build the AVR target libraries like libgcc. Similarly, the version of the found AVR Binutils programs must match the version of the used Binutils sources.

  1. Determine the name of the --build platform like x86_64-pc-linux-gnu — for example by running the config.guess script as shipped with the top level GCC sources (and also with Binutils sources, and AVR-LibC sources after ./bootstrap). ✨
  2. Use different build and install directories, e.g. ./build/binutils-<version>-avr-mingw32 to build Binutils and --prefix=$PREFIX-mingw32 as install path. No sharing, we don't do that here 💅
  3. Configure, build and install Binutils and GCC like for the native build, but add the following configure options:
--build=x86_64-pc-linux-gnu --host=i686-w64-mingw32

This assumes that the required host libraries like GMP are being built in one go with the compiler. This is accomplished by running the contrib/download_prerequisites script from the toplevel GCC sources, just like with the native build. 🎀

  1. There is no need to build AVR-LibC again, because it is a pure target library. It can be installed by means of running
$ # in ./build/avr-libc-<version>
$ make install prefix=$PREFIX-mingw32

In order to "install" the toolchain on Windows, the canadian cross installed in $PREFIX-mingw32 can be moved to the desired location on the Windows computer. The compiler can be used by calling it by its absolute path, or by adding the $PREFIX-mingw32/bin directory to the PATH environment variable. 👑

💜 Using Git 💜

Most of the sources of the projects above are now managed with the git distributed version-control tools (iykyk). When you want to build from the newest development branch, you can clone the repo, like with

$ git clone <repo> [dirname]

Replace <repo> with the URL of the Git repository, e.g. https://github.com/avrdudes/avr-libc.git for AVR-LibC. Notice that when building AVR-LibC from the repo source, you have to run ./bootstrap from the top level AVR-LibC sources prior to configure. Don't skip it, the configure will simply not understand you 😭

Useful options for git clone:

  • dirname — specify an optional directory name for the cloned repository, like:
$ git clone https://github.com/avrdudes/avr-libc.git ./source/avr-libc-main

Without dirname, the name of the git file like avr-libc is used. (So the repo just names itself, main character energy 🌟)

  • --depth 1 — an ordinary clone will clone the complete repository with all its branches and their history. To speed up the cloning and save some disc space, you can just clone the top of the history to some depth. Snip snip ✂️
  • --branch branch — the default branch is the head of the latest development, which is master for GCC and Binutils, and main for AVR-LibC. 🌈

When you want a different ref, like GCC's releases/gcc-14 for the head of the GCC v14 branch, or releases/gcc-14.1.0 for the GCC v14.1 release tag, then you can specify that as branch. To see the available refs, you can use

$ git ls-remote <repo>
And that's the whole page, bestie! Go forth and cross-compile 🫶🌸

Okay so this was AVR-LibC, Version 2.2.1, page install_tools(3avr) — and if you ever need to find it again, that's your source and version right there, mwah 💅✨ No cap, you're gonna build something iconic with this. 💖🎀🦋

📦 where this page comes from