robotology superbuild handbook

This handbook contains a guide for installing the robotology build system.

The single ''super'' build (the robotology build) pulls code from all the repositories and compiles everything. This mechanisms work similar to a binary distribution, but it provides access to the source code and ''forces'' everybody to get used to the toolchain. Contributions are favored by the fact that everybody has access to the sources and can compile all the modules.

The modules need to be versioned using the GIT or HG source revision tool. Repositories can be hosted on different servers depending on the choice of the group that maintains it. For example open source code can be hosted on Github.

Requirements

To simplify integration the software is developed and should be tested run on a single well-defined Linux distribution. At the moment this is Linux Ubuntu 14.04. We are currently working to ensure compatibility on Linux Ubuntu 16.04. This can change in the future when new releases are made available and contains important updates.

Installation

The first step to begin the procedure is to install GIT and cmake

sudo apt-get install git cmake cmake-curses-gui

and configure GIT

git config --global user.name "John Doe"
git config --global user.email "john.doe@example.com"

Then you need to create your ssh keys

To generate a new SSH key just open your terminal and use code below, after substituting the "john.doe@example.com" string with the email you are using (you should use the key for all the servers where the code is hosted, e.g. github.com, gitlab.com ...)

ssh-keygen -t rsa -C "john.doe@example.com"
# Creates a new ssh key using the provided email
# Generating public/private rsa key pair...

Next just use code below

cat ~/.ssh/id_rsa.pub
# ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC6eNtGpNGwstc....

and add it to your host ssh key panels, for example Github ssh keys If you wish you can add color in git, and notification of the current branch while navigating folders. See the Additional Steps section for more info.

After configuring git you can download the robotology build system

git clone git@github.com:robotology-playground/robotology-superbuild.git

downloading the basic dependencies for ADVR-core

cd robotology-superbuild
./scripts/basic_setup.sh

and start the building process, selecting the repos that you want to download on your superbuild:

mkdir -p build
cd build
ccmake ..

Here is the view that you should see:

Just type 'c' to execute the cmake configuration step. You should see something like this:

Simply put ON the projects you need (e.g. I am working on WALKMAN robot, so I will put WALKMAN_EU ON).

Do the same for the sub-projects that will appear after configuring again (type 'c' and you will see the available repositories in the projects we put ON).

After choosing the projects, type 'c', wait for the configuration, again 'c', wait for the configuration and then 'g' (generate step).

The superbuild is now configured, enjoy it!

Super Build Workflow

Before starting using the superbuild we need to source the robotology-setup.bash in our .bashrc, in order to update the ENV variables according to the superbuild.

Just add this line on you .bashrc

. /PATH/TO/robotology-setup.bash
# e.g. . /home/lucamuratore/robotology-superbuild/robotology-setup.bash

After the first installation you need to refresh your terminal by sourcing your .bashrc:

source ~/.bashrc

Multiple robotology development workflows are possible. To begin with the easiest, just build a single project called SUB_PROJECT_NAME:

cd $ROBOTOLOGY_ROOT
mkdir build
make SUB_PROJECT_NAME
# e.g. make GYM

You will see that the superbuild will first clone the SUB_PROJECT_NAME repository, then build and install its dependecies as specified in the cmake/BuildSUB_PROJECT_NAME.cmake file and then build and install the SUB_PROJECT_NAME module in the COMPONENT folder specified again in the cmake/BuildSUB_PROJECT_NAME.cmake

In the build folder you will find a set of out-of-source build folders for your module and its dependencies. For example, for SUB_PROJECT_NAME, you will have a folder $ROBOTOLOGY_ROOT/build/SUB_PROJECT_COMPONENT/SUB_PROJECT_NAME

To build and install it you can proceed in two ways:

• Run:

cd $ROBOTOLOGY_ROOT/build/modules/module_a
make
make install

which has the advantage of being easily integrated inside the qtcreator/kdevelop workflow, by selecting the right build folder when opening $ROBOTOLOGY_ROOT/SUB_PROJECT_COMPONENT/SUB_PROJECT_NAME/CMakeLists.txt and adding a build step for installation to the project

• Run:

cd $ROBOTOLOGY_ROOT/build/
make module_a

A note of advice

warning running make module_a from the main build folder (e.g. $ROBOTOLOGY_ROOT/build) first builds all the dependencies of module_a, and it might reset your "custom" CMake variables related to module_a.

Creating a new Project in Github and adding it to the superbuild

From the new repository page, you need to create a new repository for your module. Once you have the new project, let's call it project_x, you need to create a new file inside the robotology/cmake folder named Buildproject_x.cmake You can take any other file in the same folder as example. Once you add the Buildproject_x.cmake file, you need to modify the project CMakeLists.txt file in the superbuild projects folder by adding the line:

# Compile project_x
find_or_build_package_with_tag(project_X OFF)

Then you can add the modifications to robotology and push them:

git add cmake/Buildproject_x.cmake
git add projects/project_x_PROJECT_NAME/CMakeLists.txt
git commit -m "Added project_x to the project_x_PROJECT_NAME"
git push origin master

Freezing dependencies and modules versions

By writing the correct hashtag for dependency or modules in the cmake/ProjectsTags.cmake file it is possible to use a specific set of tags for a build.

Simulation, Robot, Default profiles

One can activate the simulation (control time and simulation time are in sync) or default profile (for use with the robot) by running the (self-explanatory) script

setup.sh

The setup script will call the desired scripts in order to configure the system (e.g. profiles/default/activate-local.sh and profiles/simulation/activate-local.sh)

Known Issues

When editing the include files of my library, I lose changes

When you install your includes, your IDE might prefer to redirect you to the installed versions rather than the one in your src folder when following an #include directive in your code. You might risk not noticing this if you are not used to the workflow of installing your libraries locally. You should therefore list your include files in your CMakeLists.txt file, you can take a look at several other projects already in the superbuild to see how this is done. By doing this you will have a list of includes listed in your IDE which you can edit directly, making sure they come from the src folder instead of the install folder. This step is allowed and encouraged by CMake to communicate to the IDE the list of include files in your project and does not disrupt the compilation process since (the header files are skipped when compiling)[http://www.cmake.org/cmake/help/v2.8.12/cmake.html#prop_sf:HEADER_FILE_ONLY].

Also remember that in qtcreator hovering the mouse over the filename in the top bar shows a tooltip with the full filename.

Additional Steps

You can increase your productivity in using git by following the steps below:

Some Color

Colors in git are very useful, you can enable them by running:

git config --global color.pager true
git config --global color.ui auto

Bash Prompt

Modify your ~/.bashrc file with:

if [ "$color_prompt" = yes ]; then
    PS1='${debian_chroot:+($debian_chroot)}\[\033[01;32m\]\u@\h\[\033[00m\]:\[\033[01;34m\]\w\[\033[00m\]\[\033[00;32m\]$(__git_ps1 " (%s)")\[\033[00m\]\$ '
else
    PS1='${debian_chroot:+($debian_chroot)}\u@\h:\w$(__git_ps1 " (%s)")\$ '
fi