Building Guide

Building GNSS-SDR

In principle, GNSS-SDR can be built in any Unix-like system. In practice, it depends on being able to install all the required dependencies, mainly GNU Radio plus some few more libraries:

  • Gflags, a library that implements commandline flags processing,
  • Glog, a library that implements application-level logging,
  • Armadillo, a C++ linear algebra library,
  • Googletest, Google's framework for writing C++ tests (requires definition of the GTEST_DIR variable),

and, optionally,

  • Gperftools, which provides fast, multi-threaded malloc() and performance analysis tools.

GNSS-SDR has been successfully built on Ubuntu 12.04-14.04 (32 and 64 bits), Debian 6.0.6-7.2 (32 and 64 bits), Fedora 18-20 (32 and 64 bits), and Mac OS X 10.8-10.9 systems, and might work on other Unix-like distributions.

In order to create an executable tuned to your system and your host processor, GNSS-SDR uses CMake as a building tool. For Mac OS X users, see below.

Using CMake

Get the ultimate version of the source code by checking out GNSS-SDR's repository:

$ git clone git://git.code.sf.net/p/gnss-sdr/cttc gnss-sdr

This will create a folder named gnss-sdr with the following structure:

 |-gnss-sdr
 |---build       <- where gnss-sdr is built
 |---cmake       <- CMake-related files
 |---conf        <- Configuration files. Each file represents one receiver.
 |---data        <- Populate this folder with your captured data.
 |---docs        <- Contains documentation-related files
 |---drivers     <- Drivers for some RF front-ends
 |---firmware    <- Firmware for some front-ends
 |---install     <- Executables 
 |---src         <- Source code folder
 |-----algorithms
 |-----core
 |-----main
 |-----tests
 |-----utils     <- some utilities (e.g. Matlab scripts)

Then, type:

$ cd gnss-sdr/build
$ cmake ../
$ make
$ make install

This will create two executables at gnss-sdr/install, namely gnss-sdr and run_tests. Note that you do not need administrative privileges (that is, 'sudo make install') for the last step, since all the content of GNSS-SDR will remain under the gnss-sdr folder. You can create the documentation from the source code by doing:

$ make doc

This will use Doxygen to generate HTML documentation that can be retrieved pointing your browser of preference to gnss-sdr/docs/html/index.html. If a LaTeX installation is detected in your system,

$ make pdfmanual

will create a PDF manual at gnss-sdr/docs/GNSS-SDR_manual.pdf. Finally,

$ make doc-clean

will remove the content of previously-generated documentation.

If there are required dependencies missing, CMake can try to download and build some of them automatically for you. In case of Gflags, Glog, Armadillo and Gtest, they can be downloaded, configured and built 'on-the-fly' when you run 'make', along with the rest of the GNSS-SDR source code. For your convenience, the source code of all those downloaded packages with remain under a newly created folder gnss-sdr/thirdparty. However, installing GNU Radio can be a quite complex process and our CMake scripts cannot do it automatically. By fortune, there are tools that can help you on that, check below. Please note that none of the dependencies downloaded and built when doing 'make' will remain permanently installed on your system. They will be built and linked statically, but not installed. You can install them by following the instructions below, and then they will be found and used the next time you invoke the configuration with 'cmake ../'. Remember that the source code of all those extra dependencies downloaded when doing 'make' will remain under the gnss-sdr/thirdparty folder, so you can go directly there, configure, build and install them.

 

Manual installation of GNSS-SDR dependencies

Install GNU Radio:

- Downloading, building and installing GNU Radio and all its dependencies is not a simple task. If you are using GNU/Linux, we recommend to use PyBOMBS (Python Build Overlay Managed Bundle System), the GNU Radio install management system that automatically does all the work for you. In a terminal, type:

$ git clone git://github.com/pybombs/pybombs 
$ cd pybombs

Configure PyBOMBS:

$ ./pybombs config 

You can safely accept the default options but for prefix. We recommend to put /usr/local there. After the configuration, you should get something similar to:

gituser = username
prefix = /usr/local
satisfy_order = deb,src
forcepkgs =
timeout = 30
cmakebuildtype = RelWithDebInfo
builddocs = OFF
cc = gcc
cxx = g++

The parameter satisfy_order must be set to rpm,src if you are using Fedora/CentOS/RHEL or any other RPM-based Linux distribution.

Then, you are ready to download and install UHD (the Universal Hardware Driver), GNU Radio and all their required dependencies by doing:

$ sudo ./pybombs install uhd gnuradio

This can take some time (up to two hours to complete, depending on your system), and installs the latest versions of the Universal Hardware Driver (UHD) and GNU Radio in your system, including all their dependencies. In case you do not want to use PyBOMBS and prefer to build and install GNU Radio manually from source, follow instructions at the GNU Radio Building Guide.

After installing GNU Radio, you may want to run volk_profile, a program that tests all known Vector-Optimized Library of Kernels (VOLK) for each Single-Input Multiple-Data (SIMD) architecture supported by the host processor (sse, sse2, sse3, avx, etc.). When finished, it will write to $HOME/.volk/volk_config the best architecture (i.e., the one that provides fastest execution) for each of the VOLK functions. This file is read when using a function to know the best version of the function to execute.

Install other libraries used by GNSS-SDR:

- Download, compile, and install the Armadillo linear algebra library

If you are using Ubuntu/Debian/LinuxMint or similar:

$ sudo apt-get install libblas-dev liblapack-dev gfortran

or, if you are using Fedora/CentOS/RHEL or similar:

$ sudo yum install lapack-devel blas-devel gcc-fortran

and then:

$ wget http://sourceforge.net/projects/arma/files/armadillo-4.300.8.tar.gz 
$ tar xvfz armadillo-4.300.8.tar.gz 
$ cd armadillo-4.300.8 
$ cmake . 
$ make 
$ sudo make install 

The full stop separated from "cmake" by a space is important. CMake will figure out what other libraries are currently installed and will modify Armadillo's configuration correspondingly. CMake will also generate a run-time armadillo library, which is a combined alias for all the relevant libraries present on your system (eg. BLAS, LAPACK and ATLAS).

- Download, unzip, configure, build and install gflags, a commandline flags processing module for C++:

$ wget http://gflags.googlecode.com/files/gflags-2.0.zip 
$ unzip gflags-2.0.zip 
$ cd gflags-2.0 
$ ./configure 
$ make 
$ sudo make install 

- Download, unzip, configure, build and install glog, a library that implements application-level logging:

$ wget http://google-glog.googlecode.com/files/glog-0.3.3.tar.gz 
$ tar xvfz glog-0.3.3.tar.gz 
$ cd glog-0.3.3 
$ ./configure 
$ make 
$ sudo make install 

- Download, unzip, configure, build and install gperftools, a set of performance analysis tools:

$ wget http://gperftools.googlecode.com/files/gperftools-2.1.tar.gz 
$ tar xvfz gperftools-2.1.tar.gz 
$ cd gperftools-2.1 
$ ./configure --enable-frame-pointers 
$ make 
$ sudo make install 

- Download, unzip, configure, and build the Google C++ Testing Framework (also known as Google Test or gtest):

$ wget http://googletest.googlecode.com/files/gtest-1.7.0.zip 
$ unzip gtest-1.7.0.zip 
$ cd gtest-1.7.0 
$ ./configure 
$ make 

Please DO NOT install gtest (do not do "sudo make install"). Every user needs to compile his tests using the same compiler flags used to compile the installed Google Test libraries; otherwise he may run into undefined behaviors (i.e. the tests can behave strangely and may even crash for no obvious reasons). The reason is that C++ has this thing called the One-Definition Rule: if two C++ source files contain different definitions of the same class/function/variable, and you link them together, you violate the rule. The linker may or may not catch the error (in many cases it is not required by the C++ standard to catch the violation). If it does not, you get strange run-time behaviors that are unexpected and hard to debug. If you compile Google Test and your test code using different compiler flags, they may see different definitions of the same class/function/variable (e.g. due to the use of #if in Google Test). Therefore, for your sanity, we recommend to avoid installing pre-compiled Google Test libraries. Instead, each project should compile Google Test itself such that it can be sure that the same flags are used for both Google Test and the tests. GNSS-SDR's building system does the compilation and linking of gtest with its own tests for you; it is only required that you tell the system where the gtest folder that you downloaded resides. Just add to your $HOME/.bashrc file the following line:

export GTEST_DIR=/home/username/gtest-1.7.0 

changing /home/username/gtest-1.7.0 by the actual directory where you downloaded gtest.

- Install OpenSSL

If you are using Ubuntu/Debian/LinuxMint or similar:

$ sudo apt-get install libssl-dev  

or, if you are using Fedora/CentOS/RHEL or similar:

$ sudo yum install openssl-devel  

 

Release and Debug builds

By default, CMake will build the Release version, meaning that the compiler will generate a faster, optimized executable that will not contain debug symbols (thus making it harder to debug), will not spend time executing assertion checks and will perform a selected subset of logs. This is the recommended build type when using a RF front-end and you need to attain real time. If working with a file (and thus without real-time constraints), you may want to obtain more information about the internals of the receiver, as well as more fine-grained logging. This can be done by building the Debug version, by doing:

$ cd gnss-sdr/build
$ cmake -DCMAKE_BUILD_TYPE=Debug ../
$ make
$ make install

That means that the flags passed to the compiler are not focused in obtaining an optimized executable, but to facilitate the work of debugging tools such as gdb. The executable will contain debug symbols, will not be optimized for size or speed and will perform all the assertion checks and logging annotations. This is the preferred variant if you are developing or debugging the code, and where real-time is not a constraint (for instance, reading raw samples from a file instead of from a RF front-end).

 

Installing GNSS-SDR on Mac OS X

Mac OS X 10.9 Mavericks

If you still have not installed Xcode, do it now from the App Store (it's free).

Then, install Macports. If you are upgrading from a previous installation, please follow the migration rules.

In a terminal, type:

$ sudo port selfupdate
$ sudo port upgrade outdated
$ sudo port install doxygen +latex
$ sudo port install gnuradio
$ sudo port install armadillo
$ sudo port install google-glog +gflags

Finally, you are ready to checkout the GNSS-SDR repository and build the software:

$ git clone git://git.code.sf.net/p/gnss-sdr/cttc gnss-sdr
$ cd gnss-sdr/build
$ cmake ../ -DCMAKE_CXX_COMPILER=/usr/bin/clang++
$ make
$ make install

This will create two executables at gnss-sdr/install, namely gnss-sdr and run_tests. The documentation can be built by:

$ make doc

and can be viewed doing:

$ open ../docs/html/index.html

 

Mac OS X 10.6, 10.7, 10.8 (Snow Leopard, Lion, Mountain Lion)

If you still have not installed Xcode, do it now from the App Store (it's free). Once Xcode is installed, download and install the command line tools:

Xcode -> Preferences -> Downloads -> Components -> Command Line Tools

Then, install MacPorts. All the required packages are available for free.

Once MacPorts is properly installed on your system, open a terminal and type:

$ sudo port selfupdate
$ sudo port install gcc48
$ sudo port select --set gcc mp-gcc48

Install X11 via XQuartz-2.7.4.dmg (needed by gnuradio-companion but not by GNSS-SDR) from the XQuartz webpage.

Install GNU Radio and other required dependencies:

$ sudo port install gnuradio 
$ sudo port install armadillo

The gflags and glog libraries should be installed manually, and in that particular order (same steps as above). The same applies to gtest. If those libraries are not already installed when building GNSS-SDR, cmake will download, build and link them statically but they will not remain installed in the system.

Finally, you are ready to checkout the GNSS-SDR repository and build the software:

$ git clone git://git.code.sf.net/p/gnss-sdr/cttc gnss-sdr
$ cd gnss-sdr/build
$ cmake ../ -DCMAKE_CXX_COMPILER=g++
$ make
$ make install

This will create two executables at gnss-sdr/install, namely gnss-sdr and run_tests. The documentation can be built by:

$ make doc

and can be viewed doing:

$ open ../docs/html/index.html

 

 

See also:

 

 

   Back to articles

 

 

 

Instructions for building the source code

Theme by Danetsoft and Danang Probo Sayekti inspired by Maksimer