mc_rtc superbuild

This project is a superbuild project for mc_rtc and related projects.

It will build all mc_rtc dependencies, mc_rtc itself and downstream projects. You can also extend the project locally or clone extensions to build your own projects.

Requirements

• CMake >= 3.20
• Git
• Visual Studio 2019 and later (Windows)

Installing the requirements (bootstraping)

You can fullfill the requirements above by invoking our bootstraping script:

git clone https://github.com/mc-rtc/mc-rtc-superbuild

• on Debian like distributions: ./mc-rtc-superbuild/utils/bootstrap-linux.sh
• on macOS: ./mc-rtc-superbuild/utils/bootstrap-macos.sh

Usage

First, make sure you have configured git:

git config --global user.name "Full Name"
git config --global user.email "your.email@provider.com"

Then configure and run the superbuild as follows:

# Run the bootstrap script in mc-rtc-superbuild/utils folder if required
cmake -S mc-rtc-superbuild -B mc-rtc-superbuild/build -DSOURCE_DESTINATION=${HOME}/devel/src -DBUILD_DESTINATION=${HOME}/devel/build
cmake --build mc-rtc-superbuild/build --config RelWithDebInfo

This will:

1. Install all required system dependencies
2. Create a meta-repository at SOURCE_DESTINATION (the folder must be empty or already created by another superbuild instance)
3. Add Git submodules for each of the projects in the meta-repository
4. Build each project in the ${BUILD_DESTINATION}/${PROJECT} folder and install it in the provided ${CMAKE_INSTALL_PREFIX}

You can then use the projects that were built and cloned by the superbuild as you would use projects you built and clone yourself. If you modify some projects, the superbuild will pick up on it and rebuild its dependents.

Note

On Linux and macOS, all commands of the form cmake --build ${FOLDER} --config RelWithDebInfo --target ${TARGET} can also be run by make ${TARGET} in ${FOLDER}. In particular, you can start a build by simply doing make in the build folder.

You should avoid running something like make -jN. This will build up to N projects in parallel but each project will run its own parallelized build and that will likely be too much for your machine RAM or CPU.

Separate clone and build

If you want to clone everything before attempting the first build you can use the clone target:

git clone https://github.com/mc-rtc/mc-rtc-superbuild
cmake -S mc-rtc-superbuild -B mc-rtc-superbuild/build -DSOURCE_DESTINATION=${HOME}/devel/src -DBUILD_DESTINATION=${HOME}/devel/build
cd mc-rtc-superbuild/build
cmake --build . --config RelWithDebInfo --target clone
cmake --build . --config RelWithDebInfo

Update the repositories

You can run the update target to pull all the projects:

cmake --build . --config RelWithDebInfo --target update

Or invididually pull some of the projects and their dependencies:

cmake --build . --config RelWithDebInfo --target update-mc_rtc

Update mc-rtc-superbuild and extensions

You can run the self-update target to update mc-rtc-superbuild and all the cloned extensions:

cmake --build . --config RelWithDebInfo --target self-update

Uninstall projects

You can run the uninstall target to uninstall all the projects at once:

cmake --build . --target uninstall

It might require sudo if you install to a non-writable prefix (e.g. /usr/local)

You cam also uninstall a specific project:

cmake --build . --target uninstall-mc_rtc

Extensions

You can add extensions to the superbuild system by cloning extensions projects into the extensions folder, see for example the lipm-walking-controller-superbuild for an example centered around a single project.

cd mc-rtc-superbuild/extensions
git clone https://github.com/mc-rtc/lipm-walking-controller-superbuild
cd ../build/
# Will build mc_rtc and then the lipm-walking-controller project and its dependencies
cmake --build . --config RelWithDebInfo

You can also check out superbuild-extensions for commonly availabe extensions. Please refer to this repository for usage instructions.

Options

The following CMake options can be passed:

Adding your own projects

You can:

• Add new AddProject declaration to the main CMakeLists.txt of this repository (look for PERSONAL_PROJECTS in that file to find the correct location)
• Create a new extension under the extensions folder:

  mkdir -p extensions/local
  editor extensions/local/CMakeLists.txt

• Create a simple .cmake under the extensions folder with your projects:

  touch extensions/local.cmake
  editor extensions/local.cmake

The remainder is an introduction of the functions offered by superbuild to specify your own project.

AddProject

AddProject specifies a new project, here is a simple example:

AddProject(lipm_walking_controller
  GITHUB mehdi-benallegue/lipm_walking_controller
  GIT_TAG origin/rebase_stabilizer_ana
  DEPENDS copra mc_state_observation mc_plugin_footstep_plan_msgs
)

Here:

• GITHUB is a git source (see AddGitSource for available options and how to extend them)
• GIT_TAG is the branch or tag that we use for this repository. It defaults to origin/main. When GIT_TAG starts with origin/ it is interpreted as a branch otherwise it is interpreted as a tag
• DEPENDS are other projects that are depended upon

Other options for AddProject are:

• SUBFOLDER <folder>: clone the repository in a subfolder of SOURCE_DESTINATION
• CLONE_ONLY: do not perform any build step, only clone the repository
• SKIP_TEST: do not run or build unit tests
• NO_NINJA: use CMake's default generator rather than ninja
• NO_SOURCE_MONITOR: disable source monitoring. By default, superbuild will monitor the source folder to force the rebuild of packages and their dependents when change happens. Some projects systematically trigger rebuilds under this monitor and this option disable it. Rebuilds then have to be triggered manually via the force-${NAME} target.
• SKIP_SYMBOLIC_LINKS: disable the creation of symbolic links. By default, on supported platforms, superbuild creates a link between the source folder and the build folder as well as a link from the source folder to the CMake's generated compile_commands.json. This option disables the behavior.
• INSTALL_PREFIX: override the provided CMAKE_INSTALL_PREFIX

For advanced usage, other options supported by ExternalProject_Add are also supported by AddProject.

In particular, CMAKE_ARGS, CONFIGURE_COMMAND, BUILD_COMMAND and INSTALL_COMMAND can be used to control the build.

CreateCatkinWorkspace

CreateCatkinWorkspace(ID <id> DIR <dir> {CATKIN_MAKE|CATKIN_BUILD} [CATKIN_BUILD_ARGS <args>...])

Declare a catkin workspace:

• <id> must be unique throughout the superbuild and its extensions
• <dir> is a directory (relative to SOURCE_DESTINATION) where the workspace is created
• CATKIN_MAKE/CATKIN_BUILD whether to build the workspace with catkin_make or catkin build
• <args> are passed as build arguments to catkin build when it is used

AddCatkinProject

** AddCatkinProject(<name> WORKSPACE <id> [<options>]...)

Adds a catkin project into the provided workspace. The git repository is provided through the same way as with AddProject.

If WITH_ROS_SUPPORT is OFF then this is treated like AddProject

AddPackageToCatkinSkiplist

** AddPackageToCatkinSkiplist(<id> <package>)

Adds the given package to the catkin build's skiplist

AddGitSource

AddGitSource(<id> <uri>)

Adds a new git source to superbuild:

• <id> unique id that can be used in subsequent AddProject commands
• <uri> corresponding Git URI (such that repository stubs can be appended to form full URIs)

superbuild knows the following source:

• GITHUB which is https://github.com/
• GITHUB_PRIVATE which is git@github.com:
• GITE which is git@gite.lirmm.fr:
• GIT_REPOSITORY which is empty, allowing one to put arbitrary fully qualified Git URI

AddProjectPlugin

AddProjectPlugin(<name> <project> [SUBFOLDER <folder>] [LINK_NAME <name>] [<options>]...)

Clone the project inside the provided SUBFOLDER of <project>. Other options are passed to AddProject but CLONE_ONLY is always enabled.

By default, the project is cloned in an hidden folder (due to submodule limitations) and linked inside the specified project's source directory as ${SUBFOLDER}/${NAME}. LINK_NAME can override this behavior and create the link to ${SUBFOLDER}/${LINK_NAME}.

AptInstall

AptInstall(<package> ...)

Wrapper around the apt command to install system packages. The function does nothing on non-Debian-based systems. Otherwise it installs the provided packages that are missing.

The packages specified by calling these commands will be installed together at the end of the configuration process. If the packages are required immediately you can use AptInstallNow.

RequireExtension

RequireExtension(FOLDER ...)

This allows an extension to require another extension and make sure this extension is included before the one being processed.

Supported arguments are the one of FetchContent_Declare