rosco

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:

1. Lookup the rosinstall entry for the package/stack using roslocate.
2. Update your rosinstall configuration with this information.
3. 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

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 API

roslocate has a command-based API. Each of the commands is described below.

$ 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

$ roslocate info common
- hg:
    local-name: common
    meta:
      repo-name: wg-kforge
    uri: https://kforge.ros.org/common/common
    version: default

$ roslocate repo cram_pl
tum-ros-pkg

$ roslocate uri rospy
https://code.ros.org/svn/ros/stacks/ros_comm/trunk/clients/rospy

$ roslocate vcs common
hg

$ roslocate www rospy
http://ros.org/wiki/rospy

$ 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

$ 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

rosco command-line API

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.

$ roslocate info rospy | rosco

Packaging

rosco and roslocate are distributed as scripts with the rosinstall PyPI package.

rosco API

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.

--dev

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.

Removal of roslocate rosinstall

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.

rosco

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.