You're reading the documentation for an older, but still supported, version of ROS 2. For information on the latest version, please have a look at Jazzy.

Using Custom Rosdistro Version

Overview

rosdistro contains the central index of ROS packages for all distributions and rosdep keys for packaged binary dependencies for installation. When you invoke rosdep install ..., it is checking a local cached index from rosdistro (populated during rosdep update) to correlate keys in a package.xml to the ROS package, python module, or binary to install. Thus, this index is an important element of the ROS ecosystem.

However, there are occasions where a user would like the assert further control over this index to add in their own proprietary keys or use a previous state of rosdistro. This guide walks through how to set a version of rosdistro to use on your system.

The motivating example that this guide will use is a desire to use a previous version of Rolling due to a breakage on your development computer or Continuous Integration. It is possible that during transition periods from one operating system to another, Rolling on the older operating system may become unusable due to support shifting to a new OS (i.e. moving to Ubuntu 22.04 to 24.04). Thus, we wish to set a prior version of rosdistro that aligns with a working Rolling distribution on a given operating system to keep our systems functioning before upgrading to the new operating system.

Important Preliminaries

Rosdep populates its cache from the locations set in its /etc/ros/rosdep/sources.list.d/20-default.list by default. When setting up rosdep with rosdep init, it populates 20-default.list with the main rosdistro URLs (from this file). The cache generated by rosdep update is located in ~/.ros/rosdep/sources.cache and should not be modified by hand.

When no ROSDISTRO_INDEX_URL environment variable value is set during a rosdep update, it uses the main public rosdistro index. However, when this value is set, you may use a custom rosdisto index which could be a snapshot from the public index or a completely separate index populated with your proprietary packages.

If you’d like to learn more about this, checkout the documentation in ros_buildfarm package.

How to Use a Custom Rosdistro Version

To use a custom version in your CI, docker build, local environment, robot, or other application, we need to first identify the rosdistro version of interest.

For our motivating example, we wish to use the last index state before the first sync of rolling on the new operating system. In this case, that last sync for our operating system was performed on February 28, 2024. Conveniently, the syncs are tagged so we can obtain that information on the rolling/2024-02-28 tagged branch.

Thus, we need to update the 20-default.list with our tagged branch values rather than using the main repository’s current state. This can be accomplished using the script as follows. If running on a local host, you may need to include sudo. This will update list to use our tagged branch rather than the master branch.

sed -i "s|ros\/rosdistro\/master|ros\/rosdistro\/rolling\/2024-02-28|" /etc/ros/rosdep/sources.list.d/20-default.list

After, we must now update the environment variable ROSDISTRO_INDEX_URL to point to our new rosdistro index.

export ROSDISTRO_INDEX_URL=https://raw.githubusercontent.com/ros/rosdistro/rolling/2024-02-28/index-v4.yaml

If you plan to use this on a local host for a long time, it may be wise to include this in your ~/.bashrc so that all new terminals do this automatically. The v4 in our index points to a new version of the index format. A previous index also exists without the v4 which is still present for historical reasons and legacy systems, but you should not use it.

Afterward, you can rosdep update, which will now use the changes to update the index in accordance to the Rolling distribution’s state on February 28, 2024 before the breakages began. You can see this in action in Nav2’s CircleCI and ros_gz’s GitHub Actions in order to bypass a temporary Rolling outage in their CI systems.

Note

If you are using a custom rosdistro version, you can substitute the final URLs in the default list and index URL with your fork or index location.