Change Dart from 6.12.x to 6.13.x in Debian packaging for Ubuntu Jammy

[j-rivero]

Current situation

The different package managers that use gz-physics to install the DART dependency have different versions available.

At the time of writting:

• 6.12 Ubuntu Jammy official repositories
• 6.13.0 Conda-forge
• 6.13.0 Brew

The developer team would prefer to get rid of the 6.12.x version and move the Debian packages to the 6.13.x for the Ubuntu Jammy distribution. This has several problems:

• 6.12.x is the official version of DART in Jammy. This implies that all packages released in that platform are expect to use it. This includes all previous versions of Gazebo (Garden and Fortress),
• DART does not maintain ABI/API betwen minors, just patch bumps.
• Different major.minor versions of DART packages are not co-installable, 6.12 can not be installed together with the 6.13 version since development files (headers, buildsystem helpers, library symlinks,...) are using the same paths on both version.
• Debian packages for different major.minor would need to declare a conflict between each other, making impossible to maintain software that depend in different versions installed at the same time.
• dart 6.13.x packages could be uploaded to packages.o.o but we won't be covering the case of ROS users that consume ROS repositories + Ubuntu official packages.

Source code using DART

After checking links (ldd $lib) and binary symbols (nm -D $lib) in the gazebo libs, I'm think that the gz-physics source code that users DART is limited to the generation of the gz-physics dart plugin. The plugin is not linked against any other lib or being used in other compilation unit.

ldd /usr/lib/x86_64-linux-gnu/gz-physics-7/engine-plugins/libgz-physics7-dartsim-plugin.so.7.0.0~pre2 | grep dart
	libdart-collision-bullet.so.6.12 => /lib/x86_64-linux-gnu/libdart-collision-bullet.so.6.12 (0x00007f30d2b58000)
	libdart-collision-ode.so.6.12 => /lib/x86_64-linux-gnu/libdart-collision-ode.so.6.12 (0x00007f30d2b20000)
	libdart.so.6.12 => /lib/x86_64-linux-gnu/libdart.so.6.12 (0x00007f30d25de000)
	libdart-external-odelcpsolver.so.6.12 => /lib/x86_64-linux-gnu/libdart-external-odelcpsolver.so.6.12 (0x00007f30d132c000)

gz-physics dart packages

libgz-physics7-dartsim-dev: mainly CMake/pkg-config stuff and symlinks of the plugins (the .so files are no more than symlinks). The real file interesting here is /usr/include/gz/physics7/gz/physics/dartsim/World.hh

# dpkg -L libgz-physics7-dartsim-dev
/usr/include/gz/physics7/gz/physics/dartsim/World.hh
/usr/include/gz/physics7/gz/physics/dartsim-plugin
/usr/include/gz/physics7/gz/physics/dartsim-plugin/Export.hh
/usr/include/gz/physics7/gz/physics/dartsim-plugin/detail
/usr/include/gz/physics7/gz/physics/dartsim-plugin/detail/Export.hh

/usr/lib/x86_64-linux-gnu/cmake/gz-physics7-dartsim
/usr/lib/x86_64-linux-gnu/cmake/gz-physics7-dartsim/gz-physics7-dartsim-config-version.cmake
/usr/lib/x86_64-linux-gnu/cmake/gz-physics7-dartsim/gz-physics7-dartsim-config.cmake
/usr/lib/x86_64-linux-gnu/cmake/gz-physics7-dartsim/gz-physics7-dartsim-targets.cmake
/usr/lib/x86_64-linux-gnu/cmake/gz-physics7-dartsim-plugin
/usr/lib/x86_64-linux-gnu/cmake/gz-physics7-dartsim-plugin/gz-physics7-dartsim-plugin-config-version.cmake
/usr/lib/x86_64-linux-gnu/cmake/gz-physics7-dartsim-plugin/gz-physics7-dartsim-plugin-config.cmake
/usr/lib/x86_64-linux-gnu/cmake/gz-physics7-dartsim-plugin/gz-physics7-dartsim-plugin-targets-relwithdebinfo.cmake
/usr/lib/x86_64-linux-gnu/cmake/gz-physics7-dartsim-plugin/gz-physics7-dartsim-plugin-targets.cmake

/usr/lib/x86_64-linux-gnu/pkgconfig
/usr/lib/x86_64-linux-gnu/pkgconfig/gz-physics7-dartsim-plugin.pc
/usr/lib/x86_64-linux-gnu/pkgconfig/gz-physics7-dartsim.pc

/usr/lib/x86_64-linux-gnu/gz-physics-7/engine-plugins/libgz-physics-dartsim-plugin.so
(/usr/lib/x86_64-linux-gnu/gz-physics-7/engine-plugins/libgz-physics-dartsim-plugin.so -> libgz-physics7-dartsim-plugin.so)
/usr/lib/x86_64-linux-gnu/gz-physics-7/engine-plugins/libgz-physics7-dartsim-plugin.so
( /usr/lib/x86_64-linux-gnu/gz-physics-7/engine-plugins/libgz-physics7-dartsim-plugin.so -> libgz-physics7-dartsim-plugin.so.7)
/usr/lib/x86_64-linux-gnu/libgz-physics7-dartsim-plugin.so
( /usr/lib/x86_64-linux-gnu/libgz-physics7-dartsim-plugin.so -> libgz-physics7-dartsim-plugin.so.7)
...

libgz-physics7-dartsim: real binary plugins and two symblinks

# dpkg -L libgz-physics7-dartsim    
/usr/lib/x86_64-linux-gnu/libgz-physics7-dartsim-plugin.so.7.0.0~pre2
/usr/lib/x86_64-linux-gnu/gz-physics-7/engine-plugins/libgz-physics7-dartsim-plugin.so.7.0.0~pre2
/usr/lib/x86_64-linux-gnu/gz-physics-7/engine-plugins/libgz-physics7-dartsim-plugin.so.7
(/usr/lib/x86_64-linux-gnu/gz-physics-7/engine-plugins/libgz-physics7-dartsim-plugin.so.7 -> libgz-physics7-dartsim-plugin.so.7.0.0~pre2)
/usr/lib/x86_64-linux-gnu/libgz-physics7-dartsim-plugin.so.7
(/usr/lib/x86_64-linux-gnu/libgz-physics7-dartsim-plugin.so.7 -> libgz-physics7-dartsim-plugin.so.7.0.0~pre2)
...

[azeey]

There was a discussion in #274 about gz/physics/dartsim/World.hh. Grey mentioned that it was originally made a public header intentionally to expose the internal API of DART to gz-physics users. @j-rivero what options would become available if we decide to make this header private/used for testing only?

[j-rivero]

A possible workaround:

We really don’t want to make 6.13 and 6.12 to conflict. Period.
With this in mind, let’s consider the main use cases when using dart:

Use case A) Using the dartsim plugin (load it when launching Gazebo): we would need to get the DART 6.13 code (binary code) without touching the 6.12 files/packages.

How to get 6.13 binaries without conflicting with 6.12:

• Option 1: given that the packaging in Ubuntu provides individual packages for each of the DART libraries shipping just the library with the major.minor in filepath (i.e: https://packages.ubuntu.com/jammy/amd64/libdart-collision-bullet6.12/filelist), we can potentially inject 6.13 lib packages for getting the 6.13 binary support needed by libgz-physics7-dartsim-plugin without conflicting with 6.12 packages.
  • a) For packaging the dart libs we could upload the 4 dart 6.13 libs packages needed to packages.o.o (and possibly packages.ros.o) and make the gz dartsim plugin package to depend on them.
  • b) Another alternative for packaging would be to directly ship them inside the libgz-physics-dartsim-plugin package or a new libgz-physics-dartsim-external-dart6.13 package to create.
• Option 2: a more risky approach would be to change the linking to use static linking for gz-dartsim-plugin to avoid linking to dart 6.13. Not sure about possible side effects on the different platforms and the dloader call though.

Use case B) For developing on top of the dartsim plugin: I’m going to consider this use case “infrequent” since it is not usual to use a plugin to build things on top. If we are going to compile the gz-dartsim-plugin with dart 6.13 we would need 6.13 development files, otherwise problems with the ABI will arise.

For going forward, the question to answer is: how to keep 6.12 dart-dev packages in a system while having the gz-dartsim-plugin compiled with 6.13? A possible answer is: we can maintain the divergence of having gz-dartsim-plugin with 6.13 and dart-dev 6.12 as far as we block the user from building (compiling/developing) things on top of this mix.

For that we could use the build system (adding some CMake code to gz-physics7-dartsim-plugin-config.cmake) to stop the user from building on top of the plugin. We would consider this case not supported: if anyone wants to develop on top of the gz-physics7-dartsim-plugin she/he should uninstall dart-6.12 packages and install dart-6.13 and build from source. For allowing the divergence in the package manager, the gz-physics7 packages can declare a dependency on any of the both versions: Depends: libdart-dev (>=6.12) | libdart-dev (<< 6.14).

Summarizing of changes needed:

• Creating the new 6.13 version of Debian dart officially (note that the DARTSim PPA is not using the right major.minor notation in the package names but only majors) and releasing .debs for Jammy.
• Change the build process to use 6.13 in gz-physics7.
• Look how to package the relevant DART libraries into a gz-physics existing package or new package:
  • libdart-collision-bullet6.13, libdart-collision-ode6.13, libdart-external-odelcpsolver6.13, libdart6.13
• Change libgz-phsyics7-dartsim dependencies:
  • Depends: new package/s in the point above
• Change libgz-physics7-dartsim-dev dependency:
  • Depends: libdart-dev (>=6.12) | libdart-dev (<< 6.14).

[mjcarroll]

For case A, I like the option 1.b approach, directly shipping them inside the dartsim plugin themselves.

Option 2 is also doable, the static linking should be okay (and this is actually how bazel rules do it), but I agree, still more unknowns.

For going forward, the question to answer is: how to keep 6.12 dart-dev packages in a system while having the gz-dartsim-plugin compiled with 6.13? A possible answer is: we can maintain the divergence of having gz-dartsim-plugin with 6.13 and dart-dev 6.12 as far as we block the user from building (compiling/developing) things on top of this mix.

Another alternative is to use DART from the colcon workspace. I find this works pretty well in that it overlays the system install of DART and already gets picked up by gz-cmake and gz-sim, and doesn't require uninstalling the system version. It's also nice for testing changes in both DART and gz-physics simultaneously, in my experience.

Edit: Thanks for summarizing all of this, a lot of moving pieces.

[j-rivero]

For case A, I like the option 1.b approach, directly shipping them inside the dartsim plugin themselves.

1.b of including dart libs inside the libgz-dartsim-plugin is great for not adding new packages to the mix but could be not very flexible if at some point we have the same dart libraries provided by other packages, for example: someone installs the dartsim PPA and dart6.13 from there, in this case there would be a conflict with our libgz-dartsim-plugin that we could manage by adding some .deb metadata (alternative depends + conflicts) if we go with 1.a of having the dart libs in a different package/s.

Another alternative is to use DART from the colcon workspace. I find this works pretty well in that it overlays the system install of DART and already gets picked up by gz-cmake and gz-sim, and doesn't require uninstalling the system version. It's also nice for testing changes in both DART and gz-physics simultaneously, in my experience.

That is a great use of the overlaying provided by colcon. Not easy to understand for non advanced users but a powerful setup for experts.

[j-rivero]

There was a discussion in #274 about gz/physics/dartsim/World.hh. Grey mentioned that it was originally made a public header intentionally to expose the internal API of DART to gz-physics users. @j-rivero what options would become available if we decide to make this header private/used for testing only?

Removed in #551 . That opens the question: is there a valid use for developers that would generate code from the dartsim plugin that has no public headers? Because we are generating the buildsystem helpers (CMake + pkgconfig) to facilitate that use case. If there is no use case, we either don't package the helpers and remove the gz-phsyics-dartsim-dev package and/or change our buildsystem not to generate the helpers. If there is a valid use case, we can maintain it with just the helpers.

[azeey]

Continuing from #551 (comment)

is there a valid use for developers that would generate code from the dartsim plugin that has no public headers?

Without any public headers, I don't see a way downstream users can build on top of this. And I don't think that's really a use case we have in mind for the gz-physics plugins anyway. @scpeters ?

[j-rivero]

In the Gazebo weekly meeting we decide to support the Option 1) version 1.a that builds gz-physics7 on top of DART 6.13 and package the DART 6.13 libraries separated:

Summarizing of changes needed:

• Creating the new 6.13 version of Debian dart officially (note that the DARTSim PPA is not using the right major.minor notation in the package names but only majors) and releasing .debs for Jammy.

• Debian metadata (gbp like repo): https://github.com/j-rivero/dart-debian
• PPA; https://launchpad.net/~openrobotics/+archive/ubuntu/dart6.13-gazebo

• Change the build process to use 6.13 in gz-physics7.

• Use libdart6.13 custom packages from packages.o.o gazebo-release/gz-physics7-release#3
• Use libdart6.13 packages in CI from packages.o.o #553

• Look how to package the relevant DART libraries into a gz-physics existing package or new package:
  libdart-collision-bullet6.13, libdart-collision-ode6.13, libdart-external-odelcpsolver6.13, libdart6.13
  Special package that hosts all the libraries used by Gazebo: libdart-core+collisions+odelcpsolver6.13

• Change libgz-phsyics7-dartsim dependencies:

• Use libdart6.13 custom packages from packages.o.o gazebo-release/gz-physics7-release#3

• Depends: new package/s in the point above
• Change libgz-physics7-dartsim-dev dependency:
  • Depends: libdart-dev (>=6.12) | libdart-dev (<< 6.14).

• Use libdart6.13 custom packages from packages.o.o gazebo-release/gz-physics7-release#3

[scpeters]

Continuing from #551 (comment)

is there a valid use for developers that would generate code from the dartsim plugin that has no public headers?

Without any public headers, I don't see a way downstream users can build on top of this. And I don't think that's really a use case we have in mind for the gz-physics plugins anyway. @scpeters ?

I think there is a use case for 3rd parties to supply header files with the API definitions of custom features, though they shouldn't use engine-specific types like we had in the dartsim World.hh file. We haven't yet finished the user story for custom features, but that's the one thing that comes to mind