doc/manual/en/compiling.tex

   1 \chapter{Compiling XCSoar}\label{cha:compiling}
   2
   3 The \texttt{make} command is used to launch the XCSoar build process.
   4 You can learn more about the build system internals in chapter
   5 \ref{cha:build}.
   6
   7 Most of this chapter describes how to build XCSoar on Linux, with
   8 examples for Debian/Ubuntu.  A cross-compiler is used to build
   9 binaries for other operating systems (for example Android and
  10 Windows).
  11
  12 \section{Getting the Source Code}
  13
  14 The XCSoar source code is managed with
  15 \href{http://git-scm.com/}{git}.  It can be downloaded with the
  16 following command:
  17
  18 \begin{verbatim*}
  19 git clone git://git.xcsoar.org/xcsoar/master/xcsoar.git
  20 \end{verbatim*}
  21
  22 To update your repository, type:
  23
  24 \begin{verbatim*}
  25 git pull
  26 \end{verbatim*}
  27
  28 For more information, please read to the git documentation.
  29
  30 \section{Requirements}
  31
  32 The following is needed for all targets:
  33
  34 \begin{itemize}
  35 \item GNU make
  36 \item GNU compiler collection (\texttt{gcc}), version 4.6.2 or later
  37   or clang/LLVM 3.1 (with "make CLANG=y")
  38 \item GNU gettext
  39 \item \href{http://librsvg.sourceforge.net/)}{rsvg}
  40 \item \href{http://www.imagemagick.org/}{ImageMagick 6.4}
  41 \item \href{http://xmlsoft.org/XSLT/xsltproc2.html}{xsltproc}
  42 \item Perl and XML::Parser
  43 \end{itemize}
  44
  45 The following command installs these on Debian:
  46
  47 \begin{verbatim*}
  48 apt-get install make \
  49   librsvg2-bin xsltproc \
  50   imagemagick gettext
  51 \end{verbatim*}
  52
  53 \section{Target-specific Build Instructions}
  54
  55 \subsection{Compiling for Linux/UNIX}
  56
  57 The following additional packages are needed to build for Linux and
  58 similar operating systems:
  59
  60 \begin{itemize}
  61 \item \href{http://www.boost.org/}{Boost}
  62 \item \href{http://www.zlib.net/}{zlib}
  63 \item \href{http://curl.haxx.se/}{CURL}
  64 \item \href{http://www.libsdl.org/}{SDL}
  65 \item \href{http://www.libsdl.org/projects/SDL\_ttf/}{SDL\_ttf}
  66 \item \href{http://www.libpng.org/}{libpng}
  67 \item \href{http://libjpeg.sourceforge.net/}{libjpeg}
  68 \item OpenGL (Mesa)
  69 \item to run XCSoar, you need one of the following fonts (Debian
  70   package): DejaVu (\texttt{ttf-dejavu}), Droid (\texttt{ttf-droid}),
  71   Freefont (\texttt{ttf-freefont})
  72 \end{itemize}
  73
  74 The following command installs these on Debian:
  75
  76 \begin{verbatim*}
  77 apt-get install make g++ \
  78   libboost-dev zlib1g-dev \
  79   libsdl1.2-dev libsdl-ttf2.0-dev \
  80   libpng-dev libjpeg-dev \
  81   libcurl4-openssl-dev \
  82   libxml-parser-perl \
  83   librsvg2-bin xsltproc \
  84   imagemagick gettext \
  85   ttf-dejavu
  86 \end{verbatim*}
  87
  88 To compile, run:
  89
  90 \begin{verbatim*}
  91 make
  92 \end{verbatim*}
  93
  94 You may specify one of the following targets with \texttt{TARGET=x}:
  95
  96 \begin{tabular}{lp{8cm}}
  97
  98 \texttt{UNIX} & regular build (the default setting) \\
  99
 100 \texttt{UNIX32} & generate 32 bit binary \\
 101
 102 \texttt{UNIX64} & generate 64 bit binary \\
 103
 104 \texttt{OPT} & alias for UNIX with optimisation and no debugging \\
 105
 106 \end{tabular}
 107
 108 \subsection{Compiling for Android}
 109
 110 For Android, you need:
 111
 112 \begin{itemize}
 113 \item \href{http://developer.android.com/sdk/}{Android SDK level 16}
 114 \item \href{http://developer.android.com/sdk/ndk/}{Android NDK r8e}
 115 \item \href{http://www.vorbis.com/}{Ogg Vorbis}
 116 \item \href{http://ant.apache.org/}{Apache Ant}
 117 \end{itemize}
 118
 119 The \texttt{Makefile} assumes that the Android SDK is installed in
 120 \verb|~/opt/android-sdk-linux_x86| and the NDK is installed in
 121 \verb|~/opt/android-ndk-r8e|.  You can use the options
 122 \verb|ANDROID_SDK| and \verb|ANDROID_NDK| to override these paths.
 123
 124 To compile, run:
 125
 126 \begin{verbatim*}
 127 make TARGET=ANDROID
 128 \end{verbatim*}
 129
 130 Use one of the following targets:
 131
 132 \begin{tabular}{lp{8cm}}
 133
 134 \texttt{ANDROID} & for ARMv6 CPUs \\
 135
 136 \texttt{ANDROID7} & for ARMv7 CPUs \\
 137
 138 \texttt{ANDROID7NEON} & with
 139 \href{http://www.arm.com/products/processors/technologies/neon.php}{NEON}
 140 extension \\
 141
 142 \texttt{ANDROID86} & for x86 CPUs \\
 143
 144 \texttt{ANDROIDMIPS} & for MIPS CPUs \\
 145
 146 \texttt{ANDROIDFAT} & "fat" package for all supported CPUs \\
 147
 148 \end{tabular}
 149
 150 \subsubsection{Enabling IOIO Support}
 151
 152 IOIO support must be enabled explicitly, because it depends on
 153 IOIOLib.  First get the IOIOLib source code:
 154
 155 \begin{verbatim*}
 156 git clone git://github.com/ytai/ioio.git
 157 \end{verbatim*}
 158
 159 Now add the parameter \verb|IOIOLIB_DIR| pointing to this repository:
 160
 161 \begin{verbatim*}
 162 make TARGET=ANDROID clean
 163 make TARGET=ANDROID \
 164  IOIOLIB_DIR=/usr/src/git/ioio/software/IOIOLib
 165 \end{verbatim*}
 166
 167 The first command may be necessary if the output directory already
 168 contains binaries without IOIO support.
 169
 170 \subsection{Compiling for Windows}
 171
 172 To cross-compile to (desktop) Windows, you need the mingw-w64 version
 173 of gcc:
 174
 175  http://mingw-w64.sourceforge.net/
 176
 177 To compile, run one of the following:
 178
 179 \begin{verbatim*}
 180 make TARGET=PC
 181 \end{verbatim*}
 182
 183 Use one of the following targets:
 184
 185 \begin{tabular}{lp{8cm}}
 186
 187 \texttt{PC} & 32 bit Windows (i686) \\
 188
 189 \texttt{WIN64} & Windows x64 (amd64 / x86-64) \\
 190
 191 \texttt{WINE} & WineLib (experimental) \\
 192
 193 \texttt{CYGWIN} & Windows build with Cygwin (experimental) \\
 194
 195 \end{tabular}
 196
 197 \subsection{Compiling for Windows CE}
 198
 199 For PocketPC / Windows CE / Windows Mobile, you need mingw32ce:
 200
 201 \begin{itemize}
 202 \item \href{http://max.kellermann.name/projects/cegcc/}{mingw32ce}
 203 \end{itemize}
 204
 205 To compile, run:
 206
 207 \begin{verbatim*}
 208 make TARGET=WM5X
 209 \end{verbatim*}
 210
 211 Use one of the following targets:
 212
 213 \begin{tabular}{lp{8cm}}
 214
 215 \texttt{PPC2000} & PocketPC 2000 / Windows CE 3.0 \\
 216
 217 \texttt{PPC2003} & PocketPC 2003 / Windows CE 4.0 \\
 218
 219 \texttt{PPC2003X} & for XScale CPUs \\
 220
 221 \texttt{WM5} & Windows Mobile / Windows CE 5.0 \\
 222
 223 \texttt{WM5X} & for XScale CPUs \\
 224
 225 \texttt{ALTAIR} & for Triadis Altair \\
 226
 227 \end{tabular}
 228
 229 \subsection{Compiling for Mac OS X}
 230
 231 For Mac OS X, you need:
 232
 233 \begin{itemize}
 234 \item GCC 4.6.2 or newer (http://hpc.sourceforge.net/, or homebrew, or Macports)
 235 \item \href{http://www.boost.org/}{Boost}
 236 \item \href{http://www.zlib.net/}{zlib}
 237 \item \href{http://curl.haxx.se/}{CURL}
 238 \item \href{http://www.libsdl.org/}{SDL}
 239 \item \href{http://www.libsdl.org/projects/SDL\_ttf/}{SDL\_ttf}
 240 \item \href{http://www.libpng.org/}{libpng}
 241 \item \href{http://libjpeg.sourceforge.net/}{libjpeg}
 242 \item \href{http://icns.sourceforge.net/}{libicns}
 243 \end{itemize}
 244
 245 \subsection{Compiling for the Raspberry Pi}
 246
 247 To compile, run:
 248
 249 \begin{verbatim*}
 250 make TARGET=PI
 251 \end{verbatim*}
 252
 253 This target is only used for cross-compiling on a (desktop) computer.
 254 If you compile on the Raspberry Pi, the default target will
 255 auto-detect the Pi.
 256
 257 \subsection{Compiling for Kobo E-book Readers}
 258
 259 To compile, run:
 260
 261 \begin{verbatim*}
 262 make TARGET=KOBO
 263 \end{verbatim*}
 264
 265 \section{Options}
 266
 267 \subsection{Parallel Build}
 268
 269 Most contemporary computers have multiple CPU cores.  To take
 270 advantage of these, use the \texttt{make -j} option:
 271
 272 \begin{verbatim*}
 273 make -j12
 274 \end{verbatim*}
 275
 276 This command launches 12 compiler processes at the same time.
 277
 278 Rule of thumb: choose a number that is slightly larger than the number
 279 of CPU cores in your computer.  12 is a good choice for a computer
 280 with 8 CPU cores.
 281
 282 \subsection{Optimised Build}
 283
 284 By default, debugging is enabled and compiler optimisations are
 285 disabled.  The resulting binaries are very slow.  During development,
 286 that is helpful, because it catches more bugs.
 287
 288 To produce optimised binaries, use the option \texttt{DEBUG}:
 289
 290 \begin{verbatim*}
 291 make DEBUG=n
 292 \end{verbatim*}
 293
 294 Be sure to clean the output directory before you change the
 295 \texttt{DEBUG} setting, because debug and non-debug output files are
 296 not compatible.
 297
 298 The convenience target \texttt{OPT} is a shortcut for:
 299
 300 \begin{verbatim*}
 301 TARGET=UNIX DEBUG=n TARGET_OUTPUT_DIR=output/OPT
 302 \end{verbatim*}
 303
 304 It allows building both debug and non-debug incrementally, because two
 305 different output directories are used.