Source Installation on Ubuntu#

These instructions apply to Ubuntu Bionic (18.04) and Focal (20.04).

Install tools#

The use of some additional tools is recommended to help with the source compilation, although other ways of correctly getting and building the sources are also possible.

The easiest way to get the sources of all libraries is to use vcstool.

To compile all the different libraries and ign-gazebo in the right order colcon is recommended. The colcon tool is available on all platforms using pip (or pip3, if pip fails).

Some tools require Python 3.5 (or higher) which is not the default option on some platforms (like Ubuntu Bionic). The Python virtualenv could be a useful solution in cases where the default option cannot be easily changed.

Generic tools#

Install tools needed by this tutorial:

sudo apt install python3-pip lsb-release gnupg curl

vcstool and colcon from pip#

PIP is available on all platforms:

pip install vcstool || pip3 install vcstool

pip install -U colcon-common-extensions || pip3 install -U colcon-common-extensions

Check that no errors were printed while installing with PIP. If your system is not recognising the commands, and you’re using a system that is compatible with Debian or Ubuntu packages, see the instructions below to install using apt.

After installing vcstool and colcon with PIP, you may need to add their executables to your $PATH. Check where the installation of these packages took place:

pip show vcstool || pip3 show vcstool | grep Location

pip show colcon-common-extensions || pip3 show colcon-common-extensions | grep Location

If your install path is prefixed with $HOME/.local, you’ll probably need to add the executables within this directory to your $PATH in order to avoid “command not found” errors when using vcstool and colcon later on:

export PATH=$PATH:$HOME/.local/bin/

vcstool and colcon from apt#

An alternative method is to use the .deb packages available on Debian or Ubuntu:

sudo sh -c 'echo "deb http://packages.ros.org/ros/ubuntu $(lsb_release -sc) main" > /etc/apt/sources.list.d/ros-latest.list'
curl -s https://raw.githubusercontent.com/ros/rosdistro/master/ros.asc | sudo apt-key add -
sudo apt-get update
sudo apt-get install python3-vcstool python3-colcon-common-extensions

Git#

Ignition libraries use git for version control, so it must be available in the system for vcstool to work properly.

sudo apt-get install git

Getting the sources#

The first step is to create a developer workspace in which vcstool and colcon can work:

mkdir -p ~/workspace/src
cd ~/workspace/src

All the sources of ignition-citadel are declared in a yaml file. Download it to the workspace:

curl -O https://raw.githubusercontent.com/ignition-tooling/gazebodistro/master/collection-citadel.yaml

Use vcstool to automatically retrieve all the Ignition libraries sources from their repositories:

vcs import < collection-citadel.yaml

The src subdirectory should contain all the sources ready to be built.

Install dependencies#

Before compiling it is necessary to install all the dependencies of the different packages that compose the Citadel collection. Every platform has a different method to install software dependencies.

Add packages.osrfoundation.org to the apt sources list:

sudo sh -c 'echo "deb http://packages.osrfoundation.org/gazebo/ubuntu-stable `lsb_release -cs` main" > /etc/apt/sources.list.d/gazebo-stable.list'
curl https://packages.osrfoundation.org/gazebo.key | sudo apt-key add -
sudo apt-get update

The command below must be run from a workspace with the Gazebo source code and will install all dependencies in Ubuntu:

cd ~/workspace/src
sudo apt -y install \
  $(sort -u $(find . -iname 'packages-'`lsb_release -cs`'.apt' -o -iname 'packages.apt' | grep -v '/\.git/') | sed '/ignition\|sdf/d' | tr '\n' ' ')

Install compiler requirements#

The Ignition Libraries require the gcc compiler version 8 or higher.

Ubuntu Bionic#

Ubuntu Bionic’s default compiler version is not high enough, so the following steps are needed to upgrade. These are not needed on Ubuntu Focal.

To install gcc version 8 on Ubuntu Bionic:

sudo apt-get install g++-8

Set gcc-8 and g++-8 to be the default compilers.

sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-8 800 --slave /usr/bin/g++ g++ /usr/bin/g++-8 --slave /usr/bin/gcov gcov /usr/bin/gcov-8

At this point gcc and g++ should both report version 8. Test this with the following commands.

gcc -v
g++ -v

Building the Ignition Libraries#

Once the compiler and all the sources are in place it is time to compile them. Start the procedure by changing into the workspace and listing the packages recognized by colcon:

cd ~/workspace/
colcon graph

colcon graph should list the Ignition libraries with an interdependency diagram. If that is the case, then you are ready to build the whole set of libraries:

colcon build --merge-install

To speed up the build process, you could also disable tests by using

colcon build --cmake-args -DBUILD_TESTING=OFF --merge-install

To use debuggers activate debug symbols. Gazebo will run slower, but you’ll be able to use GDB:

colcon build --cmake-args ' -DBUILD_TESTING=OFF' ' -DCMAKE_BUILD_TYPE=Debug' --merge-install

To build a specific package with all its dependent packages:

colcon build --merge-install --packages-up-to PACKAGE_NAME

To build a single package:

colcon build --packages-select PACKAGE_NAME

Visit colcon documentation to view more colcon build and test options.

If there are no errors, all the binaries should be ready to use. You can check the [Troubleshooting] section for errors.

Using the workspace#

The workspace needs to be sourced every time a new terminal is used.

Run the following command to source the workspace in bash:

. ~/workspace/install/setup.bash

Or in zsh:

. ~/workspace/install/setup.zsh

This is the end of the source install instructions; head back to the Getting started page to start using Ignition!

Uninstalling source-based install#

A source-based install can be “uninstalled” using several methods, depending on the results you want:

  1. If you installed your workspace with colcon as instructed above, “uninstalling” could be just a matter of opening a new terminal and not sourcing the workspace’s setup.sh. This way, your environment will behave as though there is no Ignition install on your system.

  2. If, in addition to not wanting to use the libraries, you’re also trying to free up space, you can delete the entire workspace directory with:

    rm -rf ~/workspace

  3. If you want to keep the source code, you can remove the install / build / log directories as desired, leaving the src directory.

Troubleshooting#

See Troubleshooting