REP: 115 Title: rosco and roslocate tools for rosinstall Author: Ken Conley <kwc@willowgarage.com> Status: Final Type: Standards Track Content-Type: text/x-rst Created: 01-Sep-2011 Post-History: 01-Sep-2011, 02-Sep-2011
This REP proposes two updates to rosinstall: roslocate and
rosco. roslocate enables users to locate rosinstall entries
and other information about ROS stacks and packages. rosco
supports source-control checkout of any rosinstall entry.
This specification frequently refers to rosinstall entries. To clarify the meaning of this, in this REP we use rosinstall entry to mean a single YAML list element that describes source control information for rosinstall.
Example:
- hg:
local-name: common
meta:
repo-name: wg-kforge
uri: https://kforge.ros.org/common/common
version: default
rosinstall [1] is a useful tool for managing a consistent
development tree of multiple ROS stacks. It takes care of important
environment configuration, tree updates, and more. It is less useful
in situations where you just want to quickly get the source for a
particular stack or package as it does more than just retrieve code.
For example, you want to add a stack to an existing checkout, you may have to:
- Lookup the rosinstall entry for the package/stack using
roslocate. - Update your rosinstall configuration with this information.
- Run rosinstall, which will iterate through all entries in the rosinstall configuration.
If you have multiple entries in the rosinstall configuration, you will have to wait as rosinstall examines each entry for updates.
rosco is instead motivated by "give me the source, now." In
exchange for this haste, it does not do any bookkeeping or environment
configuration for you: it is tries to be equivalent to running svn
co, git clone, or the like.
roslocate is a tool for finding version-control and other
information about a ROS package or stack. The main use case is
"locate the source code repository of this resource," though it can
also provide additional metadata about that resource. It is designed
to be a command-line interface for accessing information produced by
the ROS.org indexing system, which crawls the known public
repositories of ROS-compatible software.
roslocate has existed for quite some time in ROS, though its
current incarnation is fairly recent. A new prototype was written in
December 2010 [4] to emit rosinstall entries as the original version
was SVN-centric and had scaling issues. The prototype was later
included with rosinstall to test its usefulness. After upgrades
to the ROS.org indexing system were made, an updated version of this
prototype was introduced on ros-developers in July 2011 [5] to
add distribution-specific searches for its commands (--dev,
--distro).
Although roslocate has existed for awhile in various forms, it has
not been formally specified. As there are now tools like rosco
and rosws [3] that depend on this API, it is more important to
provide this specification.
roslocate has a command-based API. Each of the commands is described below.
roslocate describe summarizes information about a ROS package or
stack.
Example:
$ roslocate describe rosinstall Type: package Stack: ros_release Description: rosinstall is a tool to check out ROS source code (or any source code, really) from multiple version control repositories and updating these checkouts. Given a *.rosinstall file that specifies where to get code, rosinstall will check out a working copy for you. We recommend the use of rosinstall when checking out development versions of ROS source code. This package is where the code lives, however it is not expected for users to checkout and use this package directly. It is expected that users use the version available through pypi.python.org. URL: http://ros.org/wiki/rosinstall
Prints the rosinstall entry for the resource.
Example:
$ roslocate info common
- hg:
local-name: common
meta:
repo-name: wg-kforge
uri: https://kforge.ros.org/common/common
version: default
Prints the name of the repository the resource is stored in. This repository name is for display purposes only -- it cannot be used as input to source control tools.
Example:
$ roslocate repo cram_pl tum-ros-pkg
Prints the source control URI of a resource. This is mainly intended as input to other programs via shell backtick or pipe.
Example:
$ roslocate uri rospy https://code.ros.org/svn/ros/stacks/ros_comm/trunk/clients/rospy
Prints the type of version control system used for the resource.
Possible values include svn, hg, git, and bzr.
Example:
$ roslocate vcs common hg
Prints the website of a resource.
Example:
$ roslocate www rospy http://ros.org/wiki/rospy
If the --distro=DISTRO_NAME option is combined with a roslocate
command, the information returned will be based on a particular
distribution release of a resource.
Example:
$ roslocate info rospy
- svn:
local-name: rospy
uri: https://code.ros.org/svn/ros/stacks/ros_comm/trunk/clients/rospy
$ roslocate info rospy --distro=diamondback
- svn:
local-name: ros_comm
uri: https://code.ros.org/svn/ros/stacks/ros_comm/tags/ros_comm-1.4.7
If the --dev option is combined with a roslocate command, the
information returned will be based on the development branch of the
resource (e.g. trunk), if possible. It should be used in
combination with the --distro=DISTRO_NAME option as development
trees are indexed based on a particular ROS distribution.
The -dev option generally only affects source control information,
like URIs and rosinstall entries. Other information, like resource
descriptions, are not guaranteed to be development-branch specific.
Example:
$ roslocate info rospy --distro=electric
- svn:
local-name: ros_comm
uri: https://code.ros.org/svn/ros/stacks/ros_comm/tags/ros_comm-1.6.0
$ roslocate info rospy --distro=electric --dev
- svn:
local-name: ros_comm
uri: https://code.ros.org/svn/ros/stacks/ros_comm/trunk
The rosco command is roughly equivalent to running the equivalent
svn, git, or other source control tool to "checkout" or
"clone" a repository. It does not record any additional state.
Searches for the specified ROS package or stack and retrieves the
source code use the appropriate version control tool. For example, if
the source code is stored in a Subversion repository, rosco will
run a svn checkout of the resource in the local directory.
For each entry in the rosinstall file, retrieve the source code use
the appropriate version control tool. Unlike rosinstall, it only
retrieves the source code and nothing more.
rosco also accepts piped input formatted as rosinstall entries.
This is primarily meant to be used in combination with roslocate.
Example:
$ roslocate info rospy | rosco
Checkout the source code for a particular ROS distribution release,
e.g. rosco rospy --distro=electric will checkout the Electric
release of rospy. This option is not valid when used with --rosinstall.
The --dev option causes rosco to checkout the development
branch instead. It should be specified in combination with a
--distro=DISTRO_NAME option as development branches are
distribution specific.
rosco and roslocate are distributed as scripts with the
rosinstall PyPI package.
The original rosco prototype had a different command-line specification:
rosco <rosinstall-file>
This style favored rosinstall entries for the API. The revised API is
based on discussions with Ibrahim Awwal on ros-users [6]. Ibrahim
wrote a different rosco prototype that favored package and stack
names as the primary argument. This syntax is more direct as it omits
the intermediate step of having to run the roslocate tool to
generate the rosinstall data.
Both roslocate and rosco return the released version of a
stack by default. Thus, by default, users will get a working code
tree. There is also no option to select between the version-based tag
and a distribution-based tag of a resource: the version-based tag is
always used. This simplifies the command-line API as users don't have
to distinguish between these two different types of tags. Although
tracking tags, e.g. distribution-based tags, are useful, they
encounter issues on VCS tools like git and we may phase them out
in the future.
This REP removes the roslocate rosinstall command that was part of
the prototype tool. Originally, roslocate had separate
rosinstall and info subcommands. The rosinstall command
was meant to return the exact rosinstall entry used to generate the
index information, whereas info was meant to provide more advanced
URL computations, like returning the URL of a specific package inside
a stack. The distinction between these two was confusing and
dependent on the implementation of the indexer.
The new rosco API is not compatible with the original prototype.
As the original prototype had limited visiblity, this is assumed to
not be a major issue.
Reference implementation code is located in SVN repository at:
https://code.ros.org/svn/ros/stacks/ros_release/trunk/rosinstall
| [1] | rosinstall (http://www.ros.org/wiki/rosinstall) |
| [2] | roslocate (http://www.ros.org/wiki/roslocate) |
| [3] | rosws (http://www.ros.org/wiki/rosws) |
| [4] | [ros-developers] roslocate2 (https://code.ros.org/lurker/message/20101221.230920.c59b4048.en.html) |
| [5] | [ros-developers] Version-specific index and roslocate prototype (http://code.ros.org/lurker/message/20110711.160222.666ecfe4.gl.html) |
| [6] | [ros-users] Rosco - ros.org checkout tool (http://code.ros.org/lurker/message/20110818.223024.9c374482.en.html) |
This document has been placed in the public domain.