Superbuild Installation¶

This is a meta repository (so-called “superbuild”) that uses CMake and YCM to automatically download and compile software developed in the OpenSim2Real GitHub organization. This superbuild is based on the robotology-superbuild.

CMake is an open-source, cross-platform family of tools designed to build, test and package software. A YCM Superbuild is a CMake project whose only goal is to download and build several other projects. If you are familiar with ROS, it is something similar to catkin or colcon workspace, but using pure CMake for portability reasons and for customizing the build via CMake options.

Support Policy¶

C++	Python	Ignition	Ubuntu	macOS	Windows
>= gcc8, clang6	>= 3.8	Fortress (binary)	>= 20.04	No	No

Superbuild Options¶

All optional builds that are supported by the superbuild are listed in the table below.

CMake Options¶
`<CMAKE_ARG>`	Default	Dependencies	Feature Description
`OPENSIM2REAL_ENABLE_CORE`	`FALSE`	deps	Enable compilation of core dependencies for the real robot. All the dependencies required to build monopod_sdk externally. Requires same dependencies as monopod sdk option.
`OPENSIM2REAL_ENABLE_ALL`	`FALSE`	deps	Enable compilation of every package. Entire Open Sim2Real software stack. Contains components for both simulation and real. gym-os2r can be used to train on real and simultion monopod.
`OPENSIM2REAL_ENABLE_MONOPODSDK`	`FALSE`	deps	Enable compilation of monopod_sdk. monopod_sdk is a realtime SDK for monopod platform. Allows user to control the monopod hardware.
`OPENSIM2REAL_ENABLE_SCENARIO`	`FALSE`	deps	Enable compilation of scenario. ScenarIO interface. This option has another sub option `OPENSIM2REAL_ENABLE_SCENARIO_MONOPOD` which will determine whether to install the scenario_monopod plugin on top of ScenarIO.
`OPENSIM2REAL_ENABLE_SCENARIO_MONOPOD`	`FALSE`	deps	Enable compilation of scenario_monopod. scenario_monopod real-time backend plugin for scenario. this plugin provides a real-time backend for the monopod platform.
`OPENSIM2REAL_ENABLE_GYMIGNITION`	`FALSE`	deps	Install gym_ignition python package. Requires python to be enabled. gym-ignition python package.
`OPENSIM2REAL_ENABLE_GYMOS2R`	`FALSE`	deps	Install gym_os2r python package. Requires python to be enabled.
`OPENSIM2REAL_ENABLE_GYMOS2R_REAL`	`FALSE`	deps	Install gym_os2r_real python package. Requires python to be enabled.
`OPENSIM2REAL_USES_PYTHON`	`TRUE`	–	Enable compilation of software that depend on Python.
`OPENSIM2REAL_ENABLE_BUILDDOCS`	`FALSE`	deps	Compile entire projects docs. Requires OPENSIM2REAL_ENABLE_ALL=TRUE. Allows developers to rebuild the projects documentation webpage.
`OPENSIM2REAL_ENABLE_SIMULATION`	same value as the OPENSIM2REAL_ENABLE_ALL	–	Enable compilation of the components that require the ignition gazebo simulator. If FALSE ignition gazebo is not a required dependency. By default this will be the same value as the OPENSIM2REAL_ENABLE_ALL option. Must be enabled to compile python bindings and modules.

When installing components using the superbuild options you only have to set the desired option to True. All other dependencies required to install that option will be adjusted accordingly. The only exception to this is OPENSIM2REAL_ENABLE_BUILDDOCS or if the user changes the OPENSIM2REAL_USES_PYTHON option.

Additional CMake Options¶
`<CMAKE_ARG>`	Default	Feature Description
`CMAKE_BUILD_TYPE`	`Release`	Choose the type of build, recommended options are: Debug or Release
`DOPENSIM2REAL_PROJECT_TAGS`	`Stable`	The tags to be used for the OPENSIM2REAL projects: Stable, Unstable, LatestRelease or Custom. This can be changed only before the first configuration.
`OPENSIM2REAL_PROJECT_TAGS_CUSTOM_FILE`	–	If OPENSIM2REAL_PROJECT_TAGS is custom, this file will be loaded to specify the tags of the projects to use.
`YCM_DISABLE_SYSTEM_PACKAGES`	`TRUE`	Disable use of all the system installed packages

Building and Installation¶

After selecting the desired build option and installing the corresponding dependencies you can build the superbuild. To configure and build any of the above options follow the general steps below.

cd <Install Dir>
git clone git@github.com:OpenSim2Real/os2r-superbuild.git
cd os2r-superbuild
cmake -S . -B build <CMAKE_OPTIONS>
cmake --build build

The <CMAKE_OPTIONS> will be a list of arguments formatted in the following way,

Single arg: -D<CMAKE_ARG>:BOOL=TRUE/FALSE
Multiple args: -D<CMAKE_ARG1>:BOOL=TRUE/FALSE -D<CMAKE_ARG2>:BOOL=TRUE/FALSE ...

For example to install all components and compile the documentation the command will become.

cmake -S . -B build -DOPENSIM2REAL_ENABLE_ALL:BOOL=TRUE -DOPENSIM2REAL_ENABLE_BUILDDOCS:BOOL=TRUE
cmake --build build

To update the repos in the superbuild make sure you are in the build directory of the os2r-superbuild and run:

make update-all
make

Tip

To update the superbuild (change the build option or update the repos) it might be necessary to remove the os2r-superbuild/build and os2r-superbuild/src folders then reconfigure and build the project. Sometimes update-all is not sufficient.

Warning

Before building any option that requires python please make sure the following pip/python packages are uninstalled: gym-ignition, scenario, and idyntree.

Attention

You might need to restart your computer after installing the dependencies before building the superbuild.

Tip

If you are having issues with dependencies and building try installing ignition even if you are only using hardware build options.

Sourcing Environment¶

To use the installed superbuild there are two ways to source the environment with the setup.sh. Either source the script each time you open a new terminal that needs access to the superbuild or add the setup.sh script to your ~/.bashrc. For both options make sure to replace <Install Dir> with the corresponding absolute path.

Sourcing the script after launching a new terminal can be done with the following command:

source <Install Dir>/os2r-superbuild/build/install/share/os2r-superbuild/setup.sh

Automatically source the environment every time the terminal is launched by calling the following commands a single time.

echo 'source <Install Dir>/os2r-superbuild/build/install/share/os2r-superbuild/setup.sh' >> ~/.bashrc
source ~/.bashrc

Options Dependencies¶

Each build option has different required dependencies. Please refer to the dependencies that match your build configuration. Alternatively you can install all dependencies following the All Dependencies.

All Dependencies¶

Dependencies required to build the superbuild options: OPENSIM2REAL_ENABLE_ALL, OPENSIM2REAL_ENABLE_SCENARIO_MONOPOD, OPENSIM2REAL_ENABLE_GYMOS2R, OPENSIM2REAL_ENABLE_GYMOS2R_REAL.

If you want to install the ignition gazebo components of the project then Install Ignition Gazebo. This is not necessary to install any option by default except OPENSIM2REAL_ENABLE_ALL which sets the default value for OPENSIM2REAL_ENABLE_SIMULATION to True.
Apt dependencies

sudo apt-add-repository universe
sudo apt update
sudo apt upgrade
sudo apt-get install -y build-essential \
                        cmake \
                        python3-sphinx \
                        doxygen \
                        python3-breathe \
                        python3-pybind11 \
                        libboost-all-dev \
                        freeglut3-dev \
                        libedit-dev \
                        libxmu-dev \
                        libncurses-dev \
                        libcereal-dev \
                        coinor-libipopt-dev \
                        libirrlicht-dev \
                        libassimp-dev \
                        swig

Further Dependencies

sudo apt update
sudo apt install python3-pip
pip3 install cmake_build_extension gym gym_ignition_models scipy numpy

Monopod Sdk¶

Dependencies required to build the superbuild options: OPENSIM2REAL_ENABLE_MONOPODSDK, or OPENSIM2REAL_ENABLE_CORE.

sudo apt-add-repository universe
sudo apt update
sudo apt upgrade
sudo apt-get install -y build-essential \
                        cmake \
                        python3-sphinx \
                        doxygen \
                        python3-breathe \
                        python3-pybind11 \
                        libboost-all-dev \
                        freeglut3-dev \
                        libedit-dev \
                        libxmu-dev \
                        libncurses-dev \
                        libcereal-dev

Simulation Only¶

Dependencies required to build the superbuild options: OPENSIM2REAL_ENABLE_GYMIGNITION, OPENSIM2REAL_ENABLE_GYMOS2R, OPENSIM2REAL_ENABLE_SCENARIO when the OPENSIM2REAL_ENABLE_SIMULATION option is set to be True. By default OPENSIM2REAL_ENABLE_SIMULATION is False, therefore, these installation dependencies is only needed when OPENSIM2REAL_ENABLE_SIMULATION option is changed from default.

When you set the option OPENSIM2REAL_ENABLE_GYMOS2R:BOOL=TRUE and OPENSIM2REAL_ENABLE_SIMULATION:BOOL=TRUE you will install all of the code required to use gym_os2r package in simulation only.

Install Ignition Gazebo
Apt dependencies

sudo apt-add-repository universe
sudo apt update
sudo apt upgrade
sudo apt-get install -y build-essential \
                        cmake \
                        libxml2-dev \
                        libboost-all-dev \
                        libeigen3-dev \
                        coinor-libipopt-dev \
                        libirrlicht-dev \
                        libassimp-dev \
                        swig

Further Dependencies

sudo apt update
sudo apt install python3-pip
pip3 install cmake_build_extension gym gym_ignition_models scipy numpy

Documentation Compilation¶

Dependencies required to build the superbuild options: OPENSIM2REAL_ENABLE_BUILDDOCS Requires OPENSIM2REAL_ENABLE_ALL to also be enabled. To compile the docs it is necessary to install all dependencies of OPENSIM2REAL_ENABLE_ALL alongside the additional dependencies below.

pip install sphinx-multiversion sphinx_autodoc_typehints sphinx_fontawesome sphinx_book_theme sphinx_tabs lxml sphinx-copybutton pydot sphinxcontrib-bibtex sphinxcontrib-youtube
pip install -U breathe
sudo apt install -y graphviz

To update the published docs to the new built docs you can use the below commands. This is for developers of the project only and require permissions to publish. This is not the easiest way to do it however it is only using the command line.

cd <Install Dir>/os2r-superbuild
git checkout gh-pages
git rm -r -f .
mv  -v ./build/html/* ./
rm -f -r build src
echo '' >> .nojekyll
git add .
git commit -m "publish new docs"
git push

Ignition Gazebo Installation¶

Required ignition gazebo version can be found in the Support Policy. Please install ignition gazebo following binary installation instructions on the ignition website (Installing from source also works but is unnecessary).

Note

It maybe be necessary to add the following to your bashrc.

export IGN_GAZEBO_PHYSICS_ENGINE_PATH=${IGN_GAZEBO_PHYSICS_ENGINE_PATH}:/usr/lib/x86_64-linux-gnu/ign-physics-5/engine-plugins/

To add it you can simply run the following code.

echo 'export IGN_GAZEBO_PHYSICS_ENGINE_PATH=${IGN_GAZEBO_PHYSICS_ENGINE_PATH}:/usr/lib/x86_64-linux-gnu/ign-physics-5/engine-plugins/' >> ~/.bashrc

Note

If you had an old version of ignition installed prior you might need to remove the config folder: Ignition should create a new one the next time it starts.

mv $HOME/.ignition $HOME/.ignition_bak

If there are still folder errors, try to create the folder yourself

mkdir -p $HOME/.ignition/gazebo/6