|
AVR-LibC
2.3.0
Standard C library for AVR-GCC
|
|
AVR-LibC Manual |
  |
AVR-LibC Sources |
|||
Main Page |
User Manual |
Library Reference |
FAQ |
Example Projects |
Index |
This chapter shows how to build and install, from source code, a complete development environment for the AVR processors using the GNU toolset. There are two main sections, one for Linux, FreeBSD, and other Unix-like operating systems, and another section for Windows.
Project Home: https://sourceware.org/binutils
Source Downloads: https://sourceware.org/pub/binutils/releases
FTP: anonymous@ftp.gnu.org/gnu/binutils
Git: git://sourceware.org/git/binutils-gdb.git
GitHub Mirror: https://github.com/bminor/binutils-gdb
Installation
Project Home https://gcc.gnu.org
Mirrors Site: https://gcc.gnu.org/mirrors.html
FTP: anonymous@ftp.gnu.org/gnu/gcc
Git: git://gcc.gnu.org/git/gcc.git
GitHub Mirror: https://github.com/gcc-mirror/gcc
Installation: https://gcc.gnu.org/install
Installation
You can develop programs for AVR devices without the following tools. They may or may not be of use for you.
Git: https://github.com/avrdudes/avrdude.git
GitHub: https://github.com/avrdudes/avrdude
Installation
The GNU Debugger GDB is hosted together with GNU Binutils. When you don't want or need GDB, you can configure Binutils with --disable-gdb.
GitHub: https://github.com/sprintersb/atest
Installation
AVRtest is an AVR core simulator that can be used to run the avr-gcc testsuite. It can also be used to run parts of the AVR-LibC testsuite. For details, see the README.
The default behaviour for most of these tools is to install every thing under the /usr/local directory. In order to keep the AVR tools separate from the base system, it is usually better to install everything into /usr/local/avr. If the /usr/local/avr directory does not exist, you should create it before trying to install anything. You will need root access to install there. If you don't have or want root access to the system, you can alternatively install in your home directory, for example, in $HOME/local/avr. Where you install is a completely arbitrary decision, but should be consistent for all the tools.
It is usually the best to use the latest released version of each of the tools.
CC set to anything other than avr-gcc in your environment, this will cause the configure script to fail. It is best to not have CC set at all.There are scripts that can simplify the process of building an AVR toolchain for Linux, and/or for Windows in Canadian cross configuration.
In order to be able to build and install the compiler and other tools, the build machine requires some software packages. The Debian package list is something like:
You specify the installation directory by using the --prefix=dir option with the configure script. It is important to install all the AVR tools in the same directory, or some of the tools will not work correctly. To ensure consistency and simplify the discussion, we will use $PREFIX to refer to whatever directory you wish to install in. You can set this as an environment variable if you wish as such (using a Bourne-like shell):
$ PREFIX=$HOME/local/avr $ export PREFIX
PATH environment variable 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
The instructions below build Binutils, GCC and AVR-LibC outside of the source tree, because:
The instructions below assume that you have 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>
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.
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
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.
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.
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
When you want to build and install with extra options, you can for example:
$ make CFLAGS="-Werror" CCASFLAGS="-Werror" $ make install prefix=/home/me/install/my-avr-gcc
In order to build the examples:
$ # in ./build/doc/examples $ make all-examples $ make example-largedemo # etc.
Additional prerequisites:
fig2dev from the Xfig projectpdflatex When fig2dev is not present on the system, one way is to build it from source:
$ wget https://sourceforge.net/projects/mcj/files/fig2dev-3.2.9a.tar.xz/download -O fig2dev-3.2.9a.tar.xz $ tar xfJ fig2dev-3.2.9a.tar.xz
and then configure, make and install as usual.
For building the documentation, Doxygen v1.9.6 is required. Here are the steps for building and installing it in a non-system location (so that no root permissions are needed). The first step is to get the required Doxygen source version:
$ # in ./source $ git clone --branch Release_1_9_6 --depth 1 https://github.com/doxygen/doxygen.git doxygen-1.9.6
Then configure and build it. The installation is in some folder /someplace which you can adjust as you like:
$ # in ./build $ mkdir doxygen-1.9.6 $ cd doxygen-1.9.6 $ cmake -DCMAKE_INSTALL_PREFIX:PATH=/someplace/doxygen-1.9.6 ../../source/doxygen-1.9.6 $ make $ make install
There are several ways to provide Doxygen 1.9.6 to AVR-LibC:
/someplace/doxygen-1.9.6/bin to PATH prior to configuring AVR-LibC.The AVR-LibC configure script will print the used Doxygen version. Make sure it is actually Doxygen 1.9.6!
In order to build the documentation, you can add --enable-doc to the AVR-LibC configure options, or you can invoke building the documentation by hand:
$ # in ./build/avr-libc-<version>/doc/api $ make html $ make dox-pdf $ make install-dox-html
Note that Doxygen doesn't care about dependencies, thus when you made changes to the sources and want to re-build the documentation, better run make clean in build/avr-libc-<version>/doc/api before building the doc. Moreover, the Doxygen version is highly critical, and the exact version of Doxygen v1.9.6 is recommended.
AVRDUDE 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
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 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
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.
Building AVRtest is done by running its Makefile. No configure script is required. To get the sources and make:
$ git clone https://github.com/sprintersb/atest.git <folder> $ cd <folder> $ make
The Makefile will build some object files like exit-atmega128.o which require an avr-gcc that supports such devices. There are also pre-built AVRtest binaries for Windows.
These install notes are not applicable to avarice-1.5 or older. You probably don't want to use anything that old anyway 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
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 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.
MinGW does provide somewhat of a POSIX environment, called MSYS, that allows you to build Unix and Linux applications as they would normally do, with a configure step and a make step. Cygwin also provides such an environment. This means that building the AVR toolchain is very similar to how it is built in Linux, described above. The main differences are in what the PATH environment variable gets set to, pathname differences, and the tools that are required to build the projects under Windows. We'll take a look at the tools next.
These are the tools that are currently used to build an AVR tool chain. This list may change, either the version of the tools, or the tools themselves, as improvements are made.
Download the MinGW Automated Installer, 2013-10-04 (or later) https://sourceforge.net/projects/mingw/files
mingw-get-setup.exeGMP, 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.
Doxygen is required to build AVR-LibC documentation.
fig2dev is required to build graphics in the AVR-LibC documentation.
MikTeX is required to build various documentation.
Set the TEMP and TMP environment variables to c:\\temp or to the short filename version. This helps to avoid NTVDM errors during building.
All directories in the PATH environment variable should be specified using their short filename (8.3) version. This will also help to avoid NTVDM errors during building. These short filenames can be specific to each machine.
Build the tools below in MinGW/MSYS.
CFLAGS=-D__USE_MINGW_ACCESS \
../$archivedir/configure \
--prefix=$installdir \
--target=avr \
--disable-nls \
--enable-doc \
--datadir=$installdir/doc/binutils \
2>&1 | tee binutils-configure.logmake all html install install-html 2>&1 | tee binutils-make.log
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.logmake all html install 2>&1 | tee $package-make.log
./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.logmake all install 2>&1 | tee $package-make.log
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 \
--prefix=$installdir \
--datadir=$installdir \
--sysconfdir=$installdir/bin \
--enable-doc \
--disable-versioned-doc \
2>&1 | tee $package-configure.logmake -k all install 2>&1 | tee $package-make.log
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.logmake all install 2>&1 | tee $package-make.log
./configure \
--prefix=$installdir \
--infodir=$installdir/info \
--mandir=$installdir/man \
2>&1 | tee $package-configure.logmake all install 2>&1 | tee $package-make.log
Build the tools below in Cygwin.
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 "
../$archivedir/configure \
--prefix=$installdir \
--datadir=$installdir/doc \
--mandir=$installdir/man \
--infodir=$installdir/info \
2>&1 | tee avarice-configure.logmake all install 2>&1 | tee avarice-make.log
export LDFLAGS="-static"
../$archivedir/configure \
--prefix=$installdir \
--datadir=$installdir \
--disable-tests \
--disable-versioned-doc \
2>&1 | tee simulavr-configure.logmake -k all install 2>&1 | tee simulavr-make.log make pdf install-pdf 2>&1 | tee simulavr-pdf-make.log
It is also possible to build avr-gcc for host Windows on a Linux build system. Suppose you have installed a i686-w64-mingw32-gcc toolchain that can compile code to run on host=i686-w64-mingw32. Then the steps to build a toolchain for Windows are:
avr-gcc --versionprints the compiler version according to the used GCC sources. 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.
--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)../build/binutils-<version>-avr-mingw32 to build Binutils and --prefix=$PREFIX-mingw32 as install path.--build=x86_64-pc-linux-gnu --host=i686-w64-mingw32This 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.$ # 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.
Most of the sources of the projects above are now managed with the git distributed version-control tools. 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.
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.
--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.
--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>
1.9.6