=== 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 [[release|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`, [[rosinstall#Installation|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.
 1. 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
}}}