As a huge number of software projects are developed in the robotology organization, and a tipical user is only interested in some of them, there are several options to
instruct the superbuild on which packages should be built and which one should not be built. In particular, the robotology-superbuild is divided in different "profiles",
that specify the specific subset of robotology packages to build.
The profile CMake options specify which subset of the robotology packages will be built by the superbuild.
Note that any dependencies of the included packages that is not available in the system will be downloaded, compiled and installed as well.
All these options are named ROBOTOLOGY_ENABLE_<profile> .
| CMake Option | Description | Main packages included | Default Value | Profile-specific documentation |
|---|---|---|---|---|
ROBOTOLOGY_ENABLE_CORE |
The core robotology software packages, necessary for most users. | YARP, ICUB, ICUBcontrib, icub-models, robots-configurations and ergocub-software. GazeboYARPPlugins if the ROBOTOLOGY_USES_GAZEBO option is enabled. gym-ignition if the ROBOTOLOGY_USES_IGNITION option is enabled. |
ON |
Documentation on Core profile. |
ROBOTOLOGY_ENABLE_ROBOT_TESTING |
The robotology software packages related to robot testing. | RobotTestingFramework, icub-tests, blocktest and blocktest-yarp-plugins |
OFF |
Documentation on Robot Testing profile. |
ROBOTOLOGY_ENABLE_DYNAMICS |
The robotology software packages related to balancing, walking and force control. | iDynTree, blockfactory, wb-Toolbox, whole-body-controllers, walking-controllers, matioCpp, robometry. Furthermore, osqp-matlab and matlab-whole-body-simulator if ROBOTOLOGY_USES_MATLAB option is enabled. |
OFF |
Documentation on Dynamics profile. |
ROBOTOLOGY_ENABLE_DYNAMICS_FULL_DEPS |
bipedal-locomotion-framework and its dependencies. |
bipedal-locomotion-framework, manif, qhull, casadi, CppAD, yarp-device-keyboard-joypad robot-log-visualizer if ROBOTOLOGY_USES_PYTHON option is enabled. |
OFF |
Documentation on Dynamics full deps profile. |
ROBOTOLOGY_ENABLE_ICUB_HEAD |
The robotology software packages needed on the system that is running on the head of the iCub robot, or in general to communicate directly with iCub low-level devices. | icub-firmware, icub-firmware-shared. Furthermore, several additional devices are compiled in YARP and ICUB if this option is enabled. |
OFF |
Documentation on iCub Head profile. |
ROBOTOLOGY_ENABLE_ICUB_BASIC_DEMOS |
The robotology software packages needed to run basic demonstrations with the iCub robot. | icub-basic-demos, speech, funny-things. |
OFF |
Documentation on iCub Basic Demos profile. |
ROBOTOLOGY_ENABLE_TELEOPERATION |
The robotology software packages related to teleoperation. | walking-teleoperation, https://github.com/ami-iit/yarp-openvr-trackers and https://github.com/ami-iit/yarp-device-openxrheadset. |
OFF |
Documentation on teleoperation profile. |
ROBOTOLOGY_ENABLE_HUMAN_DYNAMICS |
The robotology software packages related to human dynamics estimation. | human-dynamics-estimation, wearables, yarp-devices-forcetorque. For options check the profile documentation. |
OFF |
Documentation on human dynamics profile. |
ROBOTOLOGY_ENABLE_EVENT_DRIVEN |
The robotology software packages related to event-driven. | event-driven |
OFF |
Documentation on event-driven profile. |
ROBOTOLOGY_ENABLE_GRASPING |
The robotology software packages related to grasping. | find-superquadric if the ROBOTOLOGY_USES_PCL_AND_VTK option is enabled. |
OFF |
Documentation on grasping profile. |
If any of the packages required by the selected profiles is already available in the system (i.e. it can be found by the find_package CMake command ), it will be neither downloaded, nor compiled, nor installed. In robotology-superbuild, this check is done by the find_or_build_package YCM command in the main CMakeLists.txt of the superbuild.
By default, the superbuild will use the package already available in the system. If the user wants to ignore those packages and have two different versions of them, then he/she should set the CMake variable USE_SYSTEM_<PACKAGE> to FALSE. For further details, please refer to YCM Superbuild Manual for Developers.
The dependencies CMake options specify if the packages dependending on something installed in the system should be installed or not. All these options are named ROBOTOLOGY_USES_<dependency>.
| CMake Option | Description | Default Value | Dependency-specific documentation |
|---|---|---|---|
ROBOTOLOGY_USES_GAZEBO |
Include software and plugins that depend on the Gazebo Classic simulator. | ON |
Documentation on Gazebo Classic dependency. |
ROBOTOLOGY_USES_GZ |
Include software and plugins that depend on the Modern Gazebo (gz-sim) simulator. | OFF |
Documentation on Modern Gazebo (gz-sim) dependency. |
ROBOTOLOGY_USES_MUJOCO |
Include software and plugins that depend on the MuJoCo simulator. | ON |
Documentation on MuJoCo dependency. |
ROBOTOLOGY_USES_PCL_AND_VTK |
Include software and plugins that depend on the PCL or VTK. | OFF |
Documentation on PCL and VTK dependency. |
ROBOTOLOGY_USES_IGNITION |
Include software that depends on Ignition. | OFF |
Documentation on Ignition Gazebo dependency. |
ROBOTOLOGY_USES_MATLAB |
Include software and plugins that depend on the Matlab. | OFF |
Documentation on MATLAB dependency. |
ROBOTOLOGY_USES_OCTAVE |
Include software and plugins that depend on Octave. | OFF |
Documentation on Octave dependency. |
ROBOTOLOGY_USES_PYTHON |
Include software that depends on Python. | OFF |
Documentation on Python dependency. |
ROBOTOLOGY_USES_CFW2CAN |
Include software and plugins that depend on CFW2 CAN custom board. | OFF |
No specific documentation is available for this option, as it is just used with the iCub Head profile, in which the related documentation can be found. |
ROBOTOLOGY_USES_XSENS_MVN_SDK |
Include software and plugins that depend on Xsens MVN SDK. | OFF |
Documentation on Xsens MVN dependency |
ROBOTOLOGY_USES_ESDCAN |
Include software and plugins that depend on Esd Can bus. | OFF |
Documentation on ESDCAN dependency |
Not all options are supported on all platforms. The following table provides a recap of which options are supported on each platform.
| Option | Ubuntu/Debian, dependencies: apt | Windows, dependencies: vcpkg | conda on Linux, dependencies: conda-forge | conda on macOS, dependencies: conda-forge | conda on Windows, dependencies: conda-forge |
|---|---|---|---|---|---|
ROBOTOLOGY_ENABLE_CORE |
✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
ROBOTOLOGY_ENABLE_ROBOT_TESTING2! |
✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
ROBOTOLOGY_ENABLE_DYNAMICS |
✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
ROBOTOLOGY_ENABLE_DYNAMICS_FULL_DEPS |
✔️ | ❌ | ✔️ | ✔️ | ✔️ |
ROBOTOLOGY_ENABLE_ICUB_HEAD |
✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
ROBOTOLOGY_ENABLE_ICUB_BASIC_DEMOS |
✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
ROBOTOLOGY_ENABLE_TELEOPERATION |
✔️ | ❌ | ✔️ | ❌ | ✔️ |
ROBOTOLOGY_ENABLE_HUMAN_DYNAMICS |
✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
ROBOTOLOGY_ENABLE_EVENT_DRIVEN |
✔️ | ❌ | ✔️ | ❌ | ❌ |
ROBOTOLOGY_ENABLE_GRASPING |
✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
ROBOTOLOGY_USES_GAZEBO |
✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
ROBOTOLOGY_USES_GZ3! |
✔️ | ❌ | ✔️ | ✔️ | ✔️ |
ROBOTOLOGY_USES_MUJOCO1! |
✔️ | ❌ | ✔️ | ✔️ | ✔️ |
ROBOTOLOGY_USES_PCL_AND_VTK |
✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
ROBOTOLOGY_USES_IGNITION |
❌ | ❌ | ✔️ | ❌ | ❌ |
ROBOTOLOGY_USES_MATLAB |
✔️ | ❌ | ✔️ | ✔️ | ✔️ |
ROBOTOLOGY_USES_OCTAVE4! |
✔️ | ❌ | ❌ | ) ❌ | ❌ |
ROBOTOLOGY_USES_PYTHON |
✔️ | ❌ | ✔️ | ✔️ | ✔️ |
ROBOTOLOGY_USES_CFW2CAN |
✔️ | ❌ | ✔️ | ❌ | ❌ |
ROBOTOLOGY_USES_XSENS_MVN_SDK |
❌ | ✔️ | ❌ | ❌ | ❌ |
ROBOTOLOGY_USES_ESDCAN |
❌ | ✔️ | ❌ | ❌ | ✔️ |
1!:ROBOTOLOGY_USES_MUJOCO does not support building with apt dependencies on Debian or Ubuntu distributions older than 2022. Furthermore, it does not support build on Windows with Visual Studio 2019, it requires Visual Studio 2022.
2!:ROBOTOLOGY_ENABLE_ROBOT_TESTING does not support building with conda-forge dependencies on Apple Silicon.
3!:ROBOTOLOGY_USES_GZ with apt dependencies do not support building on Debian distros (only Ubuntu is supported). Furthermore it does not run on Windows (gazebosim/gz-sim#2089) and have known problems on macOS (robotology/gz-sim-yarp-plugins#90).
4!:ROBOTOLOGY_USES_OCTAVE do not support building with apt dependencies on Ubuntu 20.04.
This profile is enabled by the ROBOTOLOGY_ENABLE_CORE CMake option.
Follow the steps in https://icub-tech-iit.github.io/documentation/sw_installation/check_your_installation/#check-icub to verify if your installation was successful.
This profile is enabled by the ROBOTOLOGY_ENABLE_ROBOT_TESTING CMake option.
On Windows, this profile creates some long paths during the build process. If you enable it, it is recommended to keep the total path length of the robotology-superbuild build directory below 50 characters, or to enable the support for long path in Windows following the instructions in the official Windows documentation.
If the profile has been correctly enabled and compiled, you should be able to run the robottestingframework-testrunner and blocktestrunner executable from the command line.
This profile is enabled by the ROBOTOLOGY_ENABLE_DYNAMICS CMake option.
This profile is enabled by the ROBOTOLOGY_ENABLE_DYNAMICS_FULL_DEPS CMake option.
Since 2023.05, ROBOTOLOGY_ENABLE_DYNAMICS_FULL_DEPS is not supported with vcpkg dependencies on Windows.
This profile is enabled by the ROBOTOLOGY_ENABLE_ICUB_HEAD CMake option. It is used in the system installed on iCub head,
or if you are a developer that needs to access iCub hardware devices directly without passing through the iCub head.
Warning: the migration of existing iCub setups to use the robotology-superbuild is an ongoing process, and it is possible that your iCub still needs to be migrated. For any doubt, please get in contact with icub-support.
The configuration and compilation of this profile is supported on Linux, macOS and Windows systems.
On Linux all the software necessary to communicate with boards contained in the robot, including CAN devices via esd's CAN USB bridges, is already included.
On Windows to communicate with CAN devices via esd's CAN USB bridges you need to set to ON the Windows-only CMake option ROBOTOLOGY_ENABLE_ESDCAN.
On macOS, communication with esd's CAN USB bridges.
This section documents the iCub Head profile as any other profile, in a way agnostic of the specific machine in which it is installed. To get information on how to use the robotology-superbuild to install software on the machine mounted in the head of physical iCub robots, please check the documentation in the official iCub documentation.
The steps necessary to install the system dependencies of the iCub Head profile are provided in operating system-specific installation documentation, and no additional required system dependency is required.
On old iCub systems equipped with the CFW2 CAN board, it may be necessary to have the cfw2can driver
installed on the iCub head (it is tipically already pre-installed in the OS image installed in the system in the iCub head). In that
case, you also need to enable the ROBOTOLOGY_USES_CFW2CAN option to compile the software that depends on cfw2can. In case of doubt,
please always get in contact with icub-support.
The ROBOTOLOGY_ENABLE_ICUB_HEAD installs several YARP devices for communicating directly with embedded boards of the iCub.
To check if the installation was correct, you can list all the available YARP devices using the yarpdev --list command,
and check if devices whose name is starting with embObj are present in the list. If those devices are present, then the installation should be working correctly.
This profile is enabled by the ROBOTOLOGY_ENABLE_ICUB_BASIC_DEMOS CMake option.
If the iCub Basic Demos profile have been correctly installed, you should be able to find in your PATH and execute the demoYoga or demoRedBall executables.
This profile is enabled by the ROBOTOLOGY_ENABLE_TELEOPERATION CMake option.
To run a teleoperation scenario, with real robot or in simulation, at least we need a Windows machine and Linux/macOS machine. If you are using iCub, the linux/macOS source code can be placed on the robot head. The teleoperation dependencies are also related to the teleoperation scenario you want to perform.
This profile is enabled by the ROBOTOLOGY_ENABLE_HUMAN_DYNAMICS CMake option.
To run a human dynamics estimation scenario, we need a Windows machine to install the Xsens suit SDK for getting the sensory information of the human motions from Xsens and ESD USB CAN driver to get the FTShoes/FTSkShoes sensory information. Refer to Xsens and ESDCAN for more information about the dependencies.
This profile is enabled by the ROBOTOLOGY_ENABLE_EVENT_DRIVEN CMake option. For the moment, Windows is not a supported platform.
Support for this dependency is enabled by the ROBOTOLOGY_USES_GAZEBO CMake option, that enables the software that depends on "Classic Gazebo".
Follow the steps in https://github.com/robotology/icub-models#use-the-models-with-gazebo to check if the Gazebo-based iCub simulation works fine.
Support for this dependency is enabled by the ROBOTOLOGY_USES_GZ CMake option, that enables the software that depends on "Modern Gazebo" (gz-sim).
Important
At the moment the ROBOTOLOGY_USES_GZ does not run on Windows (gazebosim/gz-sim#2089) and have known problems on macOS (robotology/gz-sim-yarp-plugins#90). Furthermore, it is not supported on non-Ubuntu Debian distributions with apt dependencies.
Support for this dependency is enabled by the ROBOTOLOGY_USES_MUJOCO CMake option, that enables the software that depends on MuJoCo. Note that differently from other ROBOTOLOGY_USES_<..> options, in this case the main dependency (MuJoCo) is compiled by the superbuild.
Support for this dependency is enabled by the ROBOTOLOGY_USES_PCL_AND_VTK CMake option, that enables the software that depends on PCL or VTK libraries.
Support for this dependency is enabled by the ROBOTOLOGY_USES_IGNITION CMake option.
This option is set to OFF on all platforms as it is still experimental.
Different Ignition distributions can be installed alongside. The projects included in the superbuild might require different distributions. From the superbuild point of view, we currently do not allow enabling projects that only support a specific Ignition distribution, therefore all required distributions have to be found in the system.
Follow the source installation with conda-forge provided dependencies and, after creating and environment and installing the default dependencies, execute:
conda install -c conda-forge libignition-gazebo6Follow the official instructions to install Ignition on your platform, available at https://ignitionrobotics.org/docs.
Note: this installation method is not currently tested in Continuous Integration.
Support for this dependency is enabled by the ROBOTOLOGY_USES_MATLAB CMake option.
Warning: differently from other optional dependencies, MATLAB is a commercial product that requires a license to be used.
If MATLAB is not installed on your computer, install it following the instruction in https://mathworks.com/help/install/ .
The minimum version of MATLAB supported by the robotology-superbuild is R2022a.
Once you installed it, make sure that the directory containing the matlab executable is present in the PATH of your system,
as CMake's FindMatlab module relies on this to find MATLAB.
Note: tipically we assume that a user that selects the ROBOTOLOGY_USES_MATLAB also has Simulink installed in his computer.
If this is not the case, you can enable the advanced CMake option ROBOTOLOGY_NOT_USE_SIMULINK to compile all the subprojects that depend on MATLAB, but disable the subprojecs that depend on Simulink (i.e. the
wb-toolbox Simulink Library) if you have enabled the ROBOTOLOGY_ENABLE_DYNAMICS CMake options.
If MATLAB is installed on your computer, the robotology-superbuild can install some projects that depend on MATLAB, among the others:
- the MATLAB bindings of the iDynTree library,
- the native MATLAB bindings of YARP, contained in the yarp-matlab-bindings repository,
- The WB-Toolbox Simulink toolbox,
- The whole-body-controllers Simulink-based balancing controllers. Note that whole-body-controllers can be installed and compiled also without MATLAB, but its functionalities are reduced.
- The matlab-whole-body-simulator Simulink-based whole-body dynamics simulator with contacts handling.
To use this software, you can simply enable its compilation using the ROBOTOLOGY_USES_MATLAB CMake option.
Once this software has been compiled by the superbuild, you just need to add some directories of the robotology-superbuild install (typically $ROBOTOLOGY_SUPERBUILD_SOURCE_DIR/build/install) to the MATLAB path.
In particular you need to add to the MATLAB path:
- the
$ROBOTOLOGY_SUPERBUILD_INSTALL_PREFIX/mexdirectory, - the
$ROBOTOLOGY_SUPERBUILD_INSTALL_PREFIX/share/WBToolboxdirectory and all its subdirectories (except the packages which are folder names starting with "+"), - the library
$ROBOTOLOGY_SUPERBUILD_INSTALL_PREFIX/mex/+wbc/simulink, - the controller model examples
$ROBOTOLOGY_SUPERBUILD_INSTALL_PREFIX/mex/+wbc/examples.
You could add this line to your MATLAB script that uses the robotology-superbuild matlab software, substituting <ROBOTOLOGY_SUPERBUILD_INSTALL_PREFIX> with the install folder inside the build directory of the superbuild:
addpath(['<ROBOTOLOGY_SUPERBUILD_INSTALL_PREFIX>' '/mex'])
addpath(['<ROBOTOLOGY_SUPERBUILD_INSTALL_PREFIX>' '/mex/+wbc/simulink'])
addpath(['<ROBOTOLOGY_SUPERBUILD_INSTALL_PREFIX>' '/mex/+wbc/examples'])
addpath(['<ROBOTOLOGY_SUPERBUILD_INSTALL_PREFIX>' '/share/WBToolbox'])
addpath(['<ROBOTOLOGY_SUPERBUILD_INSTALL_PREFIX>' '/share/WBToolbox/images'])
Another way is to run (only once) the script startup_robotology_superbuild.m in the $ROBOTOLOGY_SUPERBUILD_SOURCE_DIR/build folder. This should be enough to permanently add the required paths for all the toolbox that use MATLAB.
You can add the folders by modifying the startup.m or the MATLABPATH environmental variable as described in official MATLAB documentation.
If you are using the setup.sh or setup.bat script for configuring your environment, MATLABPATH is automatically populated with these directories.
For more info on configuring MATLAB software with the robotology-superbuild, please check the wb-toolbox README.
To verify that the compilation of ROBOTOLOGY_USES_MATLAB option was successful, try to run a script that uses
the Matlab bindings of yarp and see if it executes without any error, for example:
yarpVec = yarp.Vector();
yarpVec.resize(3);
yarpVec.fromMatlab([1;2;3]);
yarpVec.toMatlab()This scripts should print a 1 2 3 vector, but only if the yarp bindings are working correctly.
If executing this script you obtain a "Invalid MEX-file ..." error, please check how to solve this problem in the related FAQ question in robotology-superbuild's README.
Support for this dependency is enabled by the ROBOTOLOGY_USES_OCTAVE CMake option.
The ROBOTOLOGY_USES_OCTAVE option is not supported when dependencies are installed by conda-forge.
Add the $ROBOTOLOGY_SUPERBUILD_SOURCE_DIR/build/install/octave directory to your Octave path.
To verify that the compilation of ROBOTOLOGY_USES_OCTAVE option was successful, try to run a script that uses
the Octave bindings of yarp and see if it executes without any error, for example:
yarpVec = yarp.Vector();
yarpVec.resize(3);
yarpVec.fromMatlab([1;2;3]);
yarpVec.toMatlab()This scripts should print a 1 2 3 vector, but only if the yarp bindings are working correctly.
Support for this dependency is enabled by the ROBOTOLOGY_USES_PYTHON CMake option.
Install Python and the necessary development files using the following command:
cd robotology-superbuild
sudo bash ./scripts/install_apt_python_dependencies.sh
To install python and the other required dependencies when using conda-forge provided dependencies, use:
conda install -c conda-forge python numpy swig pybind11 pyqt matplotlib h5py tornado u-msgpack-python pyzmq ipython
On Windows, enabling the ROBOTOLOGY_USES_PYTHON requires some care. If you need to enable both ROBOTOLOGY_USES_PYTHON and ROBOTOLOGY_ENABLE_DYNAMICS_FULL_DEPS, you need to make sure that
you have the "C++ Clang Compiler for Windows" and "C++ Clang-cl for vXYZ build tools" components of Visual Studio are installed, you can install them from the Visual Studio Installer:
Furthermore, due to Python ignoring the directories in PATH, before running python code that uses the superbuild dependencies you need to run before:
import os
os.add_dll_directory(os.path.join(os.environ['ROBOTOLOGY_SUPERBUILD_INSTALL_PREFIX'], bin))see #1268 for more details.
Open a python interpreter and try to import modules, for example verify that import yarp works.
Support for ROBOTOLOGY_USES_XSENS_MVN_SDK option is only enabled when the ROBOTOLOGY_ENABLE_HUMAN_DYNAMICS CMake option is set to ON.
Warning: at the moment the Xsens MVN SDK does not support macOS and Linux, so this option is only supported on Windows.
To check and install the Xsens MVN SDK, please follow the steps for Xsens MVN SDK mentioned in here.
To configure the Xsens MVN SDK please follow the steps for Xsens MVN SDK mentioned in here.
The ROBOTOLOGY_USES_ESDCAN option is used to enable support for interacting with esd CAN devices on Windows. On Linux no special option is necessary, as the interconnection with esd CAN device is supported using the default SocketCAN Linux driver. Use of esd CAN devices is not supported in macOS .
To compile the software enabled by the ROBOTOLOGY_USES_ESDCAN option (such as the icub-main's ecan YARP driver) you need to install the esd CAN C library.
To install this library in conda, just run conda install -c conda-forge -c robotology esdcan inside your conda environment. If you installed icub-main from conda binary packages, the ecan YARP driver enabled by the ROBOTOLOGY_USES_ESDCAN option is already included.
To actually run the software that uses the esd CAN devices, you also need to install the esd CAN Driver for your specific esd CAN device. The installers for the esd CAN Driver should have been provided by esd, so ask for them to who provided you with the esd CAN device you want to use.
No additional configuration is required to use the software installed by the ROBOTOLOGY_USES_ESDCAN
Open a terminal, and check that amoung the device listed by yarpdev --list the ecan YARP device is listed.