Introduction

While the core ROS libraries can be installed into system directories via Debian packages or other system-based distribution mechanisms, a given ROS install base is usually distributed over disparate parts of the filesystem and then made available at runtime by inclusion in the ROS_PACKAGE_PATH environment variable.

By manipulating this environment variable, users can create their own packages, install additional packages from source, or even shadow installed packages with experimental versions.

There are a few ways to manage these "overlay" environments. A user can manage ROS_PACKAGE_PATH and ROS_WORKSPACE environment variables by hand, but this is cumbersome, can lead to confusion when switching environments, and errors in this variable can easily break a user's environment. Alternatively, rosws (ROS Workspace) provides a systematic method for managing package overlays in a user's workspace.

sudo apt-get install python-rosinstall

sudo pip install -U rosinstall

Overlays with rosws

rosws is a tool that provides a uniform interface to various version control systems such as SVN, Git and Mercurial and for managing all packages installed in a ROS overlay. An extensive tutorial on rosws can be found here.

Creating a new overlay

The following command creates a new overlay in ~/fuerte_workspace:

rosws init ~/fuerte_workspace /opt/ros/fuerte

This command creates the files setup.bash, setup.sh, setup.zsh and the hidden file .rosinstall in the directory ~/fuerte_workspace. To use this new overlay, it is enough to just call:

source ~/fuerte_workspace/setup.bash

• It is very common to replace the line source /opt/ros/fuerte/setup.bash to source the setup.bash in ~/fuerte_workspace.

The overlay now includes all packages that were installed in /opt/ros/fuerte.

Creating a sandbox directory for new packages

New packages need to be put in a path that is in the variable ROS_PACKAGE_PATH. All directories that are managed by rosws, i.e. that have been added using rosws are automatically added to the ROS_PACKAGE_PATH when the file setup.bash of the corresponding workspace is sourced. Although new packages should always be put in repositories that have been installed using rosws, it can be very convenient to have a sandbox directory where for instance packages created during the tutorials can be put without requiring any additional rosws commands. For that we create a new directory sandbox and add it to the .rosinstall file:

mkdir ~/fuerte_workspace/sandbox
rosws set ~/fuerte_workspace/sandbox

Now, it is necessary to re-source ~/fuerte_workspace/setup.bash to make sure that the updated ROS_PACKAGE_PATH is used.

Adding repositories to the overlay

Development normally happens in repositories and when installing packages from source, they normally need to be checked out from a repository and added to the ROS_PACKAGE_PATH. This can easily be done using rosws. For instance, the following commands add the development version of the stack turtlebot which is a Mercurial repository:

rosws set turtlebot --hg https://kforge.ros.org/turtlebot/turtlebot
rosws update turtlebot

After re-sourcing setup.bash the new overlayed stack turtlebot should be in your package path, i.e. roscd turtlebot should switch to the directory ~/fuerte_workspace/turtlebot.

If a stack is already installed in /opt/ros/fuerte, installing it using rosws will shadow the existing stack, i.e. instead of the system installation, the stack in ~/fuerte_workspace will be used. That way, it is possible to edit existing packages by cloning them in the overlay.

Adding stacks using roslocate

Very often, users need to install a stack from source that is known to the ROS wiki indexer. In that case, a stack can be found using roslocate. For instance, executing

roslocate info turtlebot

prints a rosinstall file that can be directly used by rosws. To add the stack turtlebot to the current overlay and check it out, the following command can be used:

roslocate info turtlebot | rosws merge -
rosws update

Updating repositories in an overlay

rosws allows to update only a single repository or all repositories:

rosws update turtlebot

updates only the stack turtlebot while

rosws update

updates all repositories.