Skip to content

Commit 5f30f92

Browse files
azeeyazeey
committed
Add documentation for Gazebo vendor packages
Signed-off-by: Addisu Z. Taddese <addisu@openrobotics.org>
1 parent b13c551 commit 5f30f92

File tree

3 files changed

+190
-0
lines changed

3 files changed

+190
-0
lines changed

‎index.yaml

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,11 @@ pages:
2323
title: ROS/Gazebo Installation
2424
file: ros_installation.md
2525
description: Our development plans.
26+
children:
27+
- name: ros2_gz_vendor_pkgs
28+
title: ROS 2 Gazebo Vendor Packages
29+
file: ros2_gz_vendor_pkgs.md
30+
description: Using ROS 2 Gazebo Vendor packages
2631
- name: migrating_gazebo_classic_ros2_packages
2732
title: Migration from ROS 2 Gazebo Classic
2833
file: migrating_gazebo_classic_ros2_packages.md

‎ros2_gz_vendor_pkgs.md

Lines changed: 177 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
1+
# ROS 2 Gazebo Vendor Packages
2+
3+
ROS 2 versions prior to Jazzy used Gazebo packages that were available in
4+
upstream Ubuntu. However, due to the package
5+
[update policy of Ubuntu](https://wiki.ubuntu.com/StableReleaseUpdates), the
6+
Gazebo packages on upstream Ubuntu did not receive any updates. Thus, upstream
7+
Ubuntu almost always had older versions of Gazebo than what was available from
8+
the Gazebo package repository (packages.osrfoundation.org). To overcome this,
9+
more up-to-date Gazebo packages were copied to the ROS bootstrap repository
10+
(repos.ros.org) which were then copied to the main ROS package repository
11+
(packages.ros.org). However, the process was error prone and keeping package
12+
versions in sync between the Gazebo and ROS package repositories was difficult
13+
since this was a manual process.
14+
15+
As of ROS 2 Jazzy, Gazebo is available from the ROS package repository via
16+
vendor packages. A ROS vendor package is a ROS package that provides software
17+
that ROS needs on platforms where it might not be available, or where a
18+
different version than what is available is required [^1].
19+
20+
The Gazebo vendor packages provide all of the Gazebo libraries to a given ROS
21+
release. The packages are built in the ROS buildfarm and as part of their build
22+
process, fetch the sources of the underlying Gazebo library and build it. In
23+
addition, the vendor packages provide CMake shims that make it possible to use
24+
CMake targets without version numbers.
25+
26+
Each release of ROS 2 is paired with a specific release of Gazebo. For ROS 2
27+
Jazzy, the vendor packages contain Gazebo libraries from the Harmonic release.
28+
For ROS 2 K-turtle (next release), the vendor packages will contain Gazebo
29+
Ionic. This default pairing is found in the
30+
[ROS installation instructions](https://gazebosim.org/docs/harmonic/ros_installation)
31+
32+
The following is a table of all vendor packages and the underlying Gazebo
33+
library they vendor:
34+
35+
| Vendor Package | Gazebo Library |
36+
| -------------------------------------------------------------------------------- | ----------------------------------------------------------- |
37+
| [gz_cmake_vendor](https://github.com/gazebo-release/gz_cmake_vendor) | [gz-cmake](https://github.com/gazebosim/gz-cmake) |
38+
| [gz_common_vendor](https://github.com/gazebo-release/gz_common_vendor) | [gz-common](https://github.com/gazebosim/gz-common) |
39+
| [gz_fuel_tools_vendor](https://github.com/gazebo-release/gz_fuel_tools_vendor) | [gz-fuel-tools](https://github.com/gazebosim/gz-fuel-tools) |
40+
| [gz_gui_vendor](https://github.com/gazebo-release/gz_gui_vendor) | [gz-gui](https://github.com/gazebosim/gz-gui) |
41+
| [gz_launch_vendor](https://github.com/gazebo-release/gz_launch_vendor.git) | [gz-launch](https://github.com/gazebosim/gz-launch) |
42+
| [gz_math_vendor](https://github.com/gazebo-release/gz_math_vendor.git) | [gz-math](https://github.com/gazebosim/gz-math) |
43+
| [gz_msgs_vendor](https://github.com/gazebo-release/gz_msgs_vendor.git) | [gz-msgs](https://github.com/gazebosim/gz-msgs) |
44+
| [gz_physics_vendor](https://github.com/gazebo-release/gz_physics_vendor.git) | [gz-physics](https://github.com/gazebosim/gz-physics) |
45+
| [gz_plugin_vendor](https://github.com/gazebo-release/gz_plugin_vendor.git) | [gz-plugin](https://github.com/gazebosim/gz-plugin) |
46+
| [gz_rendering_vendor](https://github.com/gazebo-release/gz_rendering_vendor.git) | [gz-rendering](https://github.com/gazebosim/gz-rendering) |
47+
| [gz_sensors_vendor](https://github.com/gazebo-release/gz_sensors_vendor.git) | [gz-sensors](https://github.com/gazebosim/gz-sensors) |
48+
| [gz_sim_vendor](https://github.com/gazebo-release/gz_sim_vendor.git) | [gz-sim](https://github.com/gazebosim/gz-sim) |
49+
| [gz_tools_vendor](https://github.com/gazebo-release/gz_tools_vendor.git) | [gz-tools](https://github.com/gazebosim/gz-tools) |
50+
| [gz_transport_vendor](https://github.com/gazebo-release/gz_transport_vendor.git) | [gz-transport](https://github.com/gazebosim/gz-transport) |
51+
| [gz_utils_vendor](https://github.com/gazebo-release/gz_utils_vendor.git) | [gz-utils](https://github.com/gazebosim/gz-utils) |
52+
| [sdformat_vendor](https://github.com/gazebo-release/sdformat_vendor.git) | [sdformat](https://github.com/gazebosim/sdformat) |
53+
54+
In addition to Gazebo libraries, two dependencies of Gazebo are also vendored:
55+
56+
| Vendor Package | External Library |
57+
| -------------------------------------------------------------------------------- | -------------------------------------------------- |
58+
| [gz_dartsim_vendor](https://github.com/gazebo-release/gz_dartsim_vendor.git) | [dartsim](https://github.com/dartsim/dart) |
59+
| [gz_ogre_next_vendor](https://github.com/gazebo-release/gz_ogre_next_vendor.git) | [ogre-next](https://github.com/OGRECave/ogre-next) |
60+
61+
**Note:** These two vendor packages are only intended to be consumed by Gazebo.
62+
Use of this vendor package generally (outside of Gazebo) is not recommended as
63+
the underlying library version might change without notice.
64+
65+
## Using vendor packages in `package.xml`
66+
67+
To use a Gazebo vendor package in your project, you'll need to add the
68+
appropriate package in your `package.xml`. For example, if you use the Gazebo
69+
libraries `gz-cmake`, `gz-utils` and `gz-math`, the entries in `package.xml`
70+
will be the following
71+
72+
```xml
73+
...
74+
<depend>gz_cmake_vendor</depend>
75+
<depend>gz_utils_vendor</depend>
76+
<depend>gz_math_vendor</depend>
77+
...
78+
```
79+
80+
## Using vendor packages in CMake
81+
82+
To use a Gazebo library provided by a vendor package, you'll need to
83+
`find_package` the vendor package and the underlying Gazebo library. Calling
84+
`find_package` on the vendor package indicates that the project is "buying into"
85+
the CMake shims provided by the vendor package. These shims make it possible to
86+
`find_package` the underlying library and use its CMake targets without
87+
including the version number in the name. Thus, when upgrading to newer versions
88+
of Gazebo, the project `CMakeLists` file would not need to be modified.
89+
90+
Following the example above, The CMake entry for using `gz-cmake`, `gz-utils`
91+
and `gz-math` will be the following:
92+
93+
```cmake
94+
find_package(gz_cmake_vendor REQUIRED)
95+
find_package(gz-cmake REQUIRED)
96+
find_package(gz_utils_vendor REQUIRED)
97+
find_package(gz-utils REQUIRED)
98+
find_package(gz_math_vendor REQUIRED)
99+
find_package(gz-math REQUIRED)
100+
101+
add_executable(test_gz_vendor main.cc)
102+
target_link_libraries(test_gz_vendor PUBLIC gz-math::gz-math gz-utils::gz-utils)
103+
```
104+
105+
**Note:** The vendor packages use underscores (`_`) while the Gazebo library
106+
names use dashes (`-`).
107+
108+
## Using vendor packages with binaries from packages.osrfoundation.org
109+
110+
If you want to use a new release of Gazebo that is not officially paired with
111+
the release of ROS you are using (e.g. Gazebo Ionic with ROS 2 Jazzy), you can
112+
follow the following steps:
113+
114+
1. Install the binaries from packages.osrfoundation.org. Make sure to install
115+
the metapackage that includes all library components (e.g. gz-ionic,
116+
gz-harmonic, etc.)
117+
1. Clone the set of vendor packages included in
118+
[gz_vendor.repos](https://gist.github.com/azeey/a94adb591475ea0e613313d3540ca451)
119+
in your workspace using [vcstool](https://github.com/dirk-thomas/vcstool).
120+
1. Checkout the desired branch. The branch names currently track ROS 2 releases.
121+
You'll need to determine the branch based on the
122+
[default pairings](/docs/latest/ros_installation)
123+
1. Add any additional packages you need that also depend on Gazebo, such as
124+
[`ros_gz`](https://github.com/gazebosim/ros_gz) and
125+
[`gz_ros2_control`](https://github.com/ros-controls/gz_ros2_control/)
126+
1. `export GZ_RELAX_VERSION_MATCH=1`. By default, the vendor packages look for
127+
an exact version match of the vendored library to be available in the system.
128+
If the exact version is not found, the sources are fetched and built. This
129+
environment variable causes the vendor package to match just the major
130+
version number.
131+
1. Build the workspace
132+
133+
## Gazebo library development with vendor packages
134+
135+
Building the underlying packages from source might be needed when using a Gazebo
136+
release that is not officially paired with the ROS release you are using or when
137+
developing on a Gazebo library in conjunction with another ROS package that uses
138+
Gazebo directly. You can follow these steps to build the vendor packages from
139+
source:
140+
141+
1. Clone the desired release of the Gazebo libraries into a workspace. You can
142+
use a collection file from <https://github.com/gazebo-tooling/gazebodistro>
143+
(e.g.
144+
[`collection-harmonic.yaml`](https://github.com/gazebo-tooling/gazebodistro/blob/master/collection-harmonic.yaml))
145+
with [vcstool](https://github.com/dirk-thomas/vcstool).
146+
1. Clone the set of vendor packages included in
147+
[gz_vendor.repos](https://gist.github.com/azeey/a94adb591475ea0e613313d3540ca451)
148+
in the same workspace using
149+
[vcstool](https://github.com/dirk-thomas/vcstool).
150+
1. Checkout the desired branch. The branch names currently track ROS 2 releases.
151+
You'll need to determine the branch based on the
152+
[official pairings](/docs/latest/ros_installation)
153+
1. Add any additional packages you need that also depend on Gazebo, such as
154+
[`ros_gz`](https://github.com/gazebosim/ros_gz) and
155+
[`gz_ros2_control`](https://github.com/ros-controls/gz_ros2_control/)
156+
1. `export GZ_BUILD_FROM_SOURCE=1`. By default, the vendor packages look for an
157+
exact version match of the vendored library to be available in the system. If
158+
the exact version is not found, the sources are fetched and built. Also, by
159+
default, the vendor packages do not depend directly on the Gazebo libraries
160+
you have in your workspace. Setting this environment variable causes the
161+
vendor package to match just the major version number and add dependencies on
162+
the Gazebo libraries being built from source so that the correct build order
163+
is followed.
164+
1. Build the workspace
165+
166+
## Known Limitations
167+
168+
- The vendor packages are currently built with Python bindings disabled
169+
([issue](https://github.com/gazebo-tooling/gz_vendor/issues/2))
170+
- `gz_dartsim_vendor` and `gz_ogre_next_vendor` currently always build from
171+
source
172+
([gz_dartsim_vendor issue](https://github.com/gazebo-release/gz_dartsim_vendor/issues/4),
173+
[gz_ogre_next_vendor issue](https://github.com/gazebo-release/gz_ogre_next_vendor/issues/4))
174+
- When building Gazebo libraries from source, it is not possible to build some
175+
packages from source and install some packages from binaries.
176+
177+
[^1]: https://robotics.stackexchange.com/a/93262/31574

‎ros_installation.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,14 @@ sudo apt-get install ros-${ROS_DISTRO}-ros-gz
7171
This command will install the Gazebo libraries recommended for your ROS
7272
installation.
7373

74+
### ROS 2 Gazebo Vendor packages
75+
76+
As of ROS 2 Jazzy, Gazebo is available from the ROS package repository via
77+
vendor packages. If your package directly depends on a Gazebo library,
78+
instead of relying only on `ros_gz`, refer to
79+
[this documentation](ros2_gz_vendor_pkgs) to learn how to use the
80+
Gazebo vendor packages.
81+
7482
<div class="warning">
7583
The rest of this document provides more information and other, alternative,
7684
installations pathways. We do not recommend the following approaches for new

0 commit comments

Comments
 (0)