rosinstall: source-based install tool

Usage

Usage: rosinstall <path> <paths...> [options]

Options:
  --version             show program's version number and exit
  -h, --help            show this help message and exit
  -c, --catkin          Declare this is a catkin build.
  --cmake-prefix-path=CATKINPP
                        Where to set the CMAKE_PREFIX_PATH, implies --catkin
  --version             display version information
  --verbose             display more information
  -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.
  --diff                shows a combined diff over all SCM entries
  --status              shows a combined status command over all SCM entries
  --status-untracked    shows a combined status command over all SCM entries,
                        also showing untracked files
  -j JOBS, --parallel=JOBS
                        How many parallel threads to use for installing
  --generate-versioned-rosinstall=GENERATE_VERSIONED
                        generate a versioned rosintall file

The first <path> is the filesystem path where the source code will be downloaded. Any additional <paths…> are treated as locations from which to fetch additional rosinstall file configuration. These can be filesystem paths or URLs. The behavior of rosinstall depends on what <paths…> points to:

  • If an additional path is a filesystem directory, rosinstall will look for a .rosinstall file in the directory, and then overlay the new environment on top of that directory’s configuration.

  • If an additional path points to a .rosinstall file, rosinstall will include the contents of that file.

For example:

rosinstall ~/ros "http://packages.ros.org/cgi-bin/gen_rosinstall.py?rosdistro=electric&variant=desktop-full&overlay=no"

After installation, rosinstall writes a bash setup file, called setup.bash, into <path>. Source this file to configure your environment variables.

rosinstall will also store the checkout information used in <path>/.rosinstall.

Updating a rosinstall checkout

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 or other VCS “update” equivalent. This will also regenerate the setup.bash environment file.

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

rosinstall .

Examples usages

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_pr2all.rosinstall

Developing a stack against a full tree:

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

Adding a rosinstall layout to an existing workspace

Create a new workspace directory and include /opt/ros/diamondback in the ROS_PACKAGE_PATH:

rosinstall ~/workspace /opt/ros/diamondback

Add wg_boxturtle_devel packages to the workspace:

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

Rosinstall Under the Hood

This is a summary of how rosinstall works under the hood.

Process Flow

Whenever rosinstall is executed the following code path is followed:

  1. Gather command line arguments

  2. Merge source rosinstall files

  3. Install source

  4. Generate a setup file.

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.

  1. 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

  1. Duplicates will be removed based on the key ‘local-name’. The later definition will be preserved.

  2. 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.bash

  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)

  1. The setup file will be written to disk.