ROS 2 Gazebo Vendor Packages#
History of Gazebo packaging before ROS 2 Jazzy#
ROS 2 versions prior to Jazzy used Gazebo packages that were available in upstream Ubuntu. However, due to the package update policy of Ubuntu, the Gazebo packages on upstream Ubuntu did not receive any updates. Thus, upstream Ubuntu almost always had older versions of Gazebo than what was available from the Gazebo package repository (packages.osrfoundation.org). To overcome this, more up-to-date Gazebo packages were copied to the ROS bootstrap repository (repos.ros.org) which were then copied to the main ROS package repository (packages.ros.org). However, the process was error prone and keeping package versions in sync between the Gazebo and ROS package repositories was difficult since this was a manual process.
Gazebo vendor packages#
As of ROS 2 Jazzy, Gazebo is available from the ROS package repository via vendor packages. A ROS vendor package is a ROS package that provides software that ROS needs on platforms where it might not be available, or where a different version than what is available is required [1].
The Gazebo vendor packages provide all of the Gazebo libraries to a given ROS release. The packages are built in the ROS buildfarm and as part of their build process, fetch the sources of the underlying Gazebo library and build it. In addition, the vendor packages provide CMake shims that make it possible to use CMake targets without version numbers.
Each release of ROS 2 is paired with a specific release of Gazebo. For ROS 2 Jazzy, the vendor packages contain Gazebo libraries from the Harmonic release. For ROS 2 K-turtle (next release), the vendor packages will contain Gazebo Ionic. This default pairing is found in the ROS installation instructions
The following is a table of all vendor packages and the underlying Gazebo library they vendor:
Vendor Package |
Gazebo Library |
|---|---|
In addition to Gazebo libraries, two dependencies of Gazebo are also vendored:
Vendor Package |
External Library |
|---|---|
Note: These two vendor packages are only intended to be consumed by Gazebo. Use of this vendor package generally (outside of Gazebo) is not recommended as the underlying library version might change without notice.
Running Gazebo from vendor packages#
To be able to use the gz command to run the usual commands, be sure that at least
gz_tools_vendor package is installed. To have the gz command in the PATH,
source the setup.bash from /opt/ros/${ROS_DISTRO} as usual.
# Example running gz sim on Jazzy
export ROS_DISTRO=jazzy
sudo apt-get install ros-${ROS_DISTRO}-gz-tools-vendor ros-${ROS_DISTRO}-gz-sim-vendor
. /opt/ros/jazzy/setup.bash
gz sim --help
Building packages using Gazebo vendor packages#
Declaring dependencies in package.xml#
To use a Gazebo vendor package in your project, you’ll need to add the
appropriate package in your package.xml. For example, if you use the Gazebo
libraries gz-cmake, gz-utils and gz-math, the entries in package.xml
will be the following
...
<depend>gz_cmake_vendor</depend>
<depend>gz_utils_vendor</depend>
<depend>gz_math_vendor</depend>
...
CMakeLists.txt for building with Gazebo vendor packages#
To use a Gazebo library provided by a vendor package, you’ll need to
find_package the vendor package and the underlying Gazebo library. Calling
find_package on the vendor package indicates that the project is “buying into”
the CMake shims provided by the vendor package. These shims make it possible to
find_package the underlying library and use its CMake targets without
including the version number in the name. Thus, when upgrading to newer versions
of Gazebo, the project CMakeLists.txt file would not need to be modified.
Following the example above, The CMake entry for using gz-cmake, gz-utils
and gz-math will be the following:
find_package(gz_cmake_vendor REQUIRED)
find_package(gz-cmake REQUIRED)
find_package(gz_utils_vendor REQUIRED)
find_package(gz-utils REQUIRED)
find_package(gz_math_vendor REQUIRED)
find_package(gz-math REQUIRED)
add_executable(test_gz_vendor main.cc)
target_link_libraries(test_gz_vendor PUBLIC gz-math::gz-math gz-utils::gz-utils)
Note: The vendor packages use underscores (_) while the Gazebo library
names use dashes (-).
Expert use cases#
The documentation provided above should cover the users that require to install and run the Gazebo simulator together with ROS and developing code that requires of Gazebo and ROS.
Below are listed more advanced topics for the expert users.
Installing Non-Default Gazebo/ROS 2 Pairings with vendor packages#
If you want to use a new release of Gazebo that is not officially paired with the release of ROS you are using (e.g. Gazebo Ionic with ROS 2 Jazzy), you can follow the following steps:
Install the binaries from packages.osrfoundation.org. Make sure to install the metapackage that includes all library components (e.g. gz-ionic, gz-harmonic, etc.)
Clone the set of vendor packages included in gz_vendor.repos in your workspace using vcstool.
Checkout the desired branch. The branch names currently track ROS 2 releases. You’ll need to determine the branch based on the default pairings
Add any additional packages you need that also depend on Gazebo, such as
ros_gzandgz_ros2_controlexport GZ_RELAX_VERSION_MATCH=1. By default, the vendor packages look for an exact version match of the vendored library to be available in the system. If the exact version is not found, the sources are fetched and built. This environment variable causes the vendor package to match just the major version number.Build the workspace
Gazebo library development with vendor packages#
Building the underlying packages from source might be needed when using a Gazebo release that is not officially paired with the ROS release you are using or when developing on a Gazebo library in conjunction with another ROS package that uses Gazebo directly. You can follow these steps to build the vendor packages from source:
Clone the desired release of the Gazebo libraries into a workspace. You can use a collection file from gazebo-tooling/gazebodistro (e.g.
collection-harmonic.yaml) with vcstool.Clone the set of vendor packages included in gz_vendor.repos in the same workspace using vcstool.
Checkout the desired branch. The branch names currently track ROS 2 releases. You’ll need to determine the branch based on the official pairings
Add any additional packages you need that also depend on Gazebo, such as
ros_gzandgz_ros2_controlexport GZ_BUILD_FROM_SOURCE=1. By default, the vendor packages look for an exact version match of the vendored library to be available in the system. If the exact version is not found, the sources are fetched and built. Also, by default, the vendor packages do not depend directly on the Gazebo libraries you have in your workspace. Setting this environment variable causes the vendor package to match just the major version number and add dependencies on the Gazebo libraries being built from source so that the correct build order is followed.Build the workspace
Known Limitations#
The vendor packages are currently built with Python bindings disabled (issue)
gz_dartsim_vendorandgz_ogre_next_vendorcurrently always build from source (gz_dartsim_vendor issue, gz_ogre_next_vendor issue)When building Gazebo libraries from source, it is not possible to build some packages from source and install some packages from binaries.