Configuration options at building time

9 minute read

GNSS-SDR’s building system is based on CMake, a cross-platform, free and open-source software for managing the build process of software using a compiler-independent method. 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 environments such as make or Apple’s Xcode.

CMake allows GNSS-SDR to be effortlessly built in 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 highly recommended when building GNSS-SDR, and you will get a warning 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/build
$ cmake ..
$ make
$ sudo make install

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>

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 bulding time.

NOTE: Options in orange are currently available only in the next branch of GNSS-SDR, and they will be part of the next release. More info on how to access the next branch can be found in our brief Git tutorial.

General CMake variables

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

Variable passed to CMake Possible values Default Effect
‑DCMAKE_BUILD_TYPE None / Debug / Release / RelWithDebInfo / MinSizeRel Release A variable which controls the type of build and some of the flags passed to the compiler. The default values for these flags change with different compilers. If CMake does not know your compiler, the contents will be empty. See the CMake documentation for more details.
‑DCMAKE_INSTALL_PREFIX System path System-dependant. In most systems, this use to be /usr/local. Specifies the path in which GNSS-SDR will be installed when doing make install. The content of this variable is prepended onto all install directories. On UNIX systems, one can use the DESTDIR mechanism in order to relocate the whole installation (see below).
‑DCMAKE_INCLUDE_PATH  System path System-dependant. This is used when searching for include files e.g. using the FIND_PATH() command in the CMakeLists.txt files. If you have headers in non-standard locations, it may be useful to set this variable to this directory. If you need several directories, separate them by the platform specific separators (e.g. “:” on UNIX).
‑DCMAKE_LIBRARY_PATH  System path System-dependant. This is used when searching for libraries e.g. using the FIND_LIBRARY() command in the CMakeLists.txt files. If you have libraries in non-standard locations, it may be useful to set this variable to this directory. If you need several directories, separate them by the platform specific separators (e.g. “:” on UNIX).
‑DCMAKE_PREFIX_PATH  System path System-dependant. This is used when searching for include files, binaries, or libraries using either the FIND_PACKAGE(), FIND_PATH(), FIND_PROGRAM(), or FIND_LIBRARY() commands in the CMakeLists.txt files. For each path in the CMAKE_PREFIX_PATH list, CMake will check “PATH/include” and “PATH” when FIND_PATH() is called, “PATH/bin” and “PATH” when FIND_PROGRAM() is called, and “PATH/lib” and “PATH” when FIND_LIBRARY() is called.
‑DCMAKE_TOOLCHAIN_FILE Path to a CMake toolchain file None This variable is specified on the command line when cross-compiling with CMake. It is the path to a file which is read early in the CMake run and which specifies locations for compilers and toolchain utilities, and other target platform and compiler related information. For an example of usage, see cross-compiling GNSS-SDR.

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 a intermediate staging directory. See a practical example of its usage at cross-compiling GNSS-SDR.

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

Variable passed to CMake Possible values Default Effect
‑DENABLE_OSMOSDR ON / OFF OFF If set to ON, it enables the use of OsmoSDR and other front-ends (RTL-based dongles, HackRF, BladeRF, etc.) as a signal source. Specifically, the Osmosdr_Signal_Source and RtlTcp_Signal_Source implementations of Signal Source blocks become available. This option requires gr-osmosdr already installed in your system. See an example of use at the Realtek RTL2832U USB dongle tutorial.
‑DENABLE_GN3S ON / OFF OFF If set to ON, it enables the use of the SiGe GN3S Sampler v2 as signal source (experimental). Specifically, the Gn3sSignalSource implementation of a Signal Source block becomes available. This option requires gr-gn3s already installed in your system. See the SiGe GN3S Sampler v2 USB front-end tutorial for an example of its usage with GNSS-SDR.

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.

Variable passed to CMake Possible values Default Effect
‑DENABLE_OPENCL ON / OFF OFF If set to ON, it enables building of processing blocks implemented with OpenCL (experimental). Specifically, the GPS_L1_CA_PCPS_OpenCl_Acquisition implementation of an Acquisition block becomes available. This option requires the OpenCL library and a compatible Graphic Processing Unit (GPU).
‑DENABLE_CUDA ON / OFF OFF If set to ON, it enables building of processing blocks implemented with CUDA (experimental). Specifically, the GPS_L1_CA_DLL_PLL_Tracking_GPU implementation of a Tracking block becomes available. This option requires the CUDA Toolkit and a compatible Graphic Processing Unit (GPU).
‑DENABLE_FPGA ON / OFF OFF If set to ON, it enables building of processing blocks implemented in VHDL and executed in a FGPA device (experimental).
‑DENABLE_PROFILING ON / OFF OFF If set to ON, it enables automatic execution of volk_gnsssdr_profile at the end of the building process. This program tests all known VOLK_GNSSSDR kernels (that is, basic processing components like adders, multipliers, correlators, and much more) for each SIMD architecture supported by the host machine, measuring their performance. When finished, the profiler writes to $HOME/.volk_gnsssdr/volk_gnsssdr_config the fastest implementation for each VOLK_GNSSSDR function. This file is read when using a function to know the best version to execute.

Binary portability and packaging options

Variable passed to CMake Possible values Default Effect
‑DENABLE_GENERIC_ARCH ON / OFF OFF If set to ON, it builds portable binaries which are non-dependant of the SIMD technologies present in the building machine.
‑DENABLE_PACKAGING ON / OFF OFF If set to ON, it enables software packaging flags (for instance, it removes inessential information from executable binary programs and object files, thus potentially resulting in better performance and sometimes significantly less disk space usage) and sets automatically the variable ENABLE_GENERIC_ARCH to ON.
‑DENABLE_OWN_ARMADILLO ON / OFF OFF If set to ON, it forces to download, build and link a working version of Armadillo locally, even if it is already installed.
‑DENABLE_OWN_GLOG ON / OFF OFF If set to ON, it forces to download, build and link a working version of glog locally, even if it is already installed. If GFlags is not found, it will also download, build and link it.
‑DENABLE_LOG ON / OFF ON If set to OFF, it disables runtime logging with glog. This can be useful in storage-limited systems. GNSS-SDR will still produce outputs such as RINEX or KML files.

QA code building options

Variable passed to CMake Possible values Default Effect
‑DENABLE_UNIT_TESTING ON / OFF ON If set to OFF, it disables the building of unit tests. This can be useful in memory-limited systems.
‑DENABLE_UNIT_TESTING_EXTRA ON / OFF OFF If set to ON, it downloads external raw sample files files and other software tools (among them, GPSTk, if it is not already found in your system), and builds some extra unit tests that are added to the run_tests executable.
‑DENABLE_SYSTEM_TESTING ON / OFF OFF If set to ON, it builds system tests. The binary ttff, a tool for Time-To-First-Fix measurement, is generated at the gnss-sdr/install folder, unless otherwise indicated by the ENABLE_INSTALL_TESTS option.
‑DENABLE_SYSTEM_TESTING_EXTRA ON / OFF OFF If set to ON, it downloads external software tools (among them, GPSTk, if it is not already found in your system) and builds some extra system tests. The generated binaries are copied to the gnss-sdr/install folder, unless otherwise indicated by the ENABLE_INSTALL_TESTS option.
‑DENABLE_OWN_GPSTK ON / OFF OFF If set to ON, it forces to download, build and link GPSTk for system tests, even if it is already installed. This can be useful if you have an old version of GPSTk already installed in your system and you do not want to remove it, but you still want the QA code to use a more recent version.
‑DENABLE_INSTALL_TESTS ON / OFF OFF By default, generated test binaries are not installed system-wide but placed in the local folder gnss-sdr/install. If this option is set to ON, test binaries and auxiliary files will not be copied to gnss-sdr/install but installed in the system path when doing make install.

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:

Variable passed to CMake Possible values Default Effect
‑DENABLE_GPERFTOOLS ON / OFF OFF If set to ON, it enables linking to gperftools libraries (tcmalloc and profiler). This option requires gperftools to be already installed in your system. Check out how to profile GNSS-SDR for more details on gperftools usage.
‑DENABLE_GPROF ON / OFF OFF If set to ON, it enables the use of the GNU profiler tool gprof. Specifically, it adds -pg to the list of flags passed to the compiler and the linker. If the compiler is not GNU, this option has no effect.

Tags:

Updated:

Leave a Comment