Provided by: avr-libc_2.0.0+Atmel3.6.2-3_all bug

NAME

       install_tools - Building and Installing the GNU Tool Chain

       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.

Building and Installing under Linux, FreeBSD, and Others

       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/
          InstallationGCC
          http://gcc.gnu.org/
          InstallationAVR 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.

       • AVRDUDE
          http://savannah.nongnu.org/projects/avrdude/
          Installation
          Usage NotesGDB
          http://sources.redhat.com/gdb/
          InstallationSimulAVR
          http://savannah.gnu.org/projects/simulavr/
          InstallationAVaRICE
          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 <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-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
       Makefiles 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 --disable-libssp --with-dwarf2
       $ 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. (Starting with GCC 4.7 releases, these split files are no longer available
       though.)

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

       Optionally, generation of debug information can be requested with:

       $ gunzip -c avr-libc-<version>.tar.gz | tar xf -
       $ cd avr-libc-<version>
       $ ./configure --prefix=$PREFIX --build=`./config.guess` --host=avr   --with-debug-info=DEBUG_INFO
       $ make
       $ make install

       where DEBUG_INFO can be one of stabs, dwarf-2, or dwarf-4.

       The default is to not generate any debug information, which is suitable for binary
       distributions of avr-libc, where the user does not have the source code installed the
       debug information would refer to.

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

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

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.

       MinGW does provide somewhat of a POSIX environment, called MSYS, 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.

Tools Required for Building the Toolchain for Windows

       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.

       • MinGW
          Download the MinGW Automated Installer, 20100909 (or later)
         http://sourceforge.net/projects/mingw/files/Automated%20MinGW%20Installer/mingw-get-
         inst/mingw-get-inst-20100909/mingw-get-inst-20100909.exe/download

         • Run mingw-get-inst-20100909.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, and MPC are required to build GCC.

           GMP is a prequisite for building MPFR. Build GMP first.

           MPFR is a prerequisite for building MPC. Build MPFR second.

       • Build GMP for MinGW

         • Latest Version

         • http://gmplib.org/

         • Build script:

               ./configure  2>&1 | tee gmp-configure.log
               make         2>&1 | tee gmp-make.log
               make check   2>&1 | tee gmp-make-check.log
               make install 2>&1 | tee gmp-make-install.log

         • GMP headers will be installed under /usr/local/include and library installed under
           /usr/local/lib.

       • Build MPFR for MinGW

         • Latest Version

         • http://www.mpfr.org/

         • Build script:

               ./configure --with-gmp=/usr/local --disable-shared 2>&1 | tee mpfr-configure.log
               make         2>&1 | tee mpfr-make.log
               make check   2>&1 | tee mpfr-make-check.log
               make install 2>&1 | tee mpfr-make-install.log

         • MPFR headers will be installed under /usr/local/include and library installed under
           /usr/local/lib.

       • Build MPC for MinGW

         • Latest Version

         • http://www.multiprecision.org/

         • Build script:

               ./configure --with-gmp=/usr/local --with-mpfr=/usr/local --disable-shared 2>&1 | tee mpfr-configure.log
               make         2>&1 | tee mpfr-make.log
               make check   2>&1 | tee mpfr-make-check.log
               make install 2>&1 | tee mpfr-make-install.log

         • MPFR headers will be installed under /usr/local/include and library installed under
           /usr/local/lib.

       Note
           Doxygen is required to build AVR-LibC documentation.

           • Install Doxygen

             • Version 1.7.2

             • http://www.stack.nl/~dimitri/doxygen/

             • Download and install.

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

           • Install NetPBM

             • Version 10.27.0

             • From the GNUWin32 project: http://gnuwin32.sourceforge.net/packages.html

             • Download and install.

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

           • Install fig2dev

             • Version 3.2 patchlevel 5c

             • From WinFig 4.62: http://www.schmidt-web-berlin.de/winfig/

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

           • Install MiKTeX

             • Version 2.9

             • http://miktex.org/

             • Download and install.

           Ghostscript is required to build various documentation.

           • Install Ghostscript

             • Version 9.00

             • http://www.ghostscript.com

             • Download and install.

             • In the \bin subdirectory of the installaion, 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

       All directories in the PATH enviornment 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.

       • Binutils

         • Open source code pacakge 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             --with-gmp=/usr/local             --with-mpfr=/usr/local             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 pacakge 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               --with-gmp=/usr/local              --with-mpfr=/usr/local             --with-mpc=/usr/local              --prefix=$installdir               --target=$target              --enable-languages=c,c++                --with-dwarf2            --enable-doc             --with-docdir=$installdir/doc/$project            --disable-shared              --disable-libada              --disable-libssp              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-xml-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 pacakge 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

       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

         • Make

               make -k all install 2>&1 | tee simulavr-make.log
               make pdf install-pdf 2>&1 | tee simulavr-pdf-make.log