[REP Index] [REP Source]

Title:Changes to roslaunch and rosrun for REP 122 and catkin build system
Author:Ken Conley, Brian Gerkey
Type:Standards Track


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.


<machine> tag

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:


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.

Package-relative executables

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.

Locating package-relative executables with rosrun

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.

Locating package-relative executables with roslaunch

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.


Locating executables in catkin build directories

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.

env-loader optional

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.

Breaking compatibility with <machine> tag

The rationale for these changes is discussed in the "Backwards Compatibility" section below.

Backwards Compatibility

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)