<<TableOfContents(3)>>

== 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 [[https://code.ros.org/svn/release/download/stacks/|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|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
}}}