Command-line syntax

The name "rosinstall" does not fit into an SCM like tool as it contains a verb "install" in its name, which is confusing. The name rosws for rosworkspace is a suggestion based also on other activities around rosinstall. (see https://code.ros.org/lurker/message/20110711.160222.666ecfe4.en.html)

The command by default uses the context to determine which folder to use as target of the operations. Two location types are relevant, the workspace folder, and folders of entries.

The workspace folder must contain a .rosinstall file to be recognized as such. The rosws command will consider the first such folder in the chain of the current directory and its parents. The rosinstall command may also rely on the ROS_WORKSPACE environment variable to specify a workspace. If both approaches detect a suitable folder, the command will fail with an error message indicating the ambiguity. The user may specify a target workspace folder with the same option for all commands. This is the preferred approach for scripting with rosws.

To determine what entry a user wants to work on for certain commands, the concept of a localname is used in what follows. The localname is historically an absolute filepath or a relative path relative to the workspace folder. Commands which accept a localname argument will first attempt to resolve that argument against the list of known localnames. If that fails, the commands will fall back to choosing a workspace entry which has the same path in the filesystem, even if the localname does not match. As an example, rosws diff . In a tree with localname foo is equivalent to rosws diff foo. Finally, some commands may fall back to interpret such an argument, if it is the only one, and in the absence of a specifying option, as a workspace folder if the command also accepts a workspace folder.

$ rosws set robot_model --hg https://kforge.ros.org/robotmodel/robot_model
$ rosws set robot_model --version robot_model-1.7.1
$ rosws set robot_model --detached

$ rosws update -t ~/fuerte
$ rosws update robot_model geometry

$ rosws info -t ~/ros/fuerte
$ rosws info robot_model
$ rosws info --yaml
$ rosws info --only=path,cur_uri,cur_revision robot_model geometry

Use cases

The following are a list of use cases for rosinstall. U1-U6 are based on use cases described in the rosinstall documentation [1].

The new command syntax examples usually have several alternatives to use context or options to specify the workspace to operate on..

rosws ~/workspace /opt/ros/boxturtle
cd ~/workspace
rosws merge  http://www.ros.org/rosinstalls/wg_boxturtle_devel.rosinstall
rosws update

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

rosws ~/workspace http://www.ros.org/rosinstalls/boxturtle_pr2all.rosinstall
cd ~/workspace
rosws merge my_stack.rosinstall
rosws update

cd ~/workspace
rosws merge http://www.ros.org/rosinstalls/wg_boxturtle_devel.rosinstall
rosws update

cd ~/workspace
rosws update sometree

cd ~/workspace
rosws set stackname --version=newversion

cd ~/workspace
roslocate info common_msgs | rosws merge -

cd ~/workspace
rosws remove foo

cd ~/workspace
rosws info --yaml > GENERATE_VERSIONED

rosws init ~/workspace /path/to/other/workspace

cd ~/workspace
rosws update foostack
rosws regenerate

cd ~/workspace
rosws diff

cd ~/workspace
rosws status

Use-case analysis

All rosinstall use-cases deal with a user trying to maintain a ROS environment on a local machine. A ROS environment means the assignment of values to ROS_PACKAGE_PATH, PATH, PYTHONPATH and ROS_MASTER_URI, as well as further changes to support ROS toolchains.

Given the description, a user of rosinstall needs to be aware of the following artifacts:

• any .rosinstall file in the current directory
• the setup.* files in the current directory
• the state of local directories
• the information contained in other rosinstall files

As a user is free to manipulate entry in the configuration files, a major cause for errors are mistakes during such modifications. As an automated tool, rosinstall currently only knows of this: The user may have changed the rosinstall file, the user may have provided additional locations, now a new .rosinstall file may have to be merged with additional locations, and new setup.* files have to be generated.

An early attempt for this REP tried to provide different commands for different use-cases, such as init, remove, add and update. However the code for all those commands had in all cases to remain largely similar to cope with the situation where a user had manually changed his or her .rosinstall, or filesystem.

The list of use-cases thus only displays the range of distinctive usages of rosinstall, but does not provide help into splitting up the main functionality into many small commands.

T1: Table of use cases and commands

Names

The current rosinstall command structure allows a command such as:

rosinstall ~/workspace /opt/ros/diamondback ~/workspace2 ~/workspace/foo ~/download/temp.rosinstall

The intention of the user typing this cannot be inferred from the command, nor can what the tool will do be inferred from the syntax. The key idea is to have a syntax that allows the user to express a specific intention and to understand what the tool will do.

The commands info, diff, and status are self-explanatory.

The word install was dropped completely with the broad functionality it offers in rosinstall. install makes users shy away from usage fearing they might corrupt their debian installation with a tool.

The set and merge commands are somewhat ambiguous, as the user would need to use them for multiple purposes of adding entries or modifying versions of entries. However the different use-cases are algorithmically so similar that own commands for each seem superflous.

Rejected names include:

add, edit, modify, read, load, import, change

rosinstall0.5

As originally developed by Tully Foote.

Commands are:

rosinstall PATH [options] [URIs]

with a 4 Phase model, Merging, Checking out, Generating setup, bootstrapping ROS serving most use-cases and --generate-versioned-rosinstall being an exceptional command

Extended-options

Similar to the commands provided in the REP, some of the functionality could be provided by additional --options.

e.g.:

rosinstall --info
rosinstall --check
rosinstall --diff
rosinstall --status

This is less useful for bash completion and focused help.

SCM-like-explicit-path

As initially suggested for this REP, all commands require the path on which to work as the first argument.

Commands are:

rosinstall <command> PATH [options]
rosinstall <command> PATH [options] [URIs]

The SCM-like Designs are in line with the other ROS tools. However, SCM tools usually drop the PATH argument and work in the current directory tree.

SCM-like-implicit-path

Inferring the path from context can be done to varying degrees, like ignoring the ROS_WORKSPACE variable or only considering the current folder, not its ancestors as candidates.

Another alternative is to try first interpreting any first argument as a workspace folder, however this may conflict with the syntax of command set.

SCM-like-extended-command-set

The install command suggested provides support for several use cases which could be further split up into different commands, e.g. add and apply. See Rejects.

2nd draft rejects

In 2012 there was a second surge to realize the REP. In this it was decided to make a more significant step away from the rosinstall design. As a consequence, certain ideas were brought up and rejected:

• rosws install: replicates rosinstall

A command doing many things at once confuses and scares the occasional user Similarly commands set, merge nad update only do one thing, and do not allow doing more than one thing.

• update after set/merge

It could be convenient if the tool did or offered to checkout/update tree entries after a set/merge operation. This can be added as an option in the future if users want it.

• many uris for init and merge

These commands could technically take many uri arguments instead of maximally one. The decision to allow only one is to help users understand the syntax. The problem with many arguments we saw with rosinstall is that users could not read from the syntax whether the second argument had a special semantic or not, or whether the order of the arguments mattered.

• Maintain rosinstall assumptions about ROS

rosinstall was provided in support of early ROS releases, this REP is provided in the wake of ROS fuerte, which makes significant changes to how a ROS environment is set up. rosws can have a fresh start with fuerte only providing minimal support for ealier distros. In particular rosws will not insist on having a ROS stack, and will not build ros or ros_comm even after source checkouts, nor have an option to do so. A future development could be to even drop generation of the setup.* files.

• optional localname when adding using set

With SCM providers, it is possible to checkout a new local copy from a url without giving a target folder name. The same could be achieved with the rosws set syntax. However this makes the syntax more confusing, and in many cases we want the user to be aware of names because the repository names often have dashes where the localname should have underscores.

• rosws snapthos

The command is just a variant of rosws info and can be a --option

• making set and merge a single command

Both commands add/modify entries, so the case was made to unify them. It was rejected after lengthy discussions for these reasons: There is the fact that the 1st argument is mandatory for set, but not useful as localname for merge. There are the different -- options for the different cases. For the user, it should be clear whether his focus is some "remote" resource containing a set of many yaml entries, or on a single entry to add/change. That split is also the split of commands. The user won't be surprised by tab completion options --hg (or just hg as positional argument) or --version when merging with rosinstall files. They would make no sense, but code completion cannot know that. The localnames wont get in the way of tab completion user when wanting to point to a local xyz.rosinstall file. It is true that merge is semantically like n calls to set, except it is an atomic operation (all succeed, or all fail). In the far future, we might think of nested workspaces having state and version of their own and defining commit() and add()and update() actions. Then we could have a different type for the "set" command, BUT this would be very different semantics from the merge command, and the merge command would not become obsolete. This possibility should also indicate why merging the set and merge command above would hinder things in the future.

• making all entry arguments in set mandatory

The set semantics could be cleaner if it followed the principle that always a full entry (scmtype, uri, version) must be provided. This is however unnecessarily tedious when the user just wants to change one of the details of an existing entry

• splitting set into add and edit

The split has the advantage that more warnings can be provided in case the user tries to add an entry which overlaps another. However a confirmation step is sufficient. Also this would allow having mandatory positional parameters for scmtype and uri in the add case, and optional ones for the edit case, but two different syntax structures for very similar cases would be confusing as well.

• making the scmtype in set a positional argument

positional arguments like hg, git and svn do not work well with an optional third positional argument URI.

• detach as a command of its own

set has option --detached to remove all scm information. The case was made to make this a command of its own, in particular for a fuse set/merge command. But it fits better with the set - merge split.

• remove as a set option

removal is an instance of modifying, so it could be unified with set as a --option. However the end effect of a set operation is always that something exists afterwards, so these semantics get muddied by remove as an option.

• default merge option killAppend

When using merge or set, a decision is when an overlapping entry exist, whether to replace it in place, or whether to remove the existing and append the new one at the end. rosinstall has the latter semantic because it conveniently implies that it is possible to ensure an ordering of entries in the config file by ordering them in the argument list.

For novice users however this behavior is confusing and also hard to describe. The default semantics for merge is therefore to replace the entry in place. An option exists for merge to change that behavior.

1st draft rejects

The following attempts were rejected in the first REP draft in 2011

• rosws regenerate: Generates setup files but does not attempt to update SCM based entries
• rosws init: first time command demands a ROS root to be specified. too similar to install
• rosws update: merges new entries and runs update on all scm based entries. too similar to install
• rosws remove: removes an entry from .rosinstall. Better be done by hand

In the second draft, those command were resurrected in particular in the absence of an all encompassing rosws install command.

Those commands were too similar to rosws install and their behavior to bulk update and regenerate all trees conflicted with the semantics sugested by their name.

• rosws overlay: looks up repository location based on roslocate and rosinstalls it
• rosws change-ros: allows to move from e.g. /opt/ros/diamondback to ~/ros or /opt/ros/cturtle
• rosws mv: Moves local checked out stack to different location on filesystem
• rosws reorder: changes the order of stacks in ROS_PACKAGE_PATH
• rosws change-version: changes the desired version of an SCM based local stack
• rosws check --repair: Attempts to (interactively) fix inconsistencies such as duplicate paths

Those commands make the initial version of the REP more complex to discuss and harder to implement, therefore they were left out.