1
/* Copyright (c) 2002, Theodore Roth
4
Redistribution and use in source and binary forms, with or without
5
modification, are permitted provided that the following conditions are met:
7
* Redistributions of source code must retain the above copyright
8
notice, this list of conditions and the following disclaimer.
9
* Redistributions in binary form must reproduce the above copyright
10
notice, this list of conditions and the following disclaimer in
11
the documentation and/or other materials provided with the
14
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
15
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
18
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
19
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
20
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
21
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
22
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
23
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
24
POSSIBILITY OF SUCH DAMAGE. */
26
/* $Id: tools-install.dox,v 1.9.4.1 2005/01/24 07:59:14 joerg_wunsch Exp $ */
28
/** \page install_tools Installing the GNU Tool Chain
30
\addindex installation
32
\note This discussion was taken directly from Rich Neswold's document. (See
35
\note This discussion is Unix specific. [FIXME: troth/2002-08-13: we need a
36
volunteer to add windows specific notes to these instructions.]
38
This chapter shows how to build and install a complete development environment
39
for the AVR processors using the GNU toolset.
41
The default behaviour for most of these tools is to install every thing under
42
the \c /usr/local directory. In order to keep the AVR tools separate from the
43
base system, it is usually better to install everything into
44
<tt>/usr/local/avr</tt>. If the \c /usr/local/avr directory does not exist,
45
you should create it before trying to install anything. You will need
46
<tt>root</tt> access to install there. If you don't have root access to the
47
system, you can alternatively install in your home directory, for example, in
48
<tt>$HOME/local/avr</tt>. Where you install is a completely arbitrary
49
decision, but should be consistent for all the tools.
51
You specify the installation directory by using the <tt>--prefix=dir</tt>
52
option with the \c configure script. It is important to install all the AVR
53
tools in the same directory or some of the tools will not work correctly. To
54
ensure consistency and simplify the discussion, we will use \c $PREFIX to
55
refer to whatever directory you wish to install in. You can set this as an
56
environment variable if you wish as such (using a Bourne-like shell):
61
$ PREFIX=$HOME/local/avr
66
\anchor path \note Be sure that you have your \c PATH environment variable set
67
to search the directory you install everything in \e before you start
68
installing anything. For example, if you use <tt>--prefix=$PREFIX</tt>, you
69
must have \c $PREFIX/bin in your exported <tt>PATH</tt>. As such:
72
$ PATH=$PATH:$PREFIX/bin
76
\warning If you have \c CC set to anything other than \c avr-gcc in your
77
environment, this will cause the configure script to fail. It is best to not
78
have \c CC set at all.
80
\note It is usually the best to use the latest released version of
83
\section required_tools Required Tools
84
\addindex tools, required
86
- <b>GNU Binutils</b><br>
87
http://sources.redhat.com/binutils/ <br>
88
\ref install_avr_binutils "Installation"
91
http://gcc.gnu.org/ <br>
92
\ref install_avr_gcc "Installation"
95
http://savannah.gnu.org/projects/avr-libc/ <br>
96
\ref install_avr_libc "Installation"<br>
98
\section optional_tools Optional Tools
99
\addindex tools, optional
101
You can develop programs for AVR devices without the following tools. They may
102
or may not be of use for you.
105
http://savannah.gnu.org/projects/uisp/<br>
106
\ref install_uisp "Installation"
109
http://savannah.nongnu.org/projects/avrdude/ <br>
110
\ref install_avrprog "Installation" <br>
111
\ref using_avrprog "Usage Notes"
114
http://sources.redhat.com/gdb/ <br>
115
\ref install_gdb "Installation"<br>
117
- <b>Simulavr</b><br>
118
http://savannah.gnu.org/projects/simulavr/ <br>
119
\ref install_simulavr "Installation"
122
http://avarice.sourceforge.net/ <br>
123
\ref install_avarice "Installation"<br>
125
\section install_avr_binutils GNU Binutils for the AVR target
126
\addindex installation, binutils
128
The <tt><b>binutils</b></tt> package provides all the low-level utilities
129
needed in building and manipulating object files. Once installed, your
130
environment will have an AVR assembler (<tt>avr-as</tt>), linker
131
(<tt>avr-ld</tt>), and librarian (<tt>avr-ar</tt> and <tt>avr-ranlib</tt>).
132
In addition, you get tools which extract data from object files
133
(<tt>avr-objcopy</tt>), dissassemble object file information
134
(<tt>avr-objdump</tt>), and strip information from object files
135
(<tt>avr-strip</tt>). Before we can build the C compiler, these tools need to
138
Download and unpack the source files:
141
$ bunzip2 -c binutils-<version>.tar.bz2 | tar xf -
142
$ cd binutils-<version>
145
\note Replace \c <version> with the version of the package you downloaded.
147
\note If you obtained a gzip compressed file (.gz), use <tt>gunzip</tt>
148
instead of <tt>bunzip2</tt>.
150
It is usually a good idea to configure and build <tt><b>binutils</b></tt> in a
151
subdirectory so as not to pollute the source with the compiled files. This is
152
recommended by the <tt><b>binutils</b></tt> developers.
159
The next step is to configure and build the tools. This is done by supplying
160
arguments to the <tt>configure</tt> script that enable the AVR-specific
164
$ ../configure --prefix=$PREFIX --target=avr --disable-nls
167
If you don't specify the <tt>--prefix</tt> option, the tools will get
168
installed in the \c /usr/local hierarchy (i.e. the binaries will get installed
169
in <tt>/usr/local/bin</tt>, the info pages get installed in
170
<tt>/usr/local/info</tt>, etc.) Since these tools are changing frequently, It
171
is preferrable to put them in a location that is easily removed.
173
When <tt>configure</tt> is run, it generates a lot of messages while it
174
determines what is available on your operating system. When it finishes, it
175
will have created several <tt>Makefile</tt>s that are custom tailored to your
176
platform. At this point, you can build the project.
182
\note BSD users should note that the project's <tt>Makefile</tt> uses GNU
183
<tt>make</tt> syntax. This means FreeBSD users may need to build the tools by
184
using <tt>gmake</tt>.
186
If the tools compiled cleanly, you're ready to install them. If you specified
187
a destination that isn't owned by your account, you'll need <tt>root</tt>
188
access to install them. To install:
194
You should now have the programs from binutils installed into
195
<tt>$PREFIX/bin</tt>. Don't forget to \ref path "set your PATH" environment
196
variable before going to build avr-gcc.
198
\section install_avr_gcc GCC for the AVR target
199
\addindex installation, gcc
201
\warning You <em><b>must</b></em> install
202
\ref install_avr_binutils "avr-binutils" and make sure your
203
\ref path "path is set" properly before installing avr-gcc.
205
The steps to build \c avr-gcc are essentially same as for
206
\ref install_avr_binutils "binutils":
209
$ bunzip2 -c gcc-<version>.tar.bz2 | tar xf -
213
$ ../configure --prefix=$PREFIX --target=avr --enable-languages=c,c++ \
219
To save your self some download time, you can alternatively download only the
220
<tt>gcc-core-\<version\>.tar.bz2</tt> and <tt>gcc-c++-\<version\>.tar.bz2</tt>
221
parts of the gcc. Also, if you don't need C++ support, you only need the core
222
part and should only enable the C language support.
224
\note Early versions of these tools did not support C++.
226
\note The stdc++ libs are not included with C++ for AVR due to the size
227
limitations of the devices.
229
\section install_avr_libc AVR Libc
230
\addindex installation, avr-libc
232
\warning You <em><b>must</b></em> install
233
\ref install_avr_binutils "avr-binutils",
234
\ref install_avr_gcc "avr-gcc" and make sure your
235
\ref path "path is set" properly before installing avr-libc.
237
\note If you have obtained the latest avr-libc from cvs, you will have to run
238
the \c reconf script before using either of the build methods described below.
240
To build and install avr-libc:
243
$ gunzip -c avr-libc-<version>.tar.gz
244
$ cd avr-libc-<version>
251
\note The \c doconf script will automatically use the \c $PREFIX environment
252
variable if you have set and exported it.
254
Alternatively, you could do this (shown for consistency with \c binutils and
258
$ gunzip -c avr-libc-<version>.tar.gz | tar xf -
259
$ cd avr-libc-<version>
262
$ ../configure --prefix=$PREFIX
267
\section install_uisp UISP
268
\addindex installation, uisp
270
Uisp also uses the \c configure system, so to build and install:
273
$ gunzip -c uisp-<version>.tar.gz | tar xf -
277
$ ../configure --prefix=$PREFIX
282
\section install_avrprog Avrdude
283
\addindex installation, avrprog
284
\addindex installation, avrdude
286
\note It has been ported to windows (via cygwin) and linux. Other unix systems
287
should be trivial to port to.
289
<tt><b>avrdude</b></tt> is part of the FreeBSD ports system. To install it,
290
simply do the following:
293
# cd /usr/ports/devel/avrdude
297
\note Installation into the default location usually requires root
298
permissions. However, running the program only requires access
299
permissions to the appropriate \c ppi(4) device.
301
Building and installing on other systems should use the \c configure system,
305
$ gunzip -c avrdude-<version>.tar.gz | tar xf -
306
$ cd avrdude-<version>
309
$ ../configure --prefix=$PREFIX
314
\section install_gdb GDB for the AVR target
315
\addindex Installation, gdb
317
Gdb also uses the \c configure system, so to build and install:
320
$ bunzip2 -c gdb-<version>.tar.bz2 | tar xf -
324
$ ../configure --prefix=$PREFIX --target=avr
329
\note If you are planning on using <tt>avr-gdb</tt>, you will probably want to
330
install either \ref install_simulavr "simulavr" or
331
\ref install_avarice "avarice" since avr-gdb needs one of these to run as a
332
a remote target backend.
334
\section install_simulavr Simulavr
335
\addindex installation, simulavr
337
Simulavr also uses the \c configure system, so to build and install:
340
$ gunzip -c simulavr-<version>.tar.gz | tar xf -
341
$ cd simulavr-<version>
344
$ ../configure --prefix=$PREFIX
349
\note You might want to have already installed
350
\ref install_avr_binutils "avr-binutils",
351
\ref install_avr_gcc "avr-gcc" and
352
\ref install_avr_libc "avr-libc"
353
if you want to have the test programs built in the simulavr source.
355
\section install_avarice AVaRice
356
\addindex installation, avarice
358
\note These install notes are not applicable to avarice-1.5 or older. You
359
probably don't want to use anything that old anyways since there have been
360
many improvements and bug fixes since the 1.5 release.
362
AVaRice also uses the \c configure system, so to build and install:
365
$ gunzip -c avarice-<version>.tar.gz | tar xf -
366
$ cd avarice-<version>
369
$ ../configure --prefix=$PREFIX
374
\note AVaRice uses the bfd library for accessing various binary file formats.
375
You may need to tell the configure script where to find the lib and headers
376
for the link to work. This is usually done by invoking the configure script
377
like this (Replace <tt>\<hdr_path\></tt> with the path to the \c bfd.h file on
378
your system. Replace <tt>\<lib_path\></tt> with the path to \c libbfd.a on your
382
$ CPPFLAGS=-I<hdr_path> LDFLAGS=-L<lib_path> ../configure --prefix=$PREFIX
added
removed
doc/api/tools-install.dox
