A new filename replacing the existing ones

Instead of modifying the semantics and content of the old files a new filename is chosen to make it possible to distinguish old and new packages without parsing the content of the xml file.

One file per package with all the information

Each package has one package.xml which contains all necessary information (instead of having multiple separate files with semantically grouped informations). This design decision is based on the need to utilize these information in several tools (i.e. buildfarm, wiki) which should only require to fetch one file from a repository.

Catkin-only - no rosbuild information inside

The file only specifies information needed for a ROS ecosystem which is entirely based on catkin. Any additional information necessary for backward compatibility with rosbuild is kept separate (i.e. in the legacy manifest.xml files). This enable to easily remove the legacy files in the future. Legacy files required for rosbuild interaction are fully generated from the new package.xml and the CMakeLists.txt, rather than manually maintained.

Store normalized data

All data is stored in atomic units to enable automated processing. I.e. names and email addresses are not mixed in a single field but stored separately.

Data format

Beside XML (which is used in ROS for stack.xml and manifest.xml) other formats have been considered. Especially yaml has been investigates extensively during the Fuerte cycle. The benchmark results [6] showed that parsing YAML is significantly slower (by a factor of 10). Therefore the format is not changed but will stay XML.

Tags vs. attributes

While plain text information can be stored in either attributes or tags the later is preferred for readability reasons.

Additional (most times optional) information is stored in attributes of the related tag instead of grouping multiple tags inside a parent tag.

<package>

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

Required Tags

The required set of tags in a package.xml file provides basic meta data about the package:

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

Optional Tags

Example

<package>
  <name>my_package</name>
  <version>1.2.3</version>
  <description>
    ROS communications-related packages, including core client libraries (roscpp, rospy, roslisp) and graph introspection tools (rostopic, rosnode, rosservice, rosparam).
  </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="bugtracker">http://www.github.com/my_org/my_package/issues</url>
  <author>John Doe</author>
  <author email="jane.doe@example.com">Jane Doe</author>

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

  <build_depend>libboost-thread-dev</build_depend>
  <run_depend>libboost-thread</run_depend>

  <test_depend>gtest</test_depend>

  <conflict>my_old_package</conflict>

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

<name>

The name of the package consisting only of lower case alphanumeric characters and underscores and must start with a letter [1]. The package name must be unique in the ROS ecosystem. It does not need to be identical with the folder name where it is checked out to, but it is a good habit to use the same name for the folder.

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

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 would have multiple licenses if different source files have different licenses. Every license occurring the 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)

The URL to a website, a bug tracker or anything else for 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 ROS dep key that this package depends on at build-time.

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

<buildtool_depend> (multiple)

Declares a ROS dep key that this package depends on at build-time. But it identifies a tool which is executed during the build process. For cross-compilation it is necessary to distinguish them from normal build dependencies which the package is linked against (they need to be for the target architecture) and tools which are use on the build architecture to compile the package.

<run_depend> (multiple)

Declares a ROS dep key that this package depends on at run-time.

<test_depend> (multiple)

Declares a ROS dep key that this package depends on for running tests.

While build, buildtoold and run define independent sets of dependencies test dependencies are only additive and specify only what is required in addition to the other dependencies.

<conflict> (multiple)

Declares a ROS dep key that this package conflicts with. This package can not be installed at the same time as the conflicting package. This maps to conflicts for both dpkg and rpms.

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

<replace> (multiple)

Declares a ROS dep key that this package replaces. This maps to Replaces for dpkg and Obsoletes for rpms.

<export>

It serves as a container for any kind of additional information various packages and subsystems need to embed to fulfill their goal. To avoid potential collisions packages must use their package name as the tag name inside of the export block. The content of that tag is up to the package to define and utilize.

The existing tags for use cases like exporting plugins for pluginlib etc. will remain as-is.

For example, a package which implements an rviz plugin might include this:

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

The following tags will list some additional tags which are necessary to fulfill specific task in the area of package and message generation. These all belong inside an <export> tag.

<export>
  <deprecated>This package will be removed in ROS Hydro. Instead use
    package FOO which provides similar functionality but 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>

Modification to previous specifications

• Authors are now split into authors and maintainers.

• Multiple persons and their emails are specified in separate tags and attributes.
• Authors are now optional.
• Maintainers must have an email.
• At least one maintainer is now required.

• Multiple licenses can now be used (even if a single license per package is desired).
• Multiple url tags can be specified and the type attributes gives them semantic meaning.
• The former depend and rosdep have been unified, but also split into various types of dependencies.
• The export tag:

• The cpp tag has been dropped, since this functionality is handled by catkin.
• The roslang tag has been dropped, since this functionality is handled by catkin.

• The copyright tag has been dropped.
• The logo tag has been dropped.
• The review tag has been dropped, these information will be stored on the website of that package.
• The versioncontrol tag has been dropped.

Backwards Compatibility

All tools currently utilizing stack.xml and manifest.xml are updated to work with package.xml files.

The update of existing stacks and packages only effect catkin-ized packages. The existing dry packages stay as-is. Rosdep will be able to distinguish between wet and dry and return the appropriate system dependencies.

For backward compatibility with dry packages catkin will generate a manifest.xml which provides information necessary for rosbuild to work (namely exporting compiler and linker flags).

Future enhancements

Additional meta information can be easily added within the export tag in the future if necessary.

Furthermore new features related to the infrastructure can be specified and integrated using additional tags and attributes:

Affected tools

List of tools affected by the specification (which is very like not complete):

• bloom
• buildfarm
• catkin
• roscd
• rosdep
• rosdoc
• roslaunch
• roslib
• rospack
• rospkg
• rosrun
• rosstack

Several tools are affected by the transition from packaging packages instead of stacks and not really by the specification of the format for the package information.