git.rot13.org Git - simavr/blob - doc/manual/setupguide.tex

   1 \chapter{Setup Guide} \label{chapter:setup}
   2
   3 This section provides instructions on how to retrieve, compile and install
   4 \simavr on the GNU/Linux operating system.
   5
   6 \section{\simavr} \label{section:setup_simavr}
   7
   8 \subsection{Getting the source code}
   9
  10 The official home of \simavr is \url{https://github.com/buserror-uk/simavr}.
  11 Stable releases are published as git repository tags (direct downloads are
  12 available at \url{https://github.com/buserror-uk/simavr/tags}). To clone a local
  13 copy of the repository, run
  14
  15 \begin{verbatim}
  16 git clone git://github.com/buserror-uk/simavr.git
  17 \end{verbatim}
  18
  19 \subsection{Software Dependencies}
  20
  21 \emph{elfutils} is the only hard dependency at run-time. The name of this
  22 package may differ from distro to distro. For example, in Ubuntu the required
  23 package is called \emph{libelf-dev}.
  24
  25 At compile-time, \simavr additionally requires \emph{avr-libc} to complete its
  26 built-in AVR core definitions. It is assumed that further standard
  27 utilities (\emph{git}, \emph{gcc} or \emph{clang}, \emph{make}, etc \ldots) are
  28 already present.
  29
  30 \simavr has been tested with the following software versions:
  31
  32 \begin{itemize}
  33 \item Arch Linux x86\_64 and i686
  34 \item elfutils 0.154
  35 \item avr-libc 1.8.0
  36 \item gcc 4.7.1
  37 \item make 3.82
  38 \end{itemize}
  39
  40 Furthermore, the board\_usb example depends on libusb\_vhci and vhci\_hcd. For
  41 further details, see \emph{examples/board\_usb/README}. Note however that these
  42 are not required for a fully working \simavr build.
  43
  44 \subsection{Compilation and Installation}
  45
  46 \simavr's build system relies on standard makefiles. The simplest compilation
  47 boils down to the usual
  48
  49 \begin{verbatim}
  50 make
  51 make install
  52 \end{verbatim}
  53
  54 As usual, there are several variables to allow configuration of the build
  55 procedure. The most important ones are described in the following section:
  56
  57 \begin{itemize}
  58 \item AVR\_ROOT
  59
  60 The path to the system's \emph{avr-libc} installation.
  61
  62 While the default value
  63 should be correct for many systems, it may need to be set manually if the
  64 message 'WARNING \ldots did not compile, check your avr-gcc
  65 toolchain' appears during the build. For example, if iomxx0\_1.h is located at
  66 /usr/avr/include/avr/iomxx0\_1.h, AVR\_ROOT must be set to /usr/avr.
  67
  68 \item CFLAGS
  69
  70 The standard compiler flags variable.
  71
  72 It may be useful to modify CFLAGS for easier debugging (in which case
  73 optimizations should be disabled and debugging information enabled: -O0 -g).
  74 Additionally adding -DCONFIG\_SIMAVR\_TRACE=1 enables extra verbose output and
  75 extended execution tracing.
  76 \end{itemize}
  77
  78 These variables may be set either directly in Makefile.common, or alternatively
  79 can be passed to the make invocation (make AVR\_ROOT=/usr/avr DESTDIR=/usr
  80 install).
  81
  82 Installation is managed through the usual
  83 \begin{verbatim}
  84 make install
  85 \end{verbatim}
  86
  87 The DESTDIR variable can be used in association with the PREFIX variable to create a \simavr package. DESTDIR=/dest/dir
  88 PREFIX=/usr installs to /dest/dir but keeps the package configured to the standard prefix
  89 (/usr).
  90
  91 For development, we built and installed \simavr with the following procedure:
  92
  93 \begin{verbatim}
  94 make clean
  95 make AVR_ROOT=/usr/avr CFLAGS="-O0 -Wall -Wextra -g -fPIC \
  96   -std=gnu99 -Wno-sign-compare -Wno-unused-parameter"
  97 make DESTDIR="/usr" install
  98 \end{verbatim}