Setting up a development environment based on linux¶
This describes the setup of a development environment suitable to compile XCSoar for most supported platforms. The manual focuses on recent releases of Debian-based flavors of GNU/Linux (including Ubuntu).
In the following instructions, sudo
is used to execute commands with
root privileges. This is not enabled by default in Debian (but on some
Debian based distributions, like Ubuntu).
To install a virtual machine with the required, you can use Vagrant
.
Download source code¶
To download the XCSoar source code, make sure you have git installed:
sudo apt-get update
sudo apt-get install git
Download the source code of XCSoar by executing git
in the
following way in your project directory:
git clone --recursive https://github.com/XCSoar/XCSoar
Use provisioning scripts¶
If you are not using Vagrant, but an existing standard installation of a
Debian-based Linux distribution, you can run the scripts from
ide/provisioning
subfolder of the XCSoar source to install the build
dependencies for various XCSoar target platforms.
cd ide/provisioning
sudo ./install-debian-packages.sh
./install-android-tools.sh
Optional: Eclipse IDE¶
One of the most widespread IDEs is eclipse. It is not limited to Android, and can be used for all targets. It is not required for XCSoar, but its installation is described here as an example. Eclipse is quite heavyweight, and many developers prefer other IDEs for XCSoar development.
To install, download the eclipse installer (Sometimes called
“Ooomph!” for some reason) from here:
https://www.eclipse.org/downloads/
Important: Install the CDT version of eclipse for C development, not the Android/Java package, even if you plan developing for Android. In addition, it is very convenient to install the git support (egit).
The current stable version is eclipse mars (4.5) and works with OpenJDK 7 or 8, the new eclipse neon 4.6, currently RC2, is also quite stable, and requires OpenJDK 8. Both can be installed with the installer.
You can also install the ADT (Android development tools) package for better integration with Android.
Next, create a new project, by generating a make project from existing sources files. Choose your xcsoar source directory which contains the makefile.
Important: After you have added the sources, eclipse will start
indexing all files. If you have already started make
before this
time, then a lot of files have been downloaded for the various
libraries which are exctracted/built within the XCSoar directory (most
notably the boost libraries). Indexing all these takes a very long
time, and a lot of heap space, so you should probably stop the indexer
right away. In addition you should probably exclude these directories
from the indexer for the future.
For this, in the C/C++ scope, right-click on the “output” directory in the file tree on the left side, select “Properties”, then “Resource/Resource Filters” and add a filter. In the “add filter” dialog, choose “exclude all”, “files and folders”, “all children (recursive)” and set the Filter details to “Name matches *”. This will exclude the output tree from the indexer, leading to a minimal index.
Optional: modern LaTeX editor for editing the Manual¶
Most people today edit LaTeX files in specific editors, as this is much more comfortable and efficient. This is highly recommended especially if you are not very familiar with LaTeX: learning it is very easy with a modern editor. Here, we install TeXstudio as an example, as it is very widespread and supports the rather rare LuaLaTeX well.
To install, get the relevant package:
sudo apt-get install texstudio
As the directory tree of XCSoar is very unusual for a LaTeX project, we need to make some special configurations in order to allow for quick compiling from within the editor, and for full synctex functionality:
In “Options / Configure TeXStudio”, enable “show advanced options”.
In “Options / Configure TeXStudio / Commands / Commands / LuaLaTeX”, replace:
lualatex -synctex=1 -interaction=nonstopmode %.tex
with:
lualatex -synctex=1 -interaction=nonstopmode \
-output-directory=?a)../../../output/manual %.tex
In “Options / Configure TexStudio / Build / Build Options / Addition Search Paths”: Enter in both fields (“Log file” and in the field “PDF File”):
../../../output/manual/
Add the following line to both the .profile
and the .bashrc
file of your user directory:
export TEXINPUTS="..:../../../output/manual:../../../output/manual/en:../../..:"
Finally, you need to run make manual
in the XCSoar base directory
at least once from the command line before you can compile from within
the TexStudio interface. This creates the path structure and generates
the figure files which are included into the manual. Of course, if you
change figures, you might have to run make manual
again.
Inside TeXStudio, open the file :file:XCSoar-manual.tex
(or one of
the other root files) and right-click on this file to “set as explicit
root document”, in the structure view on the left. Now you are good to
go. Make changes and press F5 to see the result immediately.