Building using CMake

From FlightGear wiki
Jump to navigation Jump to search

1rightarrow.png See Building Flightgear for the main article about this subject.


Current status


06/2020: James has pushed some configuration changes to next (SG+FG) to raise various required versions of things.

If you’re developing on ‘something fairly recent’, you shouldn’t see any difference except it would be a wise time to wipe your build dirs and re-CMake from clean. If you’re on a ‘somewhat older’ Linux, the baselines being Ubuntu 18.04 (their previous LTS) and CentOS 7 (which our Jenkins runs), you should also be fine except for GCC, where you will need a version supporting C++14: in practice this means GCC 5.x or higher. (Or use Clang…) For both of these distros there are officially supported ways to get newer GCCs (we’re actually using GCC 9 on Jenkins now..), so I don’t expect this to be a problem.

As part of this we now require CMake 3.10[1], Qt 5.9 and OSG 3.4.1, and James started removing various legacy pieces from next around this. There are plenty more cleanups that can be done based on this : especially on the CMake and C++ sides. Things like Boost -> Std stuff, Cmake targets-as-objects support (eg, target_compile_features can be used now).

Windows and macOS should be unaffected BTW - because on those platforms you're always running something you downloaded which is fairly up to date. If you choose to go and download an ancient version of CMake or Qt, on either platform that’s your problem to fix - but you’ll get a configuration error at least.

The idea of doing this /now/ is that the build deps won’t change again during the next two years, barring any surprises.

None of this affects the release branches of course: they continue to work with OSG 3.2, GCC 4.x, Qt 5.4 and CMake 3.0. And you shouldn’t see any behavioural changes because of this either.

Let’s see if reality corresponds to all the theory above :)[2]

08/2020: James pushed a large overhaul of the Cmake build files for FlightGear:

  • we now use modern Cmake style nearly everywhere, i.e targets-as-objects for an OOP-style build system
  • transitive dependencies are handled automatically (or at least, that’s the idea…), which simplifies things in many places (eg, audio library handling)
  • system vs built-in dependencies is handled vis ALIAS targets, so most other code doesn’t care. We link to a target which is an alias for either our built-in version or the system one (via an IMPORTED target)
  • we should have better isolation from system headers / versions of things. [3]

Build Environment & Dependencies

Linux / Unix

Note  as of 06/2021, people may have to build using at least OSG 3.6 [4]

Qt 5.9 is the correct minimum version (for next) [5])

  • Get the OpenSceneGraph sources, either from subversion or a zip
  • NOTE: On Debian AMD64 (or not 32-bit) systems (maybe including Ubuntu) there is currently a packaging error which leads to false detection of OpenAL. Until it got repaired, you have 2 options left:

1. Goto /usr/share/cmake-2.8/Modules/ (it is the right patch on my Debian system) and expand the search path with lib/x86_64-linux-gnu/:

sudo su # to become root
cd /usr/share/cmake-2.8/Modules/ # again, use the proper path of your system
$EDITOR FindOpenAL.cmake
# Search for FIND_LIBRARY(OPENAL_LIBRARY
# Search again for PATH_SUFFIXES
# Append behind "lib": lib/x86_64-linux-gnu/
# Save it
# Quit your editor
exit # to leave root

2. (As I did) Set a symbolic link so cmake can find it:

sudo su # again, become root
cd /usr/lib/
ln -s x86_64-linux-gnu/* . # ignore that error for pkconfig for now
cd pkconfig/
ln -s ../x86_64-linux-gnu/pkgconfig/* .
  • Both steps have advantages and disadvantages, e.g. when it comes to updates, so you might need to repeat your desired path and fix your symbolic links by removing them first (!) and then re-create them. A big "thanks" to James for giving me the hints. :)
  • If you have OSG/PLIB on different directories than the usual, use environmental variables OSG_DIR/PLIBDIR, e.g. addd to ~/.bashrc:
# OSG/PLIB special directory
export OSG_DIR=/opt/my-osg-path
export PLIBDIR=/opt/my-plib-path

Note: In order to set the CFLAGS/CXXFLAGS variables for make/gcc, simply configure cmake and define CMAKE_C_FLAGS and CMAKE_CXX__FLAGS. For example, to enable gprof:

cmake ../flightgear -DCMAKE_BUILD_TYPE=DEBUG -DCMAKE_C_FLAGS=-pg -DCMAKE_CXX_FLAGS=-pg

Mac

  • Install Xcode (from the App Store)
  • Install Boost from MacPorts (or directly from source)
  • Install the Subversion client libraries and PLIB. These are included in the 'Mac 3rd-party dependencies' zip file. PLIB is also available through MacPorts, and Subversion is available by default on Snow Leopard (10.6) and Lion (10.7) but NOT on Mountain Lion (10.8)
  • Install OpenSceneGraph.

The easiest solution is to grab the 3rd-party dependencies build from Jenkins: http://build.flightgear.org:8080/job/Mac-3rdparty-deps/lastSuccessfulBuild/artifact/*zip*/archive.zip. This will give you a 'dist' directory containing PLIB, Subversion and OpenSceneGraph correctly configured. When configured SimGear and FlightGear, simply use this dist directory as CMAKE_INSTALL_PREFIX, and all the dependencies should be found with no other steps.

# make a top-level directory to contain everything
mkdir FGFS
cd FGFS

# move the downloaded 'dist' dir from the zip inside FGFS
mv <dist dir from Jenkins> .

# clone from Git
git clone git://git.code.sf.net/p/flightgear/simgear/
git clone git://git.code.sf.net/p/flightgear/flightgear/

mkdir sgbuild
cd sgbuild
cmake ../simgear -DCMAKE_INSTALL_PREFIX=$PWD/../dist
make; make install

cd ..
mkdir fgbuild
cd fgbuild
cmake ../flightgear -DCMAKE_INSTALL_PREFIX=$PWD/../dist
make; make install

Note this demonstrates start from a clean setup - after the initial build it's sufficient to simply 'git pull' in the clones repositories, then execute a 'make; make install' in the build directories. You can of course have multiple build directories with different configurations, as described in more detail below.

Windows

See Building using CMake - Windows

Getting started with CMake

(These instructions apply to Unix-like systems, including Cygwin and Mac. To build using Visual Studio or some other IDE supported by CMake, most of the information below still applies)

Always compile in a separate directory to the code. For example, if the code (eg, from Git) is at /home/curt/projects/flightgear, you might create /home/curt/projects/fgbuild. Change into the new directory, and run

cmake ../flightgear

To generate standard Unix Makefiles in fgbuild.

All these instructions apply equally to OpenSceneGraph, SimGear and finally FlightGear.

Probably you want to specify an install prefix:

cmake -DCMAKE_INSTALL_PREFIX=/usr ../flightgear

Note the install prefix is automatically searched for required libraries and header files, so if you install PLIB, OpenSceneGraph and SimGear to the same prefix, most configuration options are unnecessary.

If for some reason you have a dependency (or several) at a different prefix, you can specify one or more via CMAKE_PREFIX_PATH:

cmake -DCMAKE_PREFIX_PATH="/opt/local;/opt/fgfs" ../flightgear

(note the use of semi-colons to specify multiple prefix paths)

Standard prefixes are searched automatically (/usr, /usr/local, /opt/local)

Most dependencies also expose an environment variable to specify their installation directory explicitly eg OSG_DIR or PLIBDIR. Any of the methods described above will work, but specifying an INSTALL_PREFIX or PREFIX_PATH is usually simpler.

Debug Builds

By default, we select a release build. To create a debug build, use

cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo ../flightgear

(or MinSizeRel, or Debug)

Debug builds will automatically use corresponding debug builds of required libraries, if they are available. For example you can install debug builds of SimGear and OpenSceneGraph, and a debug FlightGear build will use them.

(Debug builds of libraries have the 'd' suffix by default - Release builds have no additional suffix)

Important: You should keep in mind that debug builds are usually not optimized at all. Thus, it is very likely that a debug binary will perform worse (framerate/performance-wise) than a release build. Many people have reported getting just frame rates of about 30 fps when using a debug binary!

Note most IDE projects (eg Xcode and Visual Studio) support building all the build types from the same project, so you can omit the CMAKE_BUILD_TYPE option when running cmake, and simply pick the build configuration as normal in the IDE.

Profiling

You can also build with optional profiling support by using -DENABLE_PROFILE=ON, for details see: Built-in Profiler.

Multiple build directories

It's common to have several build directories with different build configurations (see [1] for more info), eg

   /home/curt/projects/flightgear (the git clone)
   /home/curt/projects/fgdebug
   /home/curt/projects/fgrelease
   /home/curt/projects/fg-with-svn-osg

Optional Features

To set an optional feature, do

cmake -DFEATURE_NAME=ON  ../flightgear

(or 'OFF' to disable)

To see the variables that can be configured / are currently defined, you can run one of the GUI front ends, or the following command:

cmake -L ../flighgear

Add 'A' to see all the options (including advanced options), or 'H' to see the help for each option (similar to running configure --help under autoconf):

cmake -LH ../flightgear

Build Targets

For a Unix makefile build, 'make dist', 'make uninstall' and 'make test' are all available and should work as expected. 'make clean' is also as normal, but there is *no* 'make distclean' target. The equivalent is to completely remove your build directory, and start with a fresh one.

SimGear Build Options

This article or section contains out-of-date information

Please help improve this article by updating it. There may be additional information on the talk page.

current CPU's at least support SSE3 so that is enabled by default now, Enabling AVX adds another speedup for double precision floating point calculations which is pretty much all of the FlightGear math.[6]


Some of the more common SimGear build options include

  • -DUSE_SHADERVG=ON (use shadervg backend) [2]
  • -DENABLE_PROFILE=ON (enable support for the Built-in Profiler)
  • -ENABLE_SIMD=ON SIMD Support
  • -ENABLE_DNS=ON uDNS support
  • -DENABLE_TESTS=OFF (disable unit tests)
  • -DSIMGEAR_HEADLESS=ON (enables a headless build, i.e. without OSG and other graphics stuff)
  • -DENABLE_LIBSVN=OFF (disables subversion support, i.e. scenery fetching, to be depreciated, see [3] )
  • -DENABLE_SOUND=OFF (disables OpenAL/sound support)
  • -DCMAKE_INSTALL_PREFIX=$HOME (installs everything into $HOME, instead of system-wide)
  • -DENABLE_RTI=ON (enable HLA support)
  • -DJPEG_FACTORY=ON (enable jpeg support)
  • -DENABLE_FLITE=ON (enable FLITE TTS-based ATIS) [4] [5]
  • -ENABLE_GDAL=ON (GDAL/OGR) 02/2017 [7]
  • -DENABLE_OPENMP=ON (OpenMP support requires 02/2017 [8])
  • -DENABLE_COMPOSITOR=OFF (Compositor support requires 2019.2 [9])

LTO

Erik has tried to compile Simgear and FlightGear using 'gcc -flto' to see if he could squeee just a bit more performance out of the code.

To be able to do so he's run cmake for both Simgear and FlightGear as follows:

cmake -DCMAKE_AR=/usr/bin/gcc-ar \
 -DCMAKE_RANLIB=/usr/bin/gcc-ranlib \
 -DCMAKE_NM=/usr/bin/gcc-nm \
 -DSIMGEAR_SHARED=1 \
 -DCMAKE_BUILD_TYPE=Release \
 -DCMAKE_CXX_FLAGS:STRING="-Os -march=native -mtune=native -msse3 -mfpmath=sse -flto"

After applying one patch to SimGear he got it compiling.

The resulting binary is almost exactly 5Mb smaller:

  • 14390984 fgfs-lto
  • 19354528 fgfs

It did not alter the frame-rates much for him (he's got quite a decent videocard now with the GeForce GTX 750) but Erik did have the distinct feeling there were way less small-pauses/frame-rate glitches when compared to the regular build. The overall feeling was much smoother.[10]

XCode

On Mac, '-G Xcode' will generate nice XCode projects. You can then build in the IDE or using xcodebuild. Ensure you have a recently CMake build, since Xcode support has improved in recent versions (2.8.9 at time of writing). CMake generates an 'install' target which is needed for SimGear, but FlightGear can be run and debugged directly (no install required) - simply set your DYLD_LIBRARY_PATH in the target options, to include your 'dist' directory.

Troubleshooting

If you get the error "Oops, you have installed SimGear includes, however test compiling failed. Try removing 'CMakeCache.txt' and reconfigure with 'cmake'." when trying to run cmake for flightgear it could be that you have an old SimGear version installed from your package manager.

If you get that error or anything strange even though all is apparently fine with matching simgear and flightgear versions you should check how your filesystem is mounted, because if it is an extra partition it could be that is mounted with the "noexec" flag and cmake cannot work in that conditions.