ycm-superbuild-example(7)¶

Superbuild Example: User Point of View¶

We show how you can download an example project called example which contains two subprojects:

• TemplatePkg: a package containing the TemplateLib library

• TemplateExe: an executable that uses the TemplateLib library from the TemplatePkg package

Notice that we will not download these subprojects individually. The superbuild will do that for us, all we need to do is to get the superbuild sources, for example cloning the git repository:

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

We will set the SUPERBUILD_ROOT environment variable to the folder that was just created by git. This is not necessary, but if you don’t do it you will have to replace the $SUPERBUILD_ROOT with the actual paths when you run the following commands.

export SUPERBUILD_ROOT=/path/to/the/superbuild/folder

After the build, all the subprojects will be installed inside the build/install folder, therefore in order to use use it you will have to adjust some environment variables:

export PATH=$PATH:$SUPERBUILD_ROOT/build/install/bin/
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$SUPERBUILD_ROOT/build/install/lib/
export CMAKE_PREFIX_PATH=$CMAKE_PREFIX_PATH:$SUPERBUILD_ROOT/build/install/

You can add these exports (and the export SUPERBUILD_ROOT) to your ~/.bashrc file if you don’t want to have to execute them manually every time.

Now go to the directory where you have downloaded the project example, create a build directory

mkdir $SUPERBUILD_ROOT/build
cd $SUPERBUILD_ROOT/build
cmake ..

This will download all the repositories of the individual packages and setup the build system.

Now you can compile the whole project, type:

make

Superbuild Example: Developer Point of View¶

Suppose you want to make a superbuild that contains the following packages:

• TemplatePkg: a package containing the TemplateLib library

• TemplateExe: an executable that uses the TemplateLib library from the TemplatePkg package

Create a folder that will contain your superbuild.

mkdir example-superbuild
cd example-superbuild

Create a CMakeLists.txt with this content:

cmake_minimum_required(VERSION 3.16)

project(example)

set(YCM_USE_CMAKE_PROPOSED ON) # Enables unmerged patches to CMake modules, this is required for the superbuild to work

# makes available local cmake modules
list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake")

# Choose whether you want YCM to be a soft or a hard dependency and uncomment
# the appropriate line:
include(YCMBootstrap) # This will make it a soft dependency
# find_package(YCM 0.1 REQUIRED) # This will make it a hard dependency

include(FindOrBuildPackage)
include(YCMEPHelper)

find_or_build_package(TemplatePkg)
find_or_build_package(TemplateExe)

feature_summary(WHAT ALL INCLUDE_QUIET_PACKAGES FATAL_ON_MISSING_REQUIRED_PACKAGES)

Create a cmake folder that will contain all required CMake modules

mkdir cmake

If you want YCM as a soft dependency you will need to get the files tools/YCMBootstrap.cmake and modules/IncludeUrl.cmake from the YCM sources. If you want to make it a hard dependency you don’t have to add these files, but the user will have to install YCM before he can build the superbuild.

Create the files cmake/BuildTemplatePkg.cmake and cmake/BuildTemplateExe.cmake with the following content:

# TemplatePkg
include(YCMEPHelper)

ycm_ep_helper(TemplatePkg TYPE GIT
                          STYLE GITLAB_ROBOTOLOGY
                          REPOSITORY walkman/template-pkg.git
                          TAG master
                          COMPONENT superbuild)

# TemplateExe
include(YCMEPHelper)
include(FindOrBuildPackage)

find_or_build_package(TemplatePkg QUIET)

ycm_ep_helper(TemplateExe TYPE GIT
                          STYLE GITLAB_ROBOTOLOGY
                          REPOSITORY walkman/template-exe.git
                          TAG master
                          COMPONENT superbuild
                          DEPENDS TemplatePkg)

Now you can compile the superbuild:

mkdir build
cd build
cmake ..
make

This will download the subprojects TemplatePkg and TemplateExe by cloning their repositories. Sources will be in the directory superbuild:

$ cd ..
$ ls superbuild
TemplateExe  TemplatePkg
$ ls superbuild/TemplateExe/
AUTHORS  CMakeLists.txt  COPYING  doc  README  src
...

Binaries for the two subprojects are insted in build/install. For example you can verify that the library form TemplatePkg and the executable in TemplateExe have been correctly compiled:

$ ls build/install/
bin  include  lib
$ ls build/install/lib
cmake  libtemplate-lib.so  libtemplate-lib.so.0.0.1
$ ls build/install/bin
template-exe

Code¶

The code of this superbuild example can be found here:

git@github.com:robotology/superbuild-example.git