# Installing the GNU Tool Chain

Note:
  This discussion was taken directly from Rich Neswold's document. (See Acknowledgments).

  This discussion is Unix specific. [FIXME: troth/2002-08-13: we need a volunteer to add windows specific notes to these instructions.]

This chapter shows how to build and install a complete development environment for the AVR processors using the GNU toolset.

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 PREFIX

Note:
  Be 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 PATH

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

## Required Tools

- GNU Binutils
  http://sources.redhat.com/binutils/
  Installation

- GCC
  http://gcc.gnu.org/
  Installation

- AVR Libc
  http://savannah.gnu.org/projects/avr-libc/
  Installation

## Optional Tools

You can develop programs for AVR devices without the following tools. They may or may not be of use for you.

- uisp
  http://savannah.gnu.org/projects/uisp/
  Installation

- avrdude
  http://savannah.nongnu.org/projects/avrdude/
  Installation
  Usage Notes

- GDB
  http://sources.redhat.com/gdb/
  Installation

- Simulavr
  http://savannah.gnu.org/projects/simulavr/
  Installation

- AVaRice
  http://avarice.sourceforge.net/
  Installation

## 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`), 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 ``

with the version of the package you downloaded.

Note:
  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-avr

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.

    $ ../configure --prefix=$PREFIX --target=avr --disable-nls

If 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 `Makefile`s that are custom tailored to your platform. At this point, you can build the project.

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

## GCC for the AVR target

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
    $ make
    $ make install

To 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.

## 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 cvs, you will have to run the `reconf` script before using either of the build methods described below.

To build and install avr-libc:

    $ gunzip -c avr-libc-<version>.tar.gz
    $ cd avr-libc-<version>
    $ ./doconf
    $ ./domake
    $ cd build
    $ make install

Note:
  The `doconf` script will automatically use the `$PREFIX` environment variable if you have set and exported it.

Alternatively, you could do this (shown for consistency with `binutils` and `gcc`):

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

## UISP

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

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

## Avrdude

Note:
  It has been ported to windows (via cygwin) and linux. 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

## GDB for the AVR target

Gdb 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 install

Note:
  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

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

Automatically generated by Doxygen 1.4.1 on 13 Oct 2005.