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 contents of the xml file.

One file per package with all the information

Each package has one package.xml which contains all necessary data, instead of multiple separate files with semantically grouped information. Several tools, like the buildfarm and the wiki, need to use that information. They only need to fetch one file from each source package.

Store normalized data

All data are stored in atomic units for automated processing. For example, names and email addresses are stored separately.

Data format

Besides XML, which was used for stack.xml and manifest.xml, other formats were considered. YAML was investigated extensively during the Fuerte cycle, because it is easier for humans to read. Since benchmark results [3] showed YAML parsing in Python to be ten times slower, the XML format remains.

Tags versus attributes

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

Additional, mostly optional, information is stored in attributes of the related tag instead of grouping multiple tags inside a parent tag.

XML syntax restrictions

The allowed package.xml elements are tightly restricted. That way, tools can reliably detect errors and provide meaningful error messages should a user misspell any of the tags defined here.

Within the <export> element, tools may define additional tags, free from those restrictions.

If new top-level tags are needed, the format attribute of the <package> tag provides a migration path.

Package name restrictions

Package names are used in various contexts:

• namespaces
• variables
• part of a binary package name (i.e. Debian [4], Fedora [5])

All ROS package names must be mapped to these conventions without generating collision. Therefore only lower case letters (a-z), numbers (0-9) and one delimiting character (_) can be used. The additional restriction that the first character be a letter is due to the requirements of some languages for naming packages or namespaces.

<package>

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

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

  <build_depend>libgstreamer0.10-dev</build_depend>
  <run_depend>libgstreamer0.10-0</run_depend>

  <test_depend>gtest</test_depend>

  <conflict>my_old_package</conflict>

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

<name>

The package name must start with a letter and contain only lowercase alphabetic, numeric or underscore characters [1]. 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.

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

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

<run_depend> (multiple)

Declares a rosdep key or ROS package name that this package needs either at run-time or as part of some exported build interface.

The <run_depend> declares two different types of package dependencies. One is for shared libraries, executables, Python modules, launch scripts and other files required for running your package.

The second type of <run_depend> is for transitive build dependencies. 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.

<test_depend> (multiple)

Declares a rosdep key or ROS package name that your package needs for running its unit tests.

A <test_depend> may not reference any package also declared using a <build_depend>, <buildtool_depend> or <run_depend>.

<conflict> (multiple)

Declares a rosdep key or ROS package name with which your package conflicts. This package and the conflicting package cannot be installed at the same time. This maps to conflicts for both dpkg and rpms.

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 maps to Replaces for dpkg and Obsoletes for rpms.

<export>

This tag serves as a container for additional information various packages and subsystems need to embed. To avoid potential collisions packages must use their package name as their tag name inside the export block. 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.

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

<run_depend>your_custom_msgs</run_depend>
<run_depend>your_server_node</run_depend>
<run_depend>your_utils</run_depend>

Modification to previous specifications

• Authors are now split into authors and maintainers.

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

• Multiple licenses can now be used, even though a single license per package is desired.
• Multiple url tags can be specified with type attributes indicating their meanings.
• 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, it is handled by catkin.
• The roslang tag has been dropped, it is handled by catkin.

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

Backward compatibility

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

Migration to the new format only affects packages being converted to catkin. Existing rosbuild packages remain the same. Rosdep distinguishes between catkin and rosbuild and returns the correct system dependencies.

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.

Future enhancements

Additional meta-information can be added within the export tag, as needed.

New features related to the infrastructure can be specified and integrated using additional tags and attributes, but this requires introducing a new <package> format number.