[REP Index] [REP Source]

REP:140
Title:Package Manifest Format Two Specification
Author:Dirk Thomas, Jack O'Quin
Status:Final
Type:Standards Track
Content-Type:text/x-rst
Created:26-Jun-2013
Post-History:12-Mar-2014

Abstract

This REP specifies the second package.xml format, replacing the one specified in REP-0127 [1]. It is relevant for packages using the catkin build system.

Motivation

Overall, the initial package definition worked well. Hundreds of packages were converted from rosbuild to catkin using that interface. But, experience has revealed some areas which need to be improved.

The biggest problem was user confusion due to the two meanings of the <run_depend> tag. Replacing it with <exec_depend> and <build_export_depend> makes the semantics of both types much clearer.

A lesser issue was the need to declare most ROS package dependencies twice, using both <run_depend> and <build_depend>. To aleviate this redundancy the <depend> tag was introduced.

Also, as use of the package format has matured, the need has arrisen for some additional dependency tag types, e.g. <doc_depend>. Additionally, the <test_depend> tag's semantics is changed such that it covers configure as well as run time dependencies related to testing. Before it only covered run dependencies and configure time test dependencies needed to be listed with the <build_depend> tag.

Rationale

REP-0127 [1] provides the basic package.xml design rationale, which is not repeated here.

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>.

Data Representation

The package manifest is an XML file, with restricted syntax.

The only top-level element allowed is <package>. Immediately subordinate to that are several required or optional elements, defined here. No other tags are permitted directly under the <package> element.

<package format="2">

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

Attributes

format="NUMBER"

Specifying the package.xml format being used. If not set, format="1" would be assumed, which is not the format described here. For this interface, you must specify format="2". If you are using a different format, please refer to the relevant specification. REP-0127 [1] described format one.

Optional Tags

Meta-information

Optional, but recommended, meta-data include the names of the original authors and links to support documentation.

Dependencies

The dependencies and relations to other packages and system packages have been discussed in [7]. They are described using:

These dependency tags are used with both system packages and ROS packages. For system dependencies specify the rosdep key name, for ROS dependencies use the package name.

The dependency graph must be acyclic. No package may directly or indirectly depend on itself.

Various

There is a need for additional meta-data in the manifest for other tools that work with packages, like message generators and plugin discovery. Tags for that kind of information are wrapped within this tag:

Some <export> tags used by catkin are defined below. Others are defined by various tools, which must specify their own specific tag structures.

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.

<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.

Attributes

email="name@domain.tld" (required)

Email address of the maintainer.

An orphaned package is one with no current maintainer. Orphaned packages should have their maintainer set to ROS Community <ros-release@code.ros.org>. These packages will be maintained by the ROS Community as a whole until a volunteer takes over maintenance.

Example

<maintainer email="ros-release@code.ros.org">ROS Community</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.

Attributes

type="TYPE" (optional)

The type should be one of the following identifiers: website (default), bugtracker or repository.

<author> (multiple)

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

Attributes

email="name@domain.tld" (optional)

Email address of author.

<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.

Attributes

All dependencies and relationships may restrict their applicability to particular versions. For each comparison operator an attribute can be used. Two of these attributes can be used together to describe a version range.

version_lt="VERSION" (optional)

The dependency to the package is restricted to versions less than the stated version number.

version_lte="VERSION" (optional)

The dependency to the package is restricted to versions less or equal than the stated version number.

version_eq="VERSION" (optional)

The dependency to the package is restricted to a version equal than the stated version number.

version_gte="VERSION" (optional)

The dependency to the package is restricted to versions greater or equal than the stated version number.

version_gt="VERSION" (optional)

The dependency to the package is restricted to versions greater than the stated version number.

<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.

Attributes

The same attributes as for <build_depend> (multiple).

<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".

Attributes

The same attributes as for <build_depend> (multiple).

<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.

Attributes

The same attributes as for <build_depend> (multiple).

<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.

Attributes

The same attributes as for <build_depend> (multiple).

<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.

Attributes

The same attributes as for <build_depend> (multiple).

<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.

Attributes

The same attributes as for <build_depend> (multiple).

<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.

Attributes

The same attributes as for <build_depend> (multiple).

<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].

Attributes

The same attributes as for <build_depend> (multiple).

<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.

Attributes

The same attributes as for <build_depend> (multiple).

<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.

<architecture_independent/>

This empty tag indicates that your package produces no architecture-specific files once built. That information is intended for allowing optimization of packaging.

Specifying <architecture_independent/> is recommended for metapackages and for packages defining only ROS messages and services. Python-only packages are reasonable candidates, too. It is not appropriate for any package which compiles C or C++ code.

Be sure to remove this tag if some subsequent update adds architecture-dependent targets to a formerly independent package.

<build_type>

Various tools use this tag to determine how to handle a package. It was defined in REP-0134 [10], which currently specifies only two valid values:

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

If no <build_type> is provided, catkin is assumed.

When the build type is cmake, the package is handled as a non-catkin CMake project. It cannot be included in a normal catkin workspace, but can instead use catkin_make_isolated, which configures and builds a different kind of workspace in which cmake, make, and make install are invoked separately for each package. See REP-0134 for details.

Further build types may eventually be defined, such as: "make", "autotools", "rosbuild", or "custom".

<deprecated>

This tag indicates that your package is deprecated, enabling tools to notify users about that fact. The tag may be empty or may optionally contain an arbitrary text providing user more information about the deprecation:

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

<message_generator>

The content defines the identifier for the language bindings generated by this package, i.e. in gencpp this is set to cpp:

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

<metapackage/>

This empty tag declares a special kind of catkin package used for grouping other packages. Metapackages only provide execution-time dependencies. They cannot be used for catkin builds and compile nothing themselves. Metapackages may not install any code or other files, although package.xml does get installed automatically. They can depend on other metapackages, but regular catkin packages cannot.

A good use for metapackages is to group the major components of your robot and then provide a comprehensive grouping for your whole system. Package installation tools like apt-get or yum can automatically install all the packages on which a metapackage directly or indirectly depends. Metapackages can also be used to resolve dependencies declared by legacy rosbuild stacks not yet converted to catkin.

Every metapackage must have a CMakeLists.txt containing these commands:

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

Because the metapackage CMakeLists.txt contains a catkin macro, its package.xml must declare a buildtool dependency on catkin:

<buildtool_depend>catkin</buildtool_depend>

Additional buildtool, build or test dependencies are not permitted.

Because metapackages only supply execution-time dependencies, they use <exec_depend> to list the packages in their group:

<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>

Compatibility

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.

Schema

A schema defining the structure specified in this document is available at [11]. To specify the schema within a manifest you can reference a self contained schema file like this:

<?xml version="1.0"?> <?xml-model href="http://download.ros.org/schema/package_format2.xsd" schematypens="http://www.w3.org/2001/XMLSchema"?> <package format="2">