rosinstall is a tool to help with checking out ROS code (or any code, really) from multiple repositories. Given a file that specifies where to get code, rosinstall will checkout and update a working copy for you. We recommend the use of rosinstall when checking out development versions of ROS 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:

wget --no-check-certificate http://ros.org/rosinstall -O ~/rosinstall
chmod 755 ~/rosinstall

Usage

usage: rosinstall [OPTIONS] INSTALL_PATH [URI]

Options:
-u or --update (URI is optional only when using --update on an existing install)
-s SETUP_FILE or --setup=SETUP_FILE (use another setup.sh file to create env)
-o or --overlay (push current environment into setup.sh)
-n or --nobuild (don't perform a 'make core_tools' on the ros stack)

Common invocations:

initial checkout:   rosinstall ~/ros http://rosinstalls/boxturtle-base.rosinstall
subsequent update:  rosinstall -u ~/ros

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

File format

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

- VERSION-CONTROL-TYPE:
    uri: URI
    local-name: WORKING-COPY-NAME

• VERSION-CONTROL-TYPE : what kind of version control is used for this repository; supported types are:

  • svn

  • git

  • bzr

• uri: the location of the repository

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

NOTE: rosinstall will simplify the ROS_PACKAGE_PATH for checkouts that share a common local-name sub-directory. For example, if you put multiple checkouts in sub-directories of "stacks", it will set ROS_PACKAGE_PATH=stacks, instead of setting multiple paths per checkout.

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

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

Symbolic links

In constructing the setup.sh file, rosinstall will fully dereference the INSTALL_PATH that you give it, following all symbolic links. So, for example, if your home directory is /home/user, which is a symbolic link to /storage1/user, and you do this:

rosinstall /home/user/ros http://rosinstalls/boxturtle-base.rosinstall

then the setup.sh file will contain lines like these:

export ROS_ROOT=/storage1/user/ros/ros
export ROS_PACKAGE_PATH=/storage1/user/ros/stacks/common:...

i.e., the path to your installation was expanded. This doesn't usually present a problem, but it can be an issue if you expect the location of your installation to move. In that case, you should edit the setup.sh file to point to the symbolic link.

Reviews

/Reviews

/NewVersion