Hi all,
the new rosinstall 0.6 series also has an implementation of REP110
(
http://www.ros.org/reps/rep-0110.html).
I attach to this announcement an updated version of REP110 (Ken, please
update).
I am not sure what next step will be required to close the REP as final,
if the next step in the formal process is a review, then I hereby declare
the REP to be ready for review.
Summary:
REP110 suggests a new command-line tool called rosws that does what
rosinstall does, with a more SCM like syntax. This should on the one hand
benefit novice users who feel uncertain about rosinstall, but can also
benefit expert users who felt that rosinstall does too much with a single
command.
rosws uses the same functions and back-end as rosinstall, it is just a
different ui to the same tool. Therefore there are no incompatibilities
between both tools. However it is an ongoing attempt to make rosinstall
more independent of ROS, and rosws will allow to create workspaces that do
not have a ROS root. The rosinstall command remains unchanged except for
the addition of an option to run SCM actions in parallel.
Users will get the rosws script if they update rosinstall using pip
$ sudo pip install -U rosinstall
There is also tab completion for bash that went into a python package of
its own (this one does not install with easy_install):
$ sudo pip install -U rosinstall_shellcompletion
Documentation and a tutorial for rosws are here:
http://www.ros.org/doc/api/rosinstall/html/
So if you got curious go ahead and try it out.
Also I made some design decisions on usability (with much help from Tully
and Ken), but I can well have misjudged, and I am happy to modify details
based on user feedback.
regards,
ThibaultREP: 110
Title: SCM-like rosinstall command structure
Version: $Revision: 120 $
Last-Modified: $Date: 2011-08-10 21:01:25 -0700 (Wed, 10 Aug 2011) $
Author: Thibault Kruse <
kruset@in.tum.de>
Status: Draft
Type: Informational
Content-Type: text/x-rst
Created: 11-Jun-2011
Post-History: 11-Jun-2011, 10-Aug-2011
Table of Contents
=================
#. Abstract_
#. Specification_
#. Use-cases_
#. Analysis_
#. Rationale_
#. Motivation_
#. Compatibility_
#. Design-Alternatives_
#. Reference-implementation_
#. References_
#. Copyright_
.. _Abstract:
Abstract
========
This REP presents an alternative to the rosinstall [1]_ command-line
interface to a command-based syntax. The command-based syntax is
inspired by SCM tools like ``svn``, ``git``, and ``hg`` as well as
several other ros commands like rosnode or rosservice, and is intended
to improve the usability of rosinstall as well as expose more
functionality. Common use cases of rosinstall are described and
compared with the proposed changes.
.. _Specification:
Specification
=============
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.
.. _init:
rosws init [PATH [URI]]
~~~~~~~~~~~~~~~~~~~~~~~
The command creates an initial environment for the other commands to
work. This is analogous to scm syntax. Its main purpose is to explain
the tool to the user, who understands that the location used here is
going to be a special location further on.
The command also generates three initial files, setup.sh, setup.bash and
setup.zsh, which when sourced set up environment variables according to
the .rosinstall file in the same folder. Those files wll only be overwritten
by the ``rosws regenerate`` command.
--catkin
--cmake-prefix-path
Options retain semantics as in rosinstall
.. _merge:
rosws merge [URI]
~~~~~~~~~~~~~~~~~
This command processes several entries from a given URI source
The command merges new entries (command line or changed in
``.rosinstall``) with existing entries (if a ``.rosinstall`` is
present). The strategy is to replace existing entries rather than
adding whenever possible. This is the case when an existing and a new
entry have the same target path, the same SCM type, and a similar SCM
configuration (e.g. same URI root).
The strategy fails whenever there are two entries with the same target
path but replacing is impossible with the strategy above.
When successfull, the command will append the new entries to the end
of the ``.rosinstall`` file.
URI can be a path to a rosinstall file, to a local directory
containing a ``.rosinstall``.
The command will fail when there are entries with duplicate target paths.
The command calculates the change to the configuration. If the change
merely consists of adding entries, this is executed. Else, the user is
presented with an overview of planned changes, roughly similar to what
the linux aptitude tool may present. The user can then interrupt the
operation. An option exists to not ask for confirmation.
Options:
The merge options apply whenever two elements have equivalent localnames
(pointing to the same directory)
--merge-keep Existing entries will remain unchanged
--merge-replace Existing entries will be overwritten in place
--merge-kill-append Exiting entries will be removed, new ones appended to the end
--confirm-all Do not ask for confirmation
``-`` a single dash can be used for piping stdout into the merge command
.. _set:
rosws set [LOCALNAME] [URI]?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The command serves to add or modify a single entry of the config and
is in particular aimed at users entering the entry information
themselves rather than relying on some other source of information.
For adding an entry, the common case is to add an SCM entry. The
syntax would then be
rosws set localname uri --scmtype --version=version
Options:
--svn Subversion SCM
--hg Mercurial SCM
--git git SCM
--bzr bazaar SCM
--tar tar as source (unofficial experimental feature)
--detached no SCM
--version-new the version specification to use
``-`` single dash means read from stdin (similar to tar command)
Option ``-version`` would go against the GNU standard of a global --version
option giving the version of a command line tool.
Examples::
``$ 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``
.. _update:
rosws update [LOCALNAME]*
~~~~~~~~~~~~~~~~~~~~~~~~~
The command checks out or updates the given subtrees or all subtrees
from their respective SCM provider and URL.
--continue-on-error Continue despite checkout errors
--delete-changed-uris
Delete the local copy of a directory before changing
uri.
--abort-changed-uris Abort if changed uri detected
--backup-changed-uris=BACKUP_CHANGED
backup the local copy of a directory before changing
uri to this directory.
Options retain their semantics from current rosinstall.
Examples::
``$ rosws update -t ~/fuerte``
``$ rosws update robot_model geometry``
.. _info:
rosws info [LOCALNAME]*
~~~~~~~~~~~~~~~~~~~~~~~
This serves to explain the current environment to the novice user, and
provide an overview of it. It is supposed to give an overview of the
environment and its state. The reference implementation lists the
interpreted ``ROS_ROOT`` and the ordered paths in the
``ROS_PACKAGE_PATH``. It also provides status information about the
local directories, such as whether they exist and whether their
current version matches the ``.rosinstall``.
Options:
--data-only just the data, no headers or text
--no-pkg-path does not print ROS_PACKAGE_PATH
--pkg-path-only Shows only ROS_PACKAGE_PATH separated by ``:``. Supercedes all other options.
--only Shows only given comma-separated attribute(s) separated by ``,``
--yaml prints rosinstall format yaml for backing up the current config
These options are mainly intended to allow scripting based on
rosinstall.
Examples::
``$ rosws info -t ~/ros/fuerte``
``$ rosws info robot_model``
``$ rosws info --yaml``
``$ rosws info --only=path,cur_uri,cur_revision robot_model geometry``
.. _remove:
rosws remove [LOCALNAME]+
~~~~~~~~~~~~~~~~~~~~~~~~~
removes entries with given localnames from the .rosinstall file
.. _status:
rosws status [LOCALNAME]*
~~~~~~~~~~~~~~~~~~~~~~~~~
This command batch-calls SCM status. The output is the concatenation
status commands for all versioned entries.
Options:
--untracked also shows untracked files
.. _diff:
rosws diff [LOCALNAME]*
~~~~~~~~~~~~~~~~~~~~~~~
This command batch-calls SCM diffs. The output is the concatenation of
diff commands for all versioned entries.
Such a feature was suggested on ros-developers. The reference implementation
shows how this could be done. However the solution is neither very
robust nor flexible for SCM diff options.
There is room for ambiguity when the version specified in the ``.rosinstall`` does not match
the version in the directory.
A warning should be given on stderr at least.
.. _regenerate:
rosws regenerate
~~~~~~~~~~~~~~~~
This command regenerates the setup.sh, setup.bash and setup.zsh files
that setup a shell environment. The rosinstall command overwrites these
files on each invocation for historical reasons.
There is as of today no need to regenerate these files even if the
.rosinstall file changed in acceptable use-cases. The only cases
where the files would be changed is when configuring a workspace
against a changed ROS distribution, or after an update of the rosws
tool.
Options
--catkin
--cmake-prefix-path
Options retain semantics as in rosinstall
Analysis
========
.. _Use-cases:
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..
.. _U1:
U1: Create a new environment based on an existing ros installation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
E.g. Developing on top of boxturtle shared install
``rosinstall ~/workspace /opt/ros/boxturtle
http://www.ros.org/rosinstalls/wg_boxturtle_devel.rosinstall``
New command example::
``rosws ~/workspace /opt/ros/boxturtle``
``cd ~/workspace``
``rosws merge
http://www.ros.org/rosinstalls/wg_boxturtle_devel.rosinstall``
``rosws update``
.. _U2:
U2: Create a new environment based on a rosinstall file only
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
E.g. Full source checkout
``rosinstall ~/workspace
http://www.ros.org/rosinstalls/boxturtle_pr2all.rosinstall``
New command example::
``rosws ~/workspace
http://www.ros.org/rosinstalls/boxturtle_pr2all.rosinstall``
.. _U3:
U3: Create a new environment with an additional stack
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
E.g. Developing a stack against a full tree
``rosinstall ~/workspace
http://www.ros.org/rosinstalls/boxturtle_pr2all.rosinstall my_stack.rosinstall``
New command example::
``rosws ~/workspace
http://www.ros.org/rosinstalls/boxturtle_pr2all.rosinstall``
``cd ~/workspace``
``rosws merge my_stack.rosinstall``
``rosws update``
.. _U4:
U4: Adding more entries to an existing workspace
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
E.g. Adding a rosinstall layout to an existing workspace
``rosinstall ~/workspace
http://www.ros.org/rosinstalls/wg_boxturtle_devel.rosinstall``
New command example::
``cd ~/workspace``
``rosws merge
http://www.ros.org/rosinstalls/wg_boxturtle_devel.rosinstall``
``rosws update``
.. _U5:
U5: Updating a rosinstall tree
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
``rosinstall ~/workspace``
New command example::
``cd ~/workspace``
``rosws update sometree``
.. _U6:
U6: Changing the version of a specific stack
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can manually edit the file ``.rosinstall`` in a rosinstall managed workspace and then call ``rosinstall ~/workspace``.
New command example::
``cd ~/workspace``
``rosws set stackname --version=newversion``
.. _U7:
U7: Overlaying a released ROS package with the sources
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
e.g. taking the sources from trunk, using ``roslocate``
``roslocate info common_msgs | rosinstall add .``
New command example::
``cd ~/workspace``
``roslocate info common_msgs | rosws merge -``
.. _U8:
U8: Rearranging the order of entries in the ``ROS_PACKAGE_PATH``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can manually edit the file ``.rosinstall`` in a rosinstall managed workspace and then call ``rosinstall ~/workspace``
.. _U9:
U9: Removing directories from the ``ROS_PACKAGE_PATH``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can manually edit the file ``.rosinstall`` in a rosinstall managed workspace and then call ``rosinstall ~/workspace``
New command example::
``cd ~/workspace``
``rosws remove foo``
.. _U10:
U10: Checking the validity of the current ROS environment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
using diverse file exploration tools
.. _U11:
U11: Creating a snapshot of the configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
``rosinstall ~/workspace --generate-versioned-rosinstall=GENERATE_VERSIONED``
New command example::
``cd ~/workspace``
``rosws info --yaml > GENERATE_VERSIONED``
.. _U12:
U12: Modifying the current configuration according to a snapshot
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
same as U4_
.. _U13:
U13: Basing the environment on a different ``ROS_ROOT``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Users should generall avoid doing this, as it can lead to failure in many ways.
Therefore not implementing the usecase in this REP, meaning user has
to manually modify ``.rosinstall`` and call rosinstall
.. _U14:
U14: Create a new environment based on an existing one
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
``rosinstall ~/workspace /path/to/other/workspace``
New command example::
``rosws init ~/workspace /path/to/other/workspace``
.. _U15:
U15: Moving a local stack to a different location
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The user has some ROS stack in directory foo, and want to move that
stack to directory bar. This means moving the files as well as
updating the ``.rosinstall`` and the ``setup.sh``.
Will not be supported for now.
.. _U16:
U16: User makes arbitrary changes to .rosinstall
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
An expert user can change path, version, scm, entry order, etc. in his
rosinstall. In some cases he then just wants his ``setup.sh`` file to be
regenerated, in other cases he may want to update directories to
specific revisions.
``rosinstall ~/workspace``
New command example::
``cd ~/workspace``
``rosws update foostack``
``rosws regenerate``
.. _U17:
U17: User wants to see combined diff
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When the user works on several interdependent stacks, he wants to
create a unified diff of those stacks against their checked-out
revision.
``rosinstall ~/workspace --diff``
New command example::
``cd ~/workspace``
``rosws diff``
.. _U18:
U18: User wants to status of scm files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When the user works on several interdependent stacks, he wants to
see what files are currently in a changed status in their respective SCM.
``rosinstall ~/workspace --status``
New command example::
``cd ~/workspace``
``rosws status``
.. _Analysis:
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
-----------------------------------
==== ====== ========= ======= ====== ========== ======= ========= =========
UC init_ merge_ set_ info_ update_ diff_ status_ remove_
==== ====== ========= ======= ====== ========== ======= ========= =========
U1_ x x x
U2_ x
U3_ x x x
U4_ x x
U5_ x
U6_ x x
U7_ x x
U8_
U9_ x
U10_
U11_ x
U12_ x x
U14_ x x
U15_
U16_ x
U17_ x
U18_ x
==== ====== ========= ======= ====== ========== ======= ========= =========
.. _Motivation:
Motivation
==========
The rosinstall tool, while useful, has a command-line syntax that
can be difficult for beginners of ROS to become familiar with. Users
who are intimidated by rosinstall can resort to manually creating
source trees and maintaining ``ROS_PACKAGE_PATH`` by hand. Improving
the usability of the rosinstall tool can improve the ROS experience
for beginner users as well as introduce advanced users to more
powerful features.
.. _Rationale:
Rationale
=========
The extended command structure allows to perform a broader range of
operations concerning multiple SCMs, and mere investigative commands.
Breaking down functionality helps self-explaining of the tool.
Also this makes it easier to extend rosinstall with other functions, and
to use rosintall in scripts (e.g. provide a curses/tk-based rosinstall
ui).
Another problem are the ``--options``. Those are only required in
specific use-cases, but in the current solution the user may provide
them in any case, and thus the user will have difficulties to tell
what his choices for options are, given his intention. Having distinct
commands allows a help function to quickly tell the user what options
are available for his specific intention.
The SCM like structure also allows code completion to provide command
choices, which is a significant help for users when learning a new tool.
The vision of the source code is that it will one day in large parts
be moved out of rosinstall to provide ROS-independent functionality
for managing directories of mutliple SCMs. However the rosinstall
functionality of generating setup files for ROS environments will
remain important. Therefore a name change to rosws is suggested rather
than a ROS-independent name.
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
.. _Compatibility:
Backwards Compatibility
=======================
The rosinstall setup files remain unchanged.
Current rosinstall syntax is:
::
Usage: rosinstall PATH [<options> ...] [URI]...
Options:
--version show program's version number and exit
-h, --help show this help message and exit
-n, --nobuild skip the build step for the ROS stack
--rosdep-yes Pass through --rosdep-yes to rosmake
--continue-on-error Continue despite checkout errors
--delete-changed-uris
Delete the local copy of a directory before changing
uri.
--abort-changed-uris Abort if changed uri detected
--backup-changed-uris=BACKUP_CHANGED
backup the local copy of a directory before changing
uri to this directory.
--generate-versioned-rosinstall=GENERATE_VERSIONED
generate a versioned rosintall file
``--generate-versioned-rosinstall`` is a special case and is replaced
by ``rosinstall snapshot``.
This will be fulfilled by ``rosws install``.
The change in command syntax impacts rosinstall based tools such as the
new proposal for a rosworkspace.
.. _Design-Alternatives:
Design Alternatives
===================
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_.
.. _Reference-implementation:
Reference implementation
========================
Reference implementation is provided with the latest rosinstall release.
.. _Rejects:
Rejects
=======
Ideas for rosinstall commands that were dropped for this REP, but may
become interesting later:
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.
.. _References:
References
==========
.. [1] rosinstall
(
http://www.ros.org/wiki/rosinstall)
.. _Copyright:
Copyright
=========
Copyright (c) 2011 by Thibault Kruse. This material may be distributed only subject to
the terms and conditions set forth in the Open Publication License, v0.1 or later
(the latest version is presently available at
http://www.opencontent.org/openpub/).
..
Local Variables:
mode: indented-text
indent-tabs-mode: nil
sentence-end-double-space: t
fill-column: 70
coding: utf-8
End:
(text/plain)