[Documentation] [TitleIndex] [WordIndex


UPDATE: The tool described here and below is now named py-rosws-stacks since rosinstall 0.6.0.


EXPERIMENTAL: py-rosws-stacks is a new tool; its syntax and behavior is subject to change.

New in rosinstall 0.5.17

py-rosws-stacks is a tool to help manage ROS workspaces (aka "overlays"). py-rosws-stacks is basically a front-end for rosinstall that makes use of roslocate to simplify common tasks. In particular, py-rosws-stacks helps you to pull in source for stacks that you want to develop on.

py-rosws-stacks can only operate on stacks that have been released. It locates source for stacks via the .rosdistro files that are updated during the release process. py-rosws-stacks always pulls from a distro-appropriate location (it infers your ROS distro via rosversion ros).

Example workflow

If I want to do some development on the navigation stack, in preparation for a new release into diamondback:

# Start with my system install
source /opt/ros/diamondback/setup.bash
# Create a workspace
py-rosws-stacks init diamondback-navigation
# Load the workspace's configuration
source diamondback-navigation/setup.bash
# Add the diamondback development version of navigation to the workspace
py-rosws-stacks add navigation
# Load the workspace's configuration (it was changed by adding navigation)
source diamondback-navigation/setup.bash
# Now I'm set up to work on navigation
roscd navigation
<work, work, work>
# When I'm done, and everything is checked in, I can remove navigation from the workspace:
py-rosws-stacks delete navigation


py-rosws-stacks is installed with the rosinstall tool. To get py-rosws-stacks, install rosinstall.


Usage: py-rosws-stacks {init PATH | {add | delete} STACK...}

  --version             show program's version number and exit
  -h, --help            show this help message and exit
  -p PATH, --path=PATH  path to workspace; overrides ROS_WORKSPACE
  -c, --configure       change configuration, but don't run rosinstall
  -N, --non-recursive   don't change configuration for dependent stacks
  --released            Pull stack from release tag instead of development
  -d, --delete-working-copies
                        when deleting a stack from the configuration, also
                        delete the working copy (DANGEROUS!)
The following options are passed through to rosinstall; see rosinstall's documentation for details on their effect:
  -n, --nobuild         (rosinstall) skip the build step for the ROS stack
  --rosdep-yes          (rosinstall) Pass through --rosdep-yes to rosmake
  --continue-on-error   (rosinstall) Continue despite checkout errors
                        (rosinstall) Delete the local copy of a directory
                        before changing uri.
  --abort-changed-uris  (rosinstall) Abort if changed uri detected

In all modes, py-rosws-stacks works in two steps:

  1. Modify / create a rosinstall configuration.

  2. Execute rosinstall using the new configuration. py-rosws-stacks accepts all options that rosinstall accepts and will pass them straight through.

You can skip the second step by supplying -c to py-rosws-stacks.


If the environment variable ROS_WORKSPACE is defined, py-rosws-stacks add and py-rosws-stacks delete will operate on the directory it points to. The intent is for ROS_WORKSPACE to be set by sourcing a shell setup file generated by rosinstall. So, in the common case, you don't need to worry about ROS_WORKSPACE. To override the workspace directory, give -p PATH to py-rosws-stacks.


py-rosws-stacks init PATH

Example, to create a new, empty workspace:

source /opt/ros/diamondback/setup.sh
py-rosws-stacks init /tmp/work
source /tmp/work/setup.bash


py-rosws-stacks add STACK...

Example, to add navigation, pr2_simulator, and all the released stacks that depend on them, to the workspace:

py-rosws-stacks add navigation pr2_simulator
source /tmp/work/setup.bash


py-rosws-stacks delete STACK...

Example, to remove navigation, pr2_simulator, and all the released stacks that depend on them, from the workspace:

py-rosws-stacks delete navigation pr2_simulator
source /tmp/work/setup.bash

2019-05-25 13:16