rosinstall is a tool to check out ROS source code (or any source code, really) from multiple version control repositories and updating these checkouts. Given a *.rosinstall file that specifies where to get code, rosinstall will check out a working copy for you. We recommend the use of rosinstall when checking out development versions of ROS source code.

For instructions on using rosinstall, we recommend using the ROS Installation Guide

Getting rosinstall

Because it's used to install ROS software, rosinstall is a standalone program that you need to download. Get the latest version like so:

sudo apt-get install python-setuptools

sudo easy_install -U rosinstall

If you get an error not a recognized archive type: rosinstall: you have a file somewhere called 'rosinstall' in your current working directory. Delete this file and repeat the instructions above, or change to a different directory.

Usage

Usage: rosinstall PATH [URI] [options]

Options:
  --version             show program's version number and exit
  -h, --help            show this help message and exit
  -n, --nobuild         skip the build step for the ROS stack
  --rosdep-yes          Pass through --rosdep-yes to rosmake
  --delete-changed-uris
                        Delete the local copy of a directory before changing
                        uri.
  --abort-changed-uris  Abort if changed uri detected
  --backup-changed-uris=BACKUP_CHANGED
                        backup the local copy of a directory before changing
                        uri to this directory.
  --generate-versioned-rosinstall=GENERATE_VERSIONED
                        generate a versioned rosintall file

After installation, rosinstall writes a bash setup file, called setup.sh, into PATH. Source this file to configure your environment variables.

rosinstall can also save the state of the directory into a file .rosinstall.

Arguments

The first argument is the path into which rosinstall will install. Any other arguments after that are treated as locations from which to fetch rosinstall files. If the other arguments are a directory rosinstall will look for a .rosinstall file in the directory, and create an overlay of that directory. If it is a full path to a .rosinstall file then rosinstall will include the contents of that file.

Local changes protections

rosinstall will not delete any local changes.

• If the URL has not changed for source based checkouts it will call update on the specific VCS (version control system) library.
• If the URL has changed there are three options:
  • Abort: Do not update
  • Delete: Delete the directory
  • Backup=DIRECTORY: the working directory will be moved to DIRECTORY/STACKNAME_DATESTAMP and a fresh checkout performed.
  • By default the user will be prompted to choose what to do.

Common Use Cases

Developing on top of boxturtle shared install

rosinstall ~/workspace /opt/ros/boxturtle http://www.ros.org/rosinstalls/wg_boxturtle_devel.rosinstall

Full source checkout

rosinstall ~/workspace http://www.ros.org/rosinstalls/boxturtle_wg_all.rosinstall

Developing a stack against a full tree

rosinstall ~/workspace http://www.ros.org/rosinstalls/boxturtle_wg_all.rosinstall my_stack.rosinstall

Adding a rosinstall layout to an existing workspace

Create a directory with the contents of /opt/ros/boxturtle in the ROS_PACKAGE_PATH

rosinstall ~/workspace /opt/ros/boxturtle

Add wg_boxturtle_devel packages to the workspace.

rosinstall ~/workspace http://www.ros.org/rosinstalls/wg_boxturtle_devel.rosinstall

Updating a rosinstall tree

After using rosinstall to download and setup a certain directory tree. You can update the the contents of that tree using rosinstall as well.

rosinstall ~/workspace

will read the .rosinstall file in ~/ros and then call svn up on all the svn elements in the tree. (or the correct vcs used for each element). This will also regenerate the setup.sh.

If you are already in ~/workspace you can update by typing:

rosinstall .

Changing the version of a specific stack

You can manually edit the file ".rosinstall" in a rosinstall managed workspace and then call rosinstall ~/workspace and it will update the workspace to the new URL.

File format

rosinstall works from a YAML file that tells it what repositories to check out from. The format is:

- MODE:
    local-name: path/into/which/to/install
    MODE-SPECIFIC: DICTIONARY ...

Version Control Modes

There are 4 supported version control methods

• svn

• git (experimental)

• bzr (experimental)

• hg (experimental)

They each require two elements in the dictionary:

• uri: the location of the repository

• local-name: the name to give the local directory into which the code is checked out

For example to install ros from the boxturtle tag use:

• - svn:
      uri: https://code.ros.org/svn/ros/stacks/ros/tags/boxturtle
      local-name: ros

Other Mode

If you are not using version control, such as a shared install you can simply specify other and it will not attempt to update. other requires just the element:

• local-name: the path to add to ROS_PACKAGE_PATH

Example:

- other:
    local-name: /opt/ros/boxturtle/ros
- other:
    local-name: /opt/ros/boxturtle/stacks

Example rosinstall configuration file

This file checks out ros from the boxturtle tag, and uses the all svn:external in the wg-ros-pkg repository to get everything else.

- svn:
    uri: https://code.ros.org/svn/ros/stacks/ros/tags/boxturtle
    local-name: ros
- svn:
    uri: https://code.ros.org/svn/wg-ros-pkg/externals/distro/boxturtle/all/
    local-name: pkgs

What's happening under the hood

This is a quick explanation of what rosinstall does each time it is invoked.

Merging source rosinstall files

1. Rosinstall will start with the .rosinstall file in the install path.

   • If one doesn't exist it will create an empty one.
2. To this it will append the contents of all arguments in order left to right.

   • if the argument is a directory it will look for a DIRECTORY/.rosinstall and add all elements as other elements with local-name set to the full path.

   • if the argument is a url or a path to a file it will directly take the contents
3. Duplicates will be removed based on the key 'local-name'. The later definition will be preserved.

4. This .rosinstall file will be saved to disk.

Installing Source

1. rosinstall will iterate through the .rosinstall file for each definition of source.

2. If the source directory does not exist it will be created and checked out

3. if the source directory exists and is of the same uri it will be updated

4. If the source directory exists and the uri doesn't match the user will be prompted to abort, delete, or backup

Generating setup.sh

1. After a successful installation rosinstall will iterate through each of the elements in .rosinstall and add their local-name to the ROS_PACKAGE_PATH, unless the path is detected to be ros, in which case it will be set to ROS_ROOT.

   • This will error if a ROS directory is not detected. (The ros directory must be explicitly called out in the local-name)

2. The setup file will be written to disk.

Bootstrap

1. If not disabled, the core ros will be bootstrapped.

Please see the ROS Installation page for up-to-date instructions on using rosinstall with current configurations.