Description

The rosinstall_generator generates rosinstall files containing information about repositories with ROS packages/stacks.

• Source: git https://github.com/ros-infrastructure/rosinstall_generator

• Bug / feature tracker: https://github.com/ros-infrastructure/rosinstall_generator/issues

It always returns information about released packages - either to the gbp repositories for wet packages or to the tarball of dry stacks from the SVN release repository.

If you want to access the source repository of a package/stack you should use roslocate instead.

Installation

The rosinstall_generator can be installed via a Debian package from the ROS repositories:

sudo apt-get update
sudo apt-get install python-rosinstall-generator

For other platforms (where the Debian package is not available) it can be installed from PyPI using pip. It is strongly suggested that you use a virtual environment to contain these dependencies. For more info, see: https://docs.python.org/3.6/tutorial/venv.html

python3 -m venv /path/to/my_venv
source /path/to/my_venv/bin/activate
pip install rosinstall-generator

Usage

The command line program is invoked by:

rosinstall_generator PKGNAME [PKGNAME ...]

You can pass package names, dry stack names as well as variants (below just called packages). Variants are being resolved into a set of packages and/or stacks.

By default it outputs the repository information formatted for rosinstall to the console. Commonly you want to pipe the result into a .rosinstall file.

Via command line options you can customize for which packages the rosinstall information is provided:

• --deps

  • Include all repositories for the recursive dependencies.

• --deps-up-to PKGNAME [PKGNAME ...]

  • Include repositories between the passed package and the up-to packages (see below for an example).

• --deps-only

  • Exclude the packages passed in on the command line returning only the dependencies.

Furthermore you can restrict the result set:

• --exclude PKGNAME [PKGNAME ...]

  • Exclude specific packages (also excluding their dependencies when using --deps* options).

• --wet-only

  • Only include wet packages.

• --dry-only

  • Only include dry stacks.

Anywhere where it is possible to specify package names you can also use the following keywords which will expand to a specific set of packages:

• ALL

  • Expands to the set of all released packages.

• RPP

  • Expands to the set of packages found in then current environment (by searching the ROS_PACKAGE_PATH).

If you don't have a ROS environment sourced (ROS_DISTRO not being set) you also have to specify the ROS distribution with the option --rosdistro DISTRO_NAME.

After generating a rosinstall file using this tool you can checkout all the packages using rosinstall and build the whole workspace with catkin_make_isolated.

Example

All packages to build a variant from released sources

To generate a rosinstall file with all packages and stacks contained in the desktop-full variant for Hydro invoke:

$ rosinstall_generator desktop_full --rosdistro hydro --deps > hydro-desktop-full.rosinstall

Since for Groovy not all packages of desktop_full have been catkinized you might want to generate two separate rosinstall files for wet and dry. Thereby you can checkout these two sets of packages into different locations:

$ rosinstall_generator desktop_full --rosdistro groovy --deps --wet-only > groovy-desktop-full-wet.rosinstall
$ rosinstall_generator desktop_full --rosdistro groovy --deps --dry-only > groovy-desktop-full-dry.rosinstall

All packages currently in the environment from released sources

To generate a rosinstall file with all packages and stacks available via the ROS_PACKAGE_PATH invoke:

$ rosinstall_generator RPP

A set of packages missing from the current environment

To generate a rosinstall file with a set of packages including their dependencies which are not available in the current environment invoke:

$ rosinstall_generator rviz --deps --exclude RPP

All packages of a ROS distribution from released sources

To generate a rosinstall file with all packages and stacks available in a specific ROS distribution invoke:

$ rosinstall_generator ALL --rosdistro hydro

Note: it is very likely that some of these packages will not build successfully.

Combining with vcstool / wstool / rosws

To add a package/stack with all its dependencies to an existing workspace invoke:

# assuming the workspace is in the relative folder "src"
$ rosinstall_generator ros_tutorials --rosdistro noetic --deps | vcs import src

To add a package/stack with all its dependencies to an existing workspace managed by wstool (for wet) or rosws (for dry) invoke:

# assuming the wet workspace is in the relative folder "src"
$ rosinstall_generator ros_tutorials --rosdistro hydro --deps | wstool merge -t src -
$ wstool update -t src -j8

# assuming the dry workspace is in the current folder
$ rosinstall_generator navigation --rosdistro groovy --deps | rosws merge -
$ rosws update -j8