diff --git a/garden/install_ubuntu.md b/garden/install_ubuntu.md index 1afcdc371..10360f054 100644 --- a/garden/install_ubuntu.md +++ b/garden/install_ubuntu.md @@ -4,7 +4,10 @@ Garden binaries are provided for Ubuntu Focal and Jammy. The Garden binaries are hosted in the packages.osrfoundation.org repository. To install all of them, the metapackage `gz-garden` can be installed. -**WARNING:** `gz-garden` cannot be installed alongside gazebo-classic (eg. `gazebo11`) since both use the `gz` command line tool. Trying to install `gz-garden` on a system that already has gazebo-classic installed from binaries will cause gazebo-classic and its dependencies to be uninstalled. Currently, the workarounds for this are to install from source or to use Docker [`gazebo-classic`](https://hub.docker.com/_/gazebo) so they are not installed side-by-side on the same system. +**WARNING:** for gazebo-classic (eg. `gazebo11`) users: `gz-garden` cannot be +installed alongside with `gazebo11` by default. To facilitate the migration +this can be done using the instruction detailed in +[Installing Gazebo11 side by side with new Gazebo](/docs/all/install_gz11_side_by_side). First install some necessary tools: diff --git a/harmonic/install_ubuntu.md b/harmonic/install_ubuntu.md index 72391d8b9..134282fb2 100644 --- a/harmonic/install_ubuntu.md +++ b/harmonic/install_ubuntu.md @@ -1,10 +1,13 @@ # Binary Installation on Ubuntu -Harmonic binaries are provided for Ubuntu Jammy (22.04) and Ubuntu 24.04 (when it's released). The +Harmonic binaries are provided for Ubuntu Jammy (22.04) and Ubuntu Noble (24.04). The Harmonic binaries are hosted in the packages.osrfoundation.org repository. To install all of them, the metapackage `gz-harmonic` can be installed. -**WARNING:** `gz-harmonic` cannot be installed alongside gazebo-classic (eg. `gazebo11`) since both use the `gz` command line tool. Trying to install `gz-harmonic` on a system that already has gazebo-classic installed from binaries will cause gazebo-classic and its dependencies to be uninstalled. Currently, the workarounds for this are to install from source or to use Docker [`gazebo-classic`](https://hub.docker.com/_/gazebo) so they are not installed side-by-side on the same system. +*WARNING:** for gazebo-classic (eg. `gazebo11`) users: `gz-harmonic` cannot be +installed alongside with `gazebo11` by default. To facilitate the migration +this can be done using the instruction detailed in +[Installing Gazebo11 side by side with new Gazebo](/docs/all/install_gz11_side_by_side). First install some necessary tools: diff --git a/install_gz11_side_by_side.md b/install_gz11_side_by_side.md new file mode 100644 index 000000000..d4cfdf496 --- /dev/null +++ b/install_gz11_side_by_side.md @@ -0,0 +1,71 @@ +# Installing Gazebo11 side by side with new Gazebo + +## Supported Gazebo versions and Ubuntu platforms for this tutorial + +This tutorial affects the Gazebo Classic users on Ubuntu `Jammy` (latest +Ubuntu release were Gazebo Classic packages supported by the Gazebo team) +that plan on migrating code to new Gazebo `Fortress`, `Garden` or `Harmonic.` + +There is no guarantee that the Gazebo Classic version detailed in this document +will be updated in any case. Please consider the migration to the new Gazebo +as the recommended alternative. + +## General context and migrations to new Gazebo + +New versions of Gazebo can not be installed together with Gazebo Classic +(aka `gazebo11`) since both use the `gz` command line tool. Trying to +install `gz-garden` or `gz-harmonic` from `packages.osrfoundation.org` +on a system that already has gazebo-classic installed from binaries +will cause gazebo-classic and its dependencies to be uninstalled. + +Having a side by side installation of both can make easier the recommended +migration to newer versions of Gazebo. + +## Alternative approach for Gazebo Classic without the gz tool + +A possible workaround could be to use Gazebo Classic without the `gz` +command or with a renamed `gz` command. This can be particularly +interesting since the ROS (Robot Operative System) wrapper known as +`gazebo_ros_pkgs` do not use the `gz` command but the `gzserver` and +`gzclient` commands. + +Not shipping the `gz` command by default in a Gazebo Classic installation +would be a disruptive change for existing users so it should not be hosted in +`packages.osrfoundation.org`. + +## Gazebo11 with a separate gz tool package + +This alterntive approach has been implemented and packages for `jammy` are +hosted in the Open Robotics `gazebo11-gz-cli` PPA: +https://launchpad.net/~openrobotics/+archive/ubuntu/gazebo11-gz-cli + +The PPA contains a `gazebo11` version that ships the `gz` executable in +an independent packages called `gazebo11-gz-cli` while the main `gazebo11` +package has a `gz11` command. Both are really symlinks to `gz-11.x.y`. + +### How the packaging works for the gz command + +The `gazebo11-gz-cli` is a soft dependency on `gazebo11`. It is installed +by default but it will be uninstalled when installing the new Gazebo +packages and the effect is that the `gz` command for Gazebo Classic replaced +by the `gz` tool from new Gazebo. The `gz11` command can be used instead of +the `gz` command to access to the same functionality. + +## Installing the new packaging from the PPA + +From an existing `gazebo11` installation (on `jammy` the Ubuntu official +repositories will install `11.10.2+dfsg-1` version) or a non existing +`gazebo11` installation the steps are the following: + +```bash +sudo add-apt-repository ppa:openrobotics/gazebo11-gz-cli +sudo apt update +sudo apt-get install gazebo11 +``` + +If `gazebo11` was installed before, it will be upgraded to the version in the +PPA. From this point, a new Gazebo installation for `fortress`, `garden` or +`harmonic` can be executed. + +If a new Gazebo installation was installed before, the `gazebo11-gz-cli` package +won't be installed.