py-rosws-stacks

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

Overview

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

Installation

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

Usage

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

Options:
  --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
                        branch
  -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
  --delete-changed-uris
                        (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.

ROS_WORKSPACE

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.

init

py-rosws-stacks init PATH

• Create a new workspace in directory PATH. If PATH doesn't exist, it will be created.

Example, to create a new, empty workspace:

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

add

py-rosws-stacks add STACK...

• Add one or more stacks to the workspace. By default, the add command: (i) pulls from the development branch for the current distro, and (ii) also pulls source for all released stacks that depend on the added stack(s). To pull from the released branch/tag, use the --released option. To not pull dependent stacks, use the -N option.

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

delete

py-rosws-stacks delete STACK...

• Remove one or more stacks from the workspace. By default, the remove command : (i) removes the stacks from the rosinstall configuration but does not delete any working copies, and (ii) also removes any stacks that depend on the removed stack(s). To delete working copies, use the -d option (BE CAREFUL!). To not remove dependent stacks, use the -N option.

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