REP: 124 Title: Changes to roslaunch and rosrun for REP 122 and catkin build system Author: Ken Conley, Brian Gerkey Status: Draft Type: Standards Track Content-Type: text/x-rst Created: 8-Feb-2012 ROS-Version: Fuerte Post-History: 8-Feb-2012
This REP describes changes to roslaunch [1] made necessary by the
Filesystem Hierarchy Standard [2] changes in REP 122 [3] as well as
changes necessary for compatibility with the catkin build system. A
non-backwards-compatible change is introduced for the <machine>
tag. The mechanism for locating package-relative executables is also
changed in order to find executables in an out-of-source, catkin-based
build.
The <machine> tag now uses the following syntax for setting environment variables on a remote machine:
<machine env-loader="path/to/env-loader.sh" />
For example:
<machine env-loader="/opt/ros/fuerte/env.sh" />
The env-loader file must be an executable script that accepts
variable-length arguments. After performing environment setup, the
script must then execute its arguments as a command. ROS
installations come with a default environment loader file.
The env-loader attribution is optional. If it is not set, it
defaults to /opt/ros/<distro-name>/env.sh, where <distro-name> is
the ROS distribution named defined by the rules in REP 123 [2].
The following attributes are no longer supported and will raise errors:
ros-root ros-package-path
Also, the <env> tag is no longer supported inside of a
<machine> tag and will also raise an error.
The configuraton file for roscore is now stored in etc/ros.
roslaunch obeys REP 123 [2] for locating etc/ros.
This roscore.xml configuration file is a roslaunch file that
defines the nodes that are launched with roscore is run. It was
previously stored in the roslaunch directory.
The following sections describe the effects on and updates to the ROS package-relative specification for the new FHS layout. They also discuss changes to Python library loading and a minor change to the ROS package manifest format.
Package-relative executables are files specified with
(<ros-package-name>, <file-name>), where <file-name> denotes a
file with executable permissions.
The executable is looked up in the folder lib/ros-package-name.
Additionally rosrun will crawl the package directory (where the
package manifest file is located) recursively for executables with the
name file-name.
If multiple executables with the same name are found in different
locations rosrun will query the user to select one of the
executables.
Package-relative executables are files specified with
(<ros-package-name>, <relative-file-path>), where
<relative-file-path> denotes a file with executable permissions
relative to root of the packages source directory.
In an install tree the executable might have been installed into the
FHS compliant location under lib/ros-package-name. Therefore
roslaunch checks first if an executable exist in this location with
the filename specified in relative-file-path (without the path
information).
The changes in this REP enable roslaunch to maintain compatibility with the changes introduced by REP 122. As the FHS layout and underlying out-of-source build implementation affect the location of binaries and data files, roslaunch is heavily impacted by these changes.
In the longer term, changes to the roslaunch model may enable even better integration with the REP 122 changes. Such changes are considered out-of-scope for this REP, which is instead focused on compatibility updates.
In order to facilitate an efficient write-compile-run development cycle, it is necessary to easily run executables that are compiled to the build directory. In particular, because tools like roslaunch and rosrun use a package-relative scheme for locating executables, this same scheme must work with build artifacts. Otherwise, the user would have to install the build artifacts, which would lengthen the development cycle.
Out-of-source build systems are more complicated as an executable may be a binary build artifact, or it can be a script with executable permission in the source tree.
An alternative would be to make allow a package to have multiple
directories, such as setting the ROS_PACKAGE_PATH to point to
multiple locations. This would have numerous undesireable effects,
such as disabling the ability to override existing packages, and also
not have backwards-compatibility with many tools.
Another alternative would be to copy the entire source tree into the
build space and point the ROS_PACKAGE_PATH there. This is similar
to how tools like Eclipse perform out-of-source builds. This was
considered undesireable as it would lengthen the development cycle for
script executables, such as Python scripts, as a build would be
required each time the script was modified in order to copy it back to
the build space.
The env-loader attribute was made optional because the most common
value encodes the name of the current ROS distribution. This would
make it difficult, moving forward, to maintain the same set of launch
files for different distributions. The default value will allow
things to "just work" in the most common case.
The rationale for these changes is discussed in the "Backwards Compatibility" section below.
The roslaunch <machine> tag previously assumed that it was
possible to construct the remote execution environment using
ROS_ROOT and ROS_PACKAGE_PATH. As described above,
ROS_ROOT no longer describes the path to ROS top-level binaries,
including the roslaunch executable.
There is no way to correctly determine the remote execution
environment using the <machine> tag as specified in ROS Electric.
roslaunch could attempt to infer settings by pattern matching on the
values present in the tag, but this approach would be very brittle.
Instead, there is an intentional, non-backwards-compatible change to
the <machine> tag so that users are immediately notified of this
issue and can easily migrate to the new tag. This requires developers
to maintain two sets of launch files with machine tags if they wish to
use them both in ROS Fuerte and previous ROS distributions. This is
inconvenient, but less problematic than hard-to-debug issues with
remote environment setup.
| [1] | roslaunch wiki page (http://ros.org/wiki/roslaunch) |
| [2] | (1, 2, 3) Wikipedia: Filesystem Hiearchy Standard (http://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard) |
| [3] | REP 122: FHS layout for ROS installation (http://ros.org/reps/rep-0122.html) |
| [4] | REP 123: ROS_ETC_DIR, ROS_DISTRO environment variables and ROS_ROOT changes (http://ros.org/reps/rep-0123.html) |
This document has been placed in the public domain.