Compiling XCSoar¶
The Build System¶
A big plain Makefile
is used to control the XCSoar build. GNU
extensions are allowed.
This chapter describes the internals of our build system.
Linker parameters¶
The following variables (or variable suffixes) appear in the
Makefile
(conforming to automake
conventions):
LDFLAGS
: Linker flags, such as-static
or-Wl,...
, but not-l
.LDLIBS
: All-l
flags, e.g.-lGL
.LDADD
: Path names of static libraries, e.g./usr/lib/libz.a
.
Search directories (-L
) are technically linker “flags”, but they
are allowed in LDLIBS
, too.
Compiling XCSoar on Linux¶
The make
command is used to launch the XCSoar build process.
Most of this chapter describes how to build XCSoar on Linux, with examples for Debian/Ubuntu. A cross-compiler is used to build binaries for other operating systems (for example Android and Windows).
Getting the Source Code¶
The XCSoar source code is managed with git. It can be downloaded with the following command:
git clone https://github.com/XCSoar/XCSoar
To update your repository, type:
git pull
To update third-party libraries used by XCSoar (such as Boost), type:
git submodule update --init --recursive
For more information, please read to the git documentation.
Requirements¶
The following is needed for all targets:
GNU make
GNU compiler collection (
gcc
), version 10 or later or clang/LLVM 10 (with “make CLANG=y”)GNU gettext
Perl
The following command installs these on Debian:
sudo apt-get install make \
librsvg2-bin xsltproc \
imagemagick gettext sox \
git quilt zip \
m4 automake
Target-specific Build Instructions¶
Compiling for Linux/UNIX¶
The following additional packages are needed to build for Linux and similar operating systems:
libinput (not required when using Wayland or on the KOBO)
OpenGL (Mesa)
to run XCSoar, you need one of the following fonts (Debian package): DejaVu (
fonts-dejavu
), Roboto (fonts-roboto
), Droid (fonts-droid
), Freefont (fonts-freefont-ttf
)
The following command installs these on Debian:
sudo apt-get install make g++ zlib1g-dev \
libfmt-dev \
libdbus-1-dev \
libsodium-dev \
libfreetype6-dev \
libpng-dev libjpeg-dev \
libtiff5-dev libgeotiff-dev \
libc-ares-dev \
libcurl4-openssl-dev \
libssl-dev \
libc-ares-dev \
liblua5.4-dev \
libxml-parser-perl \
libasound2-dev \
librsvg2-bin xsltproc \
imagemagick gettext \
mesa-common-dev libgl1-mesa-dev libegl1-mesa-dev \
libinput-dev \
fonts-dejavu
To compile, run:
make
You may specify one of the following targets with TARGET=x
:
|
regular build (the default setting) |
|
generate 32 bit binary |
|
generate 64 bit binary |
|
alias for UNIX with optimisation and no debugging |
Compiling for Android¶
For Android, you need:
On Debian:
sudo apt-get install
default-jdk-headless \
vorbis-tools \
adb
The required Android SDK components are:
Android SDK Build-Tools 33.0.2
SDK Platform 33
These can be installed from the Android Studio SDK Manager, or using the SDK command line tools:
tools/bin/sdkmanager “build-tools;33.0.2” “platforms;android-33”
The Makefile
assumes that the Android SDK is installed in
~/opt/android-sdk-linux
and the NDK is installed in
~/opt/android-ndk-r26d
. You can use the options ANDROID_SDK
and
ANDROID_NDK
to override these paths.
Load/update the IOIO source code:
git submodule update --init --recursive
To compile, run:
make TARGET=ANDROID
Use one of the following targets:
Name |
Description |
---|---|
|
for ARM CPUs (same as |
|
for ARMv7 CPUs (32 bit) |
|
for 64 bit ARM CPUs |
|
for x86-32 CPUs |
|
for x86-64 CPUs |
|
“fat” package for all supported CPUs |
Compiling for Windows¶
To cross-compile to (desktop) Windows, you need Mingw-w64.
The following command installs it on Debian:
sudo apt-get install g++-mingw-w64
To compile for 32 bit Windows, run:
make TARGET=PC
Use one of the following targets:
|
32 bit Windows (i686) |
|
Windows x64 (amd64 / x86-64) |
Compiling for iOS and macOS¶
On macOS, the following tools are required:
png2icns from libicns to build for macOS
dpkg to build the iOS IPA package
mkisofs to build the macOS DMG package
To compile for iOS / AArch64, run:
make TARGET=IOS64 ipa
To compile for iOS / ARMv7, run:
make TARGET=IOS32 ipa
To compile for macOS / x86_64, run:
make TARGET=OSX64 dmg
Compiling for macOS (with Homebrew)¶
Install the required Homebrew packages:
brew install \
automake autoconf libtool \
pkg-config \
quilt \
librsvg \
imagemagick gettext sox \
fmt \
sdl2 \
libsodium \
freetype \
libpng libjpeg-turbo \
libtiff libgeotiff proj \
c-ares \
curl \
lua
Then compile:
make dmg
Compiling on the Raspberry Pi 4¶
Install additional dependencies:
sudo apt-get install libdrm-dev libgbm-dev \
libgles2-mesa-dev \
libinput-dev
Compile:
make
Compiling for the Raspberry Pi 1-3¶
You need an ARM toolchain. For example, you can use the Debian package
g++-arm-linux-gnueabihf
:
make TARGET=PI
To optimize for the Raspberry Pi 2 (which has an ARMv7 with NEON instead of an ARMv6):
make TARGET=PI2
These targets are only used for cross-compiling on a (desktop) computer. If you compile on the Raspberry Pi, the default target will auto-detect the Pi.
Compiling for the Cubieboard¶
To compile, run:
make TARGET=CUBIE
This target is only used for cross-compiling on a (desktop) computer. If you compile on the Cubieboard, the default target will auto-detect the Cubieboard.
Compiling for Kobo E-book Readers¶
An ARM toolchain is bootstrapped during the build automatically.
To compile XCSoar, run:
make TARGET=KOBO
To build the kobo install file KoboRoot.tgz
, you need the following
Debian packages:
sudo apt-get install \
fakeroot \
python3-setuptools \
ttf-bitstream-vera
Then compile using this command:
make TARGET=KOBO output/KOBO/KoboRoot.tgz
Building USB-OTG Kobo Kernel¶
To build a USB-OTG capable kernel for the Kobo, clone the git repository:
git clone https://github.com/XCSoar/linux.git
Check out the correct branch. For the Kobo Mini, this is the branch
kobo-mini
, for the Kobo Glo HD, the branch is called
kobo-glohd
, and for the Kobo Aura 2, use the branch
kobo-aura2
:
git checkout kobo-mini
Configure the kernel using the configuration files from the
kobo/kernel
directory in XCSoar’s git
repository. For the Kobo
Mini, install a gcc 4.4 cross
compiler,
for example in /opt
. For the Kobo Glo HD and Aura 2, install a gcc
4.6 cross
compiler
To compile a kernel image for the Kobo Mini, type:
make \
CROSS_COMPILE=/opt/arm-2010q1/bin/arm-none-linux-gnueabi- \
ARCH=arm uImage
To compile a kernel image for the Kobo Glo HD, type:
make \
CROSS_COMPILE=/opt/gcc-arm-none-eabi-4_6-2012q4/bin/arm-none-eabi- \
ARCH=arm uImage
Copy uImage
to the Kobo. Kernel images can be installed with the
following command:
dd if=/path/to/uImage of=/dev/mmcblk0 bs=512 seek=2048
Note that XCSoar’s rcS
script may overwrite the kernel image
automatically under certain conditions. To use a new kernel permanently,
install it in /opt/xcsoar/lib/kernel
. Read the file kobo/rcS
to
find out more about this.
To include kernel images in KoboRoot.tgz
, copy uImage.otg
,
uImage.kobo
, uImage.glohd.otg
, uImage.glohd
,
uImage.aura2
and uImage.aura2.otg
to /opt/kobo/kernel
.
Editing the Manuals¶
The XCSoar documententation (except for the developer manual) is written using the TeX markup language. You can edit the source files with any text editor, although a specific TeX editor (e.g. LateXila) makes it easier.
Source files are located in the en, fr, de, pl subdirectories of the
doc/manual
directory. The Developer manual is in the
doc/manual/en directory. The generated files are put into the
output/manual directory.
To generate the PDF manuals, you need the TexLive package, plus some European languages.
The following command installs these on Debian:
sudo apt-get install texlive \
texlive-latex-extra \
texlive-luatex \
texlive-lang-french \
texlive-lang-polish \
texlive-lang-german \
texlive-lang-portuguese \
liblocale-po-perl
The documentation is distributed as PDF files. Generating the PDFs from the TeX files is done by typing:
make manual
A lot of warnings are generated… this is normal. Check for the presence of PDF files to ensure that the generation process was successful.
Options¶
Parallel Build¶
Most contemporary computers have multiple CPU cores. To take advantage
of these, use the make -j
option:
make -j12
This command launches 12 compiler processes at the same time.
Rule of thumb: choose a number that is slightly larger than the number of CPU cores in your computer. 12 is a good choice for a computer with 8 CPU cores.
Optimised Build¶
By default, debugging is enabled and compiler optimisations are disabled. The resulting binaries are very slow. During development, that is helpful, because it catches more bugs.
To produce optimised binaries, use the option DEBUG
:
make DEBUG=n
Be sure to clean the output directory before you change the DEBUG
setting, because debug and non-debug output files are not compatible.
The convenience target OPT
is a shortcut for:
TARGET=UNIX DEBUG=n TARGET_OUTPUT_DIR=output/OPT
It allows building both debug and non-debug incrementally, because two different output directories are used.
Compiling with ccache¶
To speed up the compilation of XCSoar we can use ccache
to cache the
object files for us. All we have to do is install ccache and add
USE_CCACHE=y
to the make command line:
sudo apt-get install ccache
make TARGET=UNIX USE_CCACHE=y
Using a build VM with Vagrant¶
An easy way to install a virtual machine with all build dependencies required for various targets (e.g. Linux, Windows, Android and Kobo), is using Vagrant.
The following is needed to install the VM with Vagrant:
The Vagrantfile can be found in the ide/vagrant
subfolder of the
source. To set up the VM, and connect to it, type:
cd ide/vagrant
vagrant up
vagrant ssh
The XCSoar source directory on the host is automatically mounted as a
shared folder at /xcsoar-host-src
in the VM. For performance
reasons, it is not recommended to compile directly in this folder. A git
clone of this directory is automatically created in the home directory
(`` /xcsoar-src``), which should be used instead. In this git clone, the
XSoar source directory on the host is preconfigured as a git remote
named “host”, and the XCSoar master directory is preconfigured as a
remote named “master”.
To shutdown the VM, type:
vagrant halt