|Title:||Changes to roslaunch and rosrun for REP 122 and catkin build system|
|Author:||Ken Conley, Brian Gerkey|
This REP describes changes to roslaunch  made necessary by the Filesystem Hierarchy Standard  changes in REP 122  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" />
<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 .
The following attributes are no longer supported and will raise errors:
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  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 located anywhere in the directory root of <ros-package-name>.
Following the specification for share/, package-relative executables are stored in share/ros-package-name/bin/executable. In an install tree, ROS_PACKAGE_PATH includes the share/ path. Thus, there are no updates to the package-relative executable specification for an install tree.
We amend the package-relative specification for the catkin-based binary builds, which builds out-of-source binaries outside of the ROS source package tree.
In order to find executables generated to a catkin-based build directory, tools must example the $CATKIN_BINARY_DIR/etc/packages.list file for
packages.list is a text file, where each line is of the form:
To locate a package-relative executable when the CATKIN_BINARY_DIR environment variable is set, tools use the following precedence:
- If an entry <ros-package-name> <relative-file-path> is in packages.list, look for binary in $CATKIN_BINARY_DIR/<relative-file-path>
- If executable is not found yet, look for the executable in the ROS package directory.
This implementation assumes that the underlying build system, catkin, properly separates executables into separate directories based on ROS package name to prevent collisions.
This portion of the specification is potentially volatile, as it depends on a implementation that has not been reviewed yet.
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.
There are even more alternatives, but the packages.list specification ultimately is desireable for its simplicity.
The particular implementation using CATKIN_BINARY_DIR creates a design coupling with the catkin build system. It would be desireable to have a more general mechanism for preserving the semantics in an out-of-source build. However, as the specification places requirements on the underlying build system as well, such as keeping executables for packages in separate directories. Thus, this design coupling in unavoidable, so it is made explicit.
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.
|||roslaunch wiki page (http://ros.org/wiki/roslaunch)|
|||(1, 2, 3) Wikipedia: Filesystem Hiearchy Standard (http://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard)|
|||REP 122: FHS layout for ROS installation (http://ros.org/reps/rep-0122.html)|
|||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.