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),
- Gperftools, which provides fast, multi-threaded malloc() and performance analysis tools.
GNSS-SDR has been successfully built on Ubuntu 12.10 (32 and 64 bits), Debian 6.0.6, Fedora 18, and Mac OS X 10.8.2 (Mountain Lion) systems, and might work on other Unix-like distributions.
Get the ultimate version of the source code by checking out GNSS-SDR's repository:
$ svn co http://svn.code.sf.net/p/gnss-sdr/code/trunk 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 |-----core |-----main |-----tests |-----utils <- some utilities (e.g. Matlab scripts)
$ 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.
If there are required dependencies missing, CMake will try to download and build them automatically for you. If GNU Radio is not installed, and you are working on a Debian, Ubuntu, Fedora, RedHat or Mint system, try (from gnss-sdr/build):
$ cmake ../ -DINSTALL_GNURADIO=ON
This will download and run a script that automatically installs GNU Radio (and all its dependencies) on your machine. You will be prompted to provide root's password in the process. In case of Gflags, Glog, Armadillo and Gtest, they will be downloaded, configured and built 'on-the-fly' when you run 'make', along with the rest of the source code. For your convenience, the source code of all those downloaded packages with remain under a newly created folder gnss-sdr/thirdparty.
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.
Please note that, with the exception of GNU Radio, 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. We recommend to use Marcus Leech's build-gnuradio script, which automatically does all the work for you. In a terminal, type:
$ wget http://www.sbrac.org/files/build-gnuradio $ chmod a+x build-gnuradio $ ./build-gnuradio
This can take a while (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 the script and prefer to build and install GNU Radio manually from source, follow instructions at the GNU Radio Building Guide
- Set up a system variable needed if you want to use GNU Radio beyond GNSS-SDR (highly recommended!):
In order to avoid defining that variable each time you enter a session, you may want to add that line to your $HOME/.bashrc file.
- 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
$ wget http://sourceforge.net/projects/arma/files/armadillo-3.6.2.tar.gz $ tar xvfz armadillo-3.6.2.tar.gz $ cd armadillo-3.6.2 $ 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 gperftools, a set of performance analysis tools:
$ wget http://gperftools.googlecode.com/files/gperftools-2.0.tar.gz $ tar xvfz gperftools-2.0.tar.gz $ cd gperftools-2.0 $ ./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.6.0.zip $ unzip gtest-1.6.0.zip $ cd gtest-1.6.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:
changing /home/username/gtest-1.6.0 by the actual directory where you downloaded gtest.
- 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
- Install Subversion
$ sudo apt-get install subversion
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).
If you have still not installed Apple's Xcode Developer Tools and MacPorts, please do it now following the instructions for installing MacPorts. All the required packages are available for free.
Once MacPorts is properly installed on your system, open a terminal and type:
$ sudo port install gcc47 $ sudo port select --set gcc mp-gcc47 $ sudo port install gnuradio +full $ sudo port install subversion $ svn co http://svn.code.sf.net/p/gnss-sdr/code/trunk gnss-sdr $ cd gnss-sdr/build $ cmake ../ -DCMAKE_CXX_COMPILER=gcc $ 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
Instructions for building the source code