Removing <run_depend>

The <run_depend> tag generated considerable confusion within the ROS user and developer community [3]. Everyone understood that it was needed when a package required another to be available at execution-time. But, most people did not grasp the subtle transitive build-time dependency introduced when a header exported by a package included one from some other package. In that case, the required <run_depend> tag name was quite misleading.

Creating specific tags for those two different meanings reduces confusion, and improves packaging efficiency because <build_export_depend> normally resolves to a development package, while <exec_depend> generally refers to an execution-time binary package [8]. Although most existing ROS components are not divided into development and execution-time packages, many system dependencies are separated in that way. The new tags can take advantage of that immediately.

With the new tags defined, <run_depend> was no longer needed. Removing it draws attention to the former confusion and helps resolve it correctly. When each package is upgraded from format one to this new specification, <run_depend> must be converted to one or both of the new tags, as appropriate.

Adding <depend>

Very few ROS packages have been split into separate development and execution-time packages. So, most ROS package dependencies must repeat the same name in several tags, typically <build_depend> and <run_depend>. With <run_depend> now divided into <build_export_depend> and <exec_depend>, that problem gets worse.

The <depend> tag eliminates the repetition, combining all those dependencies into one [3]. While <depend> can be misused [6], it is good to have when appropriate.

Disabling unit tests

Formerly, catkin unit tests were not cleanly separated from the rest of the package and were always configured (even if not being built later). But there are sometimes reasons to build a package without its tests or their configure time dependencies. For generated Debian or RPM packages they would not run anyway, and should not be installed. When building from source for small embedded systems, disabling the tests reduces the number of dependencies which must also be built and installed.

The solution adopted introduces two CMake configuration variables:

• CATKIN_ENABLE_TESTING controls whether the tests will be built. Packages should test this variable within their CMakeLists.txt, to ensure that no test artifacts are configured or built, unless enabled.
• CATKIN_SKIP_TESTING can be used to build without tests even for packages created before CATKIN_ENABLE_TESTING became available. This option does not build as efficiently, and may display warning messages during the build. It is a migration aid, for use while packages are being upgraded to explicitly enable and disable testing themselves.

Making <test_depend> easier to use

With format one, <test_depend> could not co-exist with other types of dependencies, nor could testing-only packages provide any build or configuration information.

For example, rostest defines an add_rostest() CMake command. Using it required a <build_depend>rostest</build_depend>, even though it was only needed when testing is enabled. Even worse, also declaring <test_depend>rostest</test_depend> was considered an error.

With format two, a <test_depend> for rostest works as expected, no separate <build_depend> is required in that case. That assumes that the configure step is done with the flag CATKIN_ENABLE_TESTING being set and that the package correctly uses the flag to disable all configuration of unit tests. Moreover, packages needed for several reasons may now be declared using any desired combination of dependency types, including <test_depend>.

<package format="2">

The <package> tag is the unique top-level tag in a package.xml file. All other tags are nested under it.

Required Tags

The required tags in a package.xml file provide package meta-data:

• <name>
• <version>
• <description>
• <maintainer> (multiple, but at least one)
• <license> (multiple, but at least one)

Optional Tags

Example

<package format="2">
  <name>my_package</name>
  <version>1.2.3</version>
  <description>
    This is my package's description.
  </description>
  <maintainer email="someone@example.com">Someone</maintainer>

  <license>BSD</license>
  <license>LGPL</license>

  <url type="website">http://wiki.ros.org/my_package</url>
  <url type="repository">http://www.github.com/my_org/my_package</url>
  <url type="bugtracker">http://www.github.com/my_org/my_package/issues</url>
  <author>John Doe</author>
  <author email="jane.doe@example.com">Jane Doe</author>

  <buildtool_depend>catkin</buildtool_depend>
  <build_depend version_gte="1.1" version_lt="2.0">genmsg</build_depend>

  <depend>roscpp</depend>

  <build_depend>libgstreamer0.10-dev</build_depend>
  <build_export_depend>libgstreamer0.10-dev</build_export_depend>
  <exec_depend>libgstreamer0.10-0</exec_depend>

  <test_depend>gtest</test_depend>

  <doc_depend>doxygen</doc_depend>

  <conflict>alternative_implementation</conflict>

  <replace>my_old_package</replace>

  <export>
    ...
  </export>
</package>

<name>

The package name must start with a letter and contain only lowercase alphabetic, numeric or underscore characters [2]. The package name should be unique within the ROS community. It may differ from the folder name into which it is checked out, but that is not recommended.

The following recommended exemptions apply, which are optional for implementations:

• Dashes may be permitted in package names. This is to support maintaining a consistent dependency name when transitioning back and forth between a system dependency and in-workspace package, since many rosdep keys contain dashes (inherited from the Debian/Ubuntu name).
• In support of some legacy packages, capital letters may also be accepted in the package name, with a validation warning.

<version>

The version number of the package in the format MAJOR.MINOR.PATCH where each part is numeric only.

<description>

The description of the package. It can consist of multiple lines and may contain XHTML. But depending on where the description is used XML tags and multiple whitespaces might be stripped.

<maintainer> (multiple, but at least one)

The name of the person maintaining the package. All packages require a maintainer. For orphaned packages see below.

<maintainer email="ros-orphaned-packages@googlegroups.com">Unmaintained see http://wiki.ros.org/MaintenanceGuide#Claiming_Maintainership</maintainer>

<license> (multiple, but at least one)

Name of license for this package, e.g. BSD, GPL, LGPL. In order to assist machine readability, only include the license name in this tag. For multiple licenses multiple separate tags must be used. A package will have multiple licenses if different source files have different licenses. Every license occurring in the source files should have a corresponding <license> tag. For any explanatory text about licensing caveats, please use the <description> tag.

Most common open-source licenses are described on the OSI website.

Commonly used license strings:

• Apache 2.0
• BSD
• Boost Software License
• GPLv2
• GPLv3
• LGPLv2.1
• LGPLv3
• MIT
• Mozilla Public License Version 1.1

<url> (multiple)

A Uniform Resource Locator for the package's website, bug tracker or source repository.

It is a good idea to include <url> tags pointing users to these resources. The website is commonly a wiki page on ros.org where users can find and update information about the package.

<author> (multiple)

The name of a person who is an author of the package, as acknowledgement of their work and for questions.

<build_depend> (multiple)

Declares a rosdep key or ROS package name that this package requires at build-time. For system packages, the rosdep key will normally specify the "development" package, which frequently ends in "-dev".

The build and buildtool dependencies are used to determine the build order of multiple packages.

<build_export_depend> (multiple)

Declares a rosdep key or ROS package name that this package needs as part of some build interface it exports. For system packages, the rosdep key will normally specify the "development" package, which frequently ends in "-dev".

The <build_export_depend> declares a transitive build dependency. A common example is when one of your dependencies provides a header file included in some header exported by your package. Even if your package does not use that header when building itself, other packages depending on your header will require those transitive dependencies when they are built.

<buildtool_depend> (multiple)

Declares a rosdep key or ROS package name for a tool that is executed during the build process. For cross-compilation, one must distinguish these from normal build dependencies, which may be linked with your package and must be compiled for the target architecture, not the build system. For system packages, the rosdep key will normally specify the "development" package, which frequently ends in "-dev".

<buildtool_export_depend> (multiple)

Declares a rosdep key or ROS package name that this package exports which must be compiled and run on the build system, not the target system. For cross-compilation, one must distinguish these from target build dependencies, which may be linked with your package and must be compiled for the target architecture.

<exec_depend> (multiple)

Declares a rosdep key or ROS package name that this package needs at execution-time. For system packages, the rosdep key will normally not specify the "development" package, so it will generally lack the "-dev" suffix.

The <exec_depend> is needed for packages providing shared libraries, executable commands, Python modules, launch scripts or any other files required for running your package. It is also used by metapackages for grouping packages.

<depend> (multiple)

Declares a rosdep key or ROS package name that this package needs for multiple reasons. A <depend> tag is equivalent to specifying <build_depend>, <build_export_depend> and <exec_depend>, all on the same package or key. The <depend> tag cannot be used in combination with any of the three equivalent tags for the same package or key name.

<doc_depend> (multiple)

Declares a rosdep key or ROS package name that your package needs for building its documentation. A <doc_depend> may reference a package also declared as some other type of dependency.

The current version of the buildsystem does not provide any documentation specific functionality or targets but may do so in the future, similar to how the unit tests are integrated into the configure and make steps. Other infrastructure (like the documentation jobs on the buildfarm) will utilize these additional doc dependencies.

Generated Debian packages are built without the documentation or the documentation dependencies.

<test_depend> (multiple)

Declares a rosdep key or ROS package name that your package needs for running its unit tests. A <test_depend> may reference a package also declared as some other type of dependency.

All tests and their dependencies will be built if the CMake variables CATKIN_ENABLE_TESTING=1 and CATKIN_SKIP_TESTING=0, the default settings. CMakeLists.txt should only define its test targets when CATKIN_ENABLE_TESTING=1 [9].

When building with testing enabled, the <test_depend> packages are available for configuring and building the tests as well as running them. Generated Debian packages are built without the unit tests or their dependencies.

<conflict> (multiple)

Declares a rosdep key or ROS package name with which your package conflicts. This package and the conflicting package should not be installed at the same time. This has no effect on source builds, but maps to Conflicts when creating Debian or RPM packages.

For a detailed explanation how these relationships are used see [4] and [5].

<replace> (multiple)

Declares a rosdep key or ROS package name that your package replaces. This has no effect on source builds, but maps to Replaces when creating Debian packages and Obsoletes for RPM packages.

<export>

This tag serves as a container for additional information various packages and subsystems need to embed. To avoid potential collisions, an export tag should have the same name as the package which is meant to process it. The content of that tag is up to the package to define and use.

Existing rosbuild export tags for tools using pluginlib remain unchanged. For example, a package which implements an rviz plugin might include this:

<export>
  <rviz plugin="${prefix}/plugin_description.xml"/>
</export>

The following are some tags used within an <export> for various package and message generation tasks.

<build_type>catkin</build_type>
<build_type>cmake</build_type>

<export>
  <deprecated>
    This package will be removed in ROS Hydro. Instead, use package
    FOO, which provides similar features with a different API.
  </deprecated>
</export>

<export>
  <message_generator>cpp</message_generator>
</export>

cmake_minimum_required(VERSION 2.8.3)
project(PACKAGE_NAME)
find_package(catkin REQUIRED)
catkin_metapackage()

<buildtool_depend>catkin</buildtool_depend>

<exec_depend>your_custom_msgs</exec_depend>
<exec_depend>your_server_node</exec_depend>
<exec_depend>your_utils</exec_depend>
<exec_depend>another_metapackage</exec_depend>

Modifications to REP-0127

• <run_depend> was replaced by <build_export_depend> and <exec_depend>.
• <depend> was added as a synonym for <build_depend>, <build_export_depend> and <exec_depend>.
• <test_depend> now fulfills configuration and build-time test requirements in addition to the objects needed for running them.
• <doc_depend> was added for documentation specific dependencies.
• <buildtool_export_depend> was added to enable the same cross-compilation semantic for <build_export_depend> as it is already available with <buildtool_depend> for <build_depend>.

Backward compatibility

Format one packages following REP-0127 [1] are not affected unless they are updated to declare <package format="2">, at which time all <run_depend> elements must be removed and replaced with other appropriate dependencies.