Configuration options at building time

GNSS-SDR’s building process is managed by CMake, a cross-platform, compiler-independent, free, and open-source software tool. CMake supports directory hierarchies and applications that depend on multiple libraries. It can locate executables, files, and libraries to be linked against, generating makefiles for many platforms and IDEs (such as Eclipse, Codeblocks, and Xcode), and liberating users from choosing the adequate flags for their compiler. CMake is used in conjunction with native build systems such as make, ninja, or Apple’s Xcode.

CMake allows GNSS-SDR to be effortlessly built on a wide range of operating systems and processor architectures, constituting a key tool for its portability.

CMake can handle in-place and out-of-place builds, enabling several builds from the same source tree, and cross-compilation. The ability to build a directory tree outside the source tree is a key feature, ensuring that if a build directory is removed, the source files remain unaffected. This approach is mandatory when building GNSS-SDR, and you will get an error message if you try an in-place build.

The cmake executable is the CMake command-line interface. When cmake is first run in an empty build tree, it creates a CMakeCache.txt file and populates it with customizable settings for the project.

Once all the required dependencies are installed in your system, the default building process is:

$ cd gnss-sdr && git checkout next
$ mkdir -p build && cd build
$ cmake ..
$ make
$ sudo make install

or, alternatively:

$ cd gnss-sdr && git checkout next
$ cmake -S . -B build
$ cmake --build build
$ sudo cmake --install build

CMake’s defaults and GNSS-SDR project configuration settings can be overridden on the command line with the -D option, with the following syntax:

$ cmake -D<variable_name>=<value>

or, if you are using CMake’s binary options:

$ cmake -S . -B build -D<variable_name>=<value>

Thus, if you want to set the variable named CMAKE_BUILD_TYPE to the Debug value, you can write in your command line:

$ cmake -DCMAKE_BUILD_TYPE=Debug ..

You can specify any number of variables:

$ cmake -DCMAKE_BUILD_TYPE=Debug -DENABLE_OSMOSDR=ON ..

This page documents the available GNSS-SDR configuration options at building time.

General CMake variables

The building system honors the usual CMake variables. Most relevant are:

In addition, if the DESTDIR environment variable is set, it will be prefixed to CMAKE_INSTALL_PREFIX in places where it is used to access files during installation. This allows the files to be installed in an intermediate directory tree without changing the final installation path name. For instance:

$ make DESTDIR=/home/carles install

will install the software using the installation prefix, e.g. /usr/local prepended with the DESTDIR value which finally gives /home/carles/usr/local, so binaries will be under /home/carles/usr/local/bin.

Since the value of CMAKE_INSTALL_PREFIX may be included in installed files, it is important to use DESTDIR rather than changing CMAKE_INSTALL_PREFIX when it is necessary to install to an intermediate staging directory. See a practical example of its usage at cross-compiling GNSS-SDR.

The value of CMAKE_BUILD_TYPE determines the flags passed to the compiler. In addition to those build types offered by CMake by default, GNSS-SDR offers other extra build types for debugging and profiling purposes. The possible options and the flags passed to the compiler are listed below:

• None: nothing set
• Debug: -O2 -g
• Release: -O3
• RelWithDebInfo: -O3 -g
• MinSizeRel: -Os
• Coverage: -Wall -pedantic -pthread -g -O0 -fprofile-arcs -ftest-coverage
• NoOptWithASM: -O0 -g -save-temps
• O2WithASM: -O2 -g -save-temps
• O3WithASM: -O3 -g -save-temps
• ASAN: -Wall -Wextra -g -O2 -fsanitize=address -fno-omit-frame-pointer

For more details, the CMake official documentation is home of the authoritative guide to all CMake variables, commands, and properties.

Optional drivers for RF front-ends

Please note that if you installed GNSS-SDR in Debian or Ubuntu through a .deb package (sudo apt-get install gnss-sdr), the option ENABLE_OSMOSDR is set to ON, and the required drivers are already installed.

FPGA / GPU off-loading and SIMD-related options

Binary portability and packaging options

QA code building options

If all these options are set to OFF (so, -DENABLE_UNIT_TESTING=OFF in a fresh start), then Google Test is not a required dependency anymore.

Performance analysis tools

Some statistical profiling tools require the software under analysis to be compiled and linked with certain profiling options enabled. GNSS-SDR provides some options for that:

Static analysis

clang-tidy is a clang-based C++ “linter” tool. Its purpose is to provide an extensible framework for diagnosing and fixing typical programming errors, like style violations, interface misuse, or bugs that can be deduced via static analysis.

Please note that you can also use the run-clang-tidy script (called run-clang-tidy.py in some platforms) to perform checks over all files in the compilation database:

$ run-clang-tidy -checks='-*,modernize-use-nullptr' -fix

You can examine the full list of clang-tidy checks and their definitions.

In Debian and Ubuntu machines, clang-tidy can be installed with:

$ sudo apt-get install clang clang-tidy

Example of usage:

$ cmake -DCMAKE_CXX_COMPILER=/usr/bin/clang++ \
        -DCMAKE_C_COMPILER=/usr/bin/clang \
        -DENABLE_CLANG_TIDY=ON ..
$ make        

Check the coding style guide for more information on how to use clang-tidy in your system.

Documentation

GNSS-SDR can generate documentation from its source code in HTML (by doing make doc) or PDF (by doing make pdfmanual) formats. Generating the documentation requires Doxygen installed in your system. The PDF generation also requires \(\LaTeX\) already installed.

By default, the HTML output makes use of MathJax loaded from a public CDN for equations rendering in your browser, so you do not need to have MathJax locally installed. If you want to enjoy MathJax rendering in offline mode, you can use a local installation of MathJax (version 2.x) by disabling the option below.

For instance, in Debian/Ubuntu systems MathJax can be installed as:

$ sudo apt-get install libjs-mathjax