Ubitrack Compilation for Linux on Linux

##1. Introduction

This wiki page will explain the instructions which are needed in order to compile Ubitrack from source for Linux. It contains the installation of the required build-tools, the setup of the buildenvironment and introduces the three methods to configure the needed libraries.

##2. How to install build-tools

Ubuntu is shipped with gcc and python pre-installed, to install Git and Scons, open up a terminal and type:

sudo apt-get install git scons

##3. Setting up the buildenvironment

Change your current directory of the terminal to the folder where you want to clone ubitrack and run:

cd ~/mylibraries/
git clone https://github.com/Ubitrack/buildenvironment.git ubitrack
cd ubitrack

##4. Adding the Ubitrack submodules

As explained in Home, Ubitrack consists of several submodules. In order to add them, there are two possibilies: Executing a bash script which adds all submodules automatically or adding them manually.

##4.a Automized adding submodules

Open a terminal, make sure you are in the <ubitrack> directory and execute:

sh misc/setup/linux/addStandardModules.sh

By that, all submodule folders are created in <ubitrack>/module/ and the source files are downloaded.

##4.b Manually adding submodules

This example will create the <ubitrack>/module/utcore directory and add utcore as submodule. Therefore, you have to execute

git submodule add https://github.com/Ubitrack/utcore.git modules/utcore

inside the <ubitrack> directory.

##5. Downloading and Configuring the required libraries

As already mentioned, there exist three ways to configure the required libraries. The first uses the Ubitrack library finder which needs all the libraries in one specific folder and represents the easiest way. The second, configures the libraries by the command line and gives you the ability to set the include, lib and lib_debug paths of each library. In the third method, each possible configuration and path is manually set by editing a textfile which is automatically generated if you have chosen the first or second method.

###5.1 Downloading and Configuring the required libraries - the easy way

If you have not already done, yet, you can download and install BOOST, LAPACK and Freeglut with the terminal:

sudo apt-get update
sudo apt-get install libboost-all-dev libblas-dev liblapack-dev libopencv-dev freeglut3-dev

As the Ubitrack library finder requires all library files in a certain folder structure, which was explained in Home, and the libraries were installed to the /usr/lib/ folder, an easy way is to link from the external_libraries folder to the and /usr/lib/ and /usr/local/include/ folder. This example shows how it is done for linux_x64-architecture:

mkdir -p linux_x64/boost/lib/
mkdir -p linux_x64/boost/include/


//linking for boost
ln -s /usr/lib/libboost_filesystem.* boost/include/lib/
ln -s /usr/lib/libboost_program_options.* boost/include/lib/
ln -s /usr/lib/libboost_regex.* boost/include/lib/
ln -s /usr/lib/libboost_serialization.* boost/include/lib/
ln -s /usr/lib/libboost_system.* boost/include/lib/
ln -s /usr/lib/libboost_thread.* boost/include/lib/

ln -s /usr/include/boost boost/include/include/

//linking for lapack
mkdir -p lapack/lib
ln -s /usr/lib/lapack/liblapack.a lapack/lib/
ln -s /usr/lib/lapack/liblapack.so lapack/lib/
ln -s /usr/lib/lapack/libblas.a lapack/lib/
ln -s /usr/lib/lapack/llibblas.so lapack/lib/

//linking for freeglut
mkdir -p glut/lib
mkdir -p glut/include
ln -s /usr/lib/x86_64-linux-gnu/libglut* glut/lib/
ln -s /usr/include/GL/ glut/include/

For OpenCV have a look at the official Guide OpenCV Installation in Linux or a special Ubuntu-Guide OpenCV on Ubuntu. After that, the libraries and header files can be linked to the external_libraries folder:

//linking for opencv
mkdir -p opencv/lib
mkdir -p opencv/include

If you have placed the libraries in a different folder to <ubitrack>/external_libraries, you have to specify the path where Ubitrack has to search for the libraries. This can be done by executing the following command in the <ubitrack> folder:

scons EXTERNAL_LIBRARIES=/home/user/my_libraries/

Alternatively, you can execute

scons

and afterwards add the following line manually to the <ubitrack>/config.cache file: Note: The first time this document may be empty.

EXTERNAL_LIBRARIES = '/home/user/my_libraries/'

###5.2 Configure the libraries using command line options and library finder

In this method, the library configuration is done by appending parameters to a scons call similar to the previous section. This method gives you the ability to define your own library-folder structure as you may already have installed some of the libraries in different directories. Just like in the previous section, you can write the parameters into a <ubitrack>\config.cache document, alternatively. If you have not already downloaded the libraries, yet, have a look at section 5.1. where some download sources are mentioned.

The basic syntax for these parameters looks like this:

<LIBNAME>_<PARAMERTER>_<PLATFORM>_<CONFIGURATION>

Examples:

<LIBNAME>:
 - BOOST, OPENCV, LAPACK, GLUT

<PARAMETER>: 
- INCLUDEPATH (path to include files)
- LIBPATH (path to library files)
- LIBS (comma separated list of library files to link against)
- DEFINES (C++ defines passed to the compiler )

<PLATFORM>: 
- x64 (64bit)
- x86 (32bit)
- android (armeabi-v7a)

<CONFIGURATION>:
- RELEASE (in this case empty) 
- DEBUG

Full Examples for library configurations by a scons call:

scons BOOST_LIBPATH=/home/user/boost/libs
scons BOOST_LIBPATH_DEBUG=/home/user/boost/lib_debug
scons BOOST_LIBPATH_X86_DEBUG=/home/user/boost/x64/debug
scons OPENCV_LIBS="opencv_stitching242.lib, opencv_legacy242.lib"

###5.3 Set everything by hand

Run the scons command once. After that the library configurations are stored in <ubitrack>/config/configStorage. Edit the files and set Include/Library Paths and Libraries to link against.

Set havelib to true and add "HAVE_{LIBNAME}" to CPPDEFINES:

havelib = true
cppdefines = ["HAVE_LAPACK"]

Full Example for OpenCV:

[linux2_x64_release]
havelib = true
cpppath = ["/home/far/mylibs/opencv/include"]
libpath = ["/home/far/mylibs/opencv/lib"]
libs = ["libopencv_contrib.so", "libopencv_core.so", "libopencv_highgui.so", "libopencv_features2d.so", "libopencv_calib3d.so", "libopencv_stitching.so", "libopencv_objdetect.so", "libopencv_gpu.so", "libopencv_photo.so", "libopencv_superres.so", "libopencv_nonfree.so", "libopencv_legacy.so", "libopencv_video.so", "libopencv_ml.so", "libopencv_ocl.so", "libopencv_imgproc.so", "libopencv_flann.so", "libopencv_videostab.so"]
cppdefines = ["HAVE_OPENCV"]

###6. Compile Ubitrack

For the compilation of Ubitrack for Windows/Linux run:

scons install-all

For the compilation of Ubitrack for Android you have to specify the android-platform once. This configuration will stay until it is changed by e.g. PLATFORM=x64.

scons PLATFORM=android
scons install-all

Speed up the build process for parallel builds:

scons install-all -j{NumProcessors} 

Clean the build by calling:

scons -c

You can see all command line parameters by calling:

scons -h

Create a Visual Studio Project:

scons vcproj