Home

This wiki contains a guide for installing the advr build system.

The single ''super'' build (the advr 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 well-defined Linux distributions. At the moment Linux Ubuntu 14.04 and 16.04 are supported. 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 "Paolo Guria"
git config --global user.email "paolo.guria@example.com"

Then you need to create your ssh keys to speed up the cloning process (avoid to put username and password everytime using https)

To generate a new SSH key just open your terminal and use code below, after substituting the "paolo.guria@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...

Add RSA identity to the authentication agent:

ssh-add

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 advr build system

git clone git@github.com:ADVRHumanoids/advr-superbuild.git

and download the basic dependencies for ADVR-core

cd advr-superbuild
./scripts/basic_setup.sh

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

Just add these 2 lines on your .bashrc

. /opt/ros/ROS_VERSION/setup.bash
# e.g. . /opt/ros/kinetic/setup.bash

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

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

source ~/.bashrc

finally 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: to start you will need ADVR-CORE 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).

For example if you are part of ADVR Humanoids, you should put ON the SUPERBUILD_ADVR_shared.

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!

If you are part of the ADVR department you have access to ADVR_shared robot models and config files: simply put on SUPERBUILD_ADVR_shared and configure again.

Super Build Workflow

Multiple robotology development workflows are possible.

If you want to build all the enabled projects just type "make" without any argument from the build folder:

cd $ROBOTOLOGY_ROOT
cd build
make

Or just build a single project called SUB_PROJECT_NAME:

cd $ROBOTOLOGY_ROOT
cd build
make SUB_PROJECT_NAME
# e.g. make XCM

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 kdevelop workflow, by selecting the right build folder when opening $ROBOTOLOGY_ROOT/SUB_PROJECT_COMPONENT/SUB_PROJECT_NAME/CMakeLists.txt

• 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 advr-superbuild/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.

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].

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:

parse_git_branch() {
     git branch 2> /dev/null | sed -e '/^[^*]/d' -e 's/* \(.*\)/ (\1)/'
}
export PS1="\u@\h \[\033[32m\]\w\[\033[33m\]\$(parse_git_branch)\[\033[00m\] $ "