---
name: "ycm-superbuild-example"
section: "7"
platform: "linux"
package: "ycm-cmake-modules"
version: "0.13.0-2"
release: "Debian 12 (Bookworm)"
platforms: ["linux"]
url: "https://new.carta.tech/ycm-superbuild-example"
---

# ycm-superbuild-example(7)

YCM Superbuild Example This page shows an example of superbuild. The first section shows how you can compile and work with it (i.e. the point of view of a user), the second section shows how the superbuild is implemented (i.e. point of view of a developer).

## NAME

ycm-superbuild-example - YCM Superbuild Example

This page shows an example of superbuild. The first section shows how you can compile and work with it (i.e. the point of view of a user), the second section shows how the superbuild is implemented (i.e. point of view of a developer).

## 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.12)
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

## COPYRIGHT

Copyright 2012-2021 Istituto Italiano di Tecnologia (IIT)