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.
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 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.
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 PREFIXBe sure that you have your 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 PATHWarning:
If you have 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.
Note:
It is usually the best to use the latest
released version of each of the tools.
You can develop programs
for AVR devices without the following tools. They may or may not be of use for
you.
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), dissassemble 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:
$ bunzip2 -c binutils-<version>.tar.bz2 | tar xf -$ cd binutils-<version>Note:
Replace <version> with the version of the package you
downloaded.
If
you obtained a gzip compressed file (.gz), use gunzip instead of bunzip2.
It is
usually a good idea to configure and build binutils in a subdirectory so as not to
pollute the source with the compiled files. This is recommended by the binutils developers.
$ mkdir obj-avr$ cd obj-avrThe 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.
$ ../configure --prefix=$PREFIX --target=avr --disable-nlsIf you don't specify the --prefix option, the tools will get
installed in the /usr/local hierarchy (i.e. the binaries will get
installed in /usr/local/bin, the info pages get installed in /usr/local/info, etc.) Since these tools are
changing frequently, It is preferrable to put them in a location that is easily
removed.
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. At this point, you can build the project.
$ makeNote:
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 installYou 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.
Note:
The official version of binutils might lack
support for recent AVR devices. A patch that adds more AVR types can be found
at http://www.freebsd.org/cgi/cvsweb.cgi/ports/devel/avr-binutils/files/patch-newdevices
Warning:
You must install avr-binutils and make sure your path is set properly before installing avr-gcc.
The steps
to build avr-gcc
are essentially same as for binutils:
$ bunzip2 -c gcc-<version>.tar.bz2 | tar xf -$ cd gcc-<version>$ mkdir obj-avr$ cd obj-avr$ ../configure --prefix=$PREFIX --target=avr --enable-languages=c,c++ \ --disable-nls --disable-libssp --with-dwarf2$ make$ make installTo save your self some
download time, you can alternatively download only the gcc-core-<version>.tar.bz2 and gcc-c++-<version>.tar.bz2 parts of the gcc. Also, if you
don't need C++ support, you only need the core part and should only enable the
C language support.
Note:
Early versions of these tools did not support
C++.
The
stdc++ libs are not included with C++ for AVR due to the size limitations of
the devices.
The
official version of GCC might lack support for recent AVR devices. A patch that
adds more AVR types can be found at http://www.freebsd.org/cgi/cvsweb.cgi/ports/devel/avr-gcc/files/patch-newdevices
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
cvs, you will have to run the bootstrap script before using either of the build
methods described below.
To build
and install avr-libc:
$ gunzip -c avr-libc-<version>.tar.gz | tar xf -$ cd avr-libc-<version>$ ./configure --prefix=$PREFIX --build=`./config.guess` --host=avr$ make$ make installNote:
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 installNote:
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 installGDB also uses the configure system, so to build and install:
$ bunzip2 -c gdb-<version>.tar.bz2 | tar xf -$ cd gdb-<version>$ mkdir obj-avr$ cd obj-avr$ ../configure --prefix=$PREFIX --target=avr$ make$ make installNote:
If you are planning on using avr-gdb, you will probably want to install
either simulavr
or avarice since avr-gdb needs one of these to
run as a a remote target backend.
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 installNote:
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.
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 installNote:
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=$PREFIXBuilding
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/MSYS. 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/MSYS 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/MSYS 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/MSYS does provide
somewhat of a POSIX environment that allows you to build Unix and Linux
applications as they woud 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 WinAVR 20070525 (or later). This
list may change, either the version of the tools, or the tools themselves, as
improvements are made.