HOW TO BUILD GNSS-SDR
----------------------

This document describes how to set up the compilation environment and build GNSS-SDR 

Ubuntu 10.04, 10.10, 11.04 and 11.10)
--------------------------------------

* 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, do:

$ 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 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 in http://gnuradio.org/redmine/projects/gnuradio/wiki/BuildGuide

- Set up some system variables needed by the GNSS-SDR build system:

export PYTHONPATH=/usr/local/lib/python2.7/dist-packages
export GNURADIO_ROOT=/path/to/gnuradio
export LD_LIBRARY_PATH=/usr/local/lib

where /path/to/gnuradio is the folder in which you invoked build-gnuradio. In order to avoid defining these variables each time you enter a session, you may want to add these three lines to your $HOME/.bashrc file.

* Install other libraries used by GNSS-SDR:

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

$ wget http://sourceforge.net/projects/arma/files/armadillo-2.4.2.tar.gz
$ tar xvfz armadillo-2.4.2.tar.gz
$ cd armadillo-2.4.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).

NOTE: ATLAS version 3.6 is know to cause random crashes and incorrect results under Ubuntu. The minimum recommended version is 3.8. It is a good idea to completely remove ATLAS 3.6 from your system, in case you have it, as it intercepts calls to BLAS and LAPACK. 

- Download, unzip, configure, build and install Google's performance analysis tools, google-perftools:

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

NOTE: At this moment (Dec. 2011), perftools seems to be not working properly in Ubuntu 11.10. See  http://code.google.com/p/google-perftools/issues/detail?id=386

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

$ 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. The building system of GNSS-SDR does the compilation and linking of gtest its own tests; 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.6.0

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



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

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

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

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

- Install Subversion

$ sudo apt-get install subversion

* Check out the latest version of GNSS-SDR

$ svn co http://gnss-sdr.svn.sourceforge.net/svnroot/gnss-sdr gnss-sdr

* Build GNSS-SDR

- Go to GNSS-SDR's root directory and compile the program:

$ cd gnss-sdr/trunk
$ bjam

If everything went fine, a executable will be found at gnss-sdr/trunk/install/gnss-sdr


NOTE: If, later on, you want to bring your GNU Radio repository up to date with the original repository of GNU Radio (and test if GNSS-SDR works with it), go to the gnuradio directory and do:

$ sudo make uninstall
$ make clean
$ git pull
$ ./configure
$ make
$ make check
$ sudo make install




Mac OS X 1.6.8 (Snow Leopard)
------------------------------
* If you have still not installed Apple's Developer Tools Xcode, do it now from  http://developer.apple.com/technologies/tools/ (it's free)

* Install Macports from  http://www.macports.org/install.php We recommend to install directly the <20>dmg<6D> disk images for Snow Leopart. GNSS-SDR has not been tested with Leopard or Tiger.

* With your favorite text editor, create a $HOME/user-config.jam file and specify that you want to use the darwin toolset (Apple's version of the GCC toolchain) and doxygen:

using darwin ;
using doxygen ;

* Install GNU Radio:

$ sudo port install gnuradio-core

* Set some variables:

export DYLD_LIBRARY_PATH=/usr/local/lib
export GNURADIO_ROOT= /path/to/gnuradio

where /path/to/gnuradio is the root folder where the source code of GNU Radio is. Currently, it is found in

export GNURADIO_ROOT=/opt/local/var/macports/build/_opt_local_var_macports_sources_rsync.macports.org_release_ports_science_gnuradio-examples/work/gnuradio-3.3.0

In order to avoid defining these variables each time you enter a session, you may want to add these two lines to your $HOME/.bash_profile file.

* Create a symbolic link in order to be able to use the gnuradio-core library from /usr/local/lib

$ sudo ln -s /opt/local/lib/libgnuradio-core.dylib /usr/local/lib/libgnuradio-core.dylib

* Install other tools:

$ sudo port install doxygen graphviz subversion 

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

$ wget http://sourceforge.net/projects/arma/files/armadillo-2.4.2.tar.gz
$ tar xvfz armadillo-2.4.2.tar.gz
$ cd armadillo-2.4.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. The "Accelerate" framework is used for accessing BLAS and LAPACK functions.

- Install Google's performance analysis tools, google-perftools:

$ sudo port install google-perftools
$ sudo ln -s /opt/local/lib/libprofiler.dylib /usr/local/lib/libprofiler.dylib 
$ sudo ln -s /opt/local/lib/libtcmalloc.dylib /usr/local/lib/libtcmalloc.dylib

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

$ 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. The building system of GNSS-SDR does the compilation and linking of gtest its own tests; it is only required that you tell the system where the gtest folder that you downloaded resides. Just add to your $HOME/.bash_profile file the following line:

export GTEST_DIR=/Users/username/gtest-1.6.0

changing /Users/username/gtest-1.6.0 by the actual directory where you unziped gtest. 

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

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

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

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

* Check the repository for the latest version of GNSS-SDR:

- Check out the latest version of GNSS-SDR

$ svn co http://gnss-sdr.svn.sourceforge.net/svnroot/gnss-sdr gnss-sdr

* Build GNSS-SDR

- Go to GNSS-SDR's root directory and compile the program:

$ cd gnss-sdr/trunk
$ bjam

If everything went fine, a executable will be found at gnss-sdr/trunk/install/gnss-sdr

NOTE: During compilation, you might see a harmless message g++: unrecognized option '-no-cpp-precomp'. You can safely ignore it, and even change darwin toolset configuration to remove it: for OS X 10.6.8 I changed /opt/local/share/boost-build/tools/tools/darwin.jam at line 58 like this

#flags darwin.compile OPTIONS : -no-cpp-precomp ;
flags darwin.compile OPTIONS : -std=c++0x ;