Package manifest files

A ROS manifest (manifest.xml) is a minimal specification about a ROS package and supports a wide variety of tools, from compilation to documentation to distribution. In addition to providing a minimal specification of metadata about your package, an important role of manifests is to declare dependencies in a language-neutral and operating-system-neutral manner. The presence of a manifest.xml file in a directory is significant: any directory within your ROS package path that contains a manifest.xml file is considered to be a package (NOTE: packages cannot contain packages).

The bare minimum manifest file is much like a README file, stating who wrote your package and what license it is under. The license is important as packages are means by which ROS code is distributed. The most common manifest files also include <depend> and <export> tags, which help manage the installation and use of a package.

The <depend> tag points to another ROS package that must be installed. It can have a variety of meanings depending on the contents of the package is it pointing to. For example, for rospy code, a depend declares that the other package should be added to the PYTHONPATH. For roslaunch files, a depend may indicate that this package includes roslaunch files from the other package.

The <export> tag describes language-specific build and runtime flags that should be used by any package that depends on your package. For a package containing roscpp code, an export tag may declare header files and libraries that should be picked by any package that depends on it.

See also

rospack

rospack is the main command-line tool for retrieving information about manifests.

Uses

Indexing

If a manifest.xml is present, the directory is assumed to be a ROS package, and the name of the package is the same as the name of the directory. Additionally, properties like the author, license, and description provide important metadata for an indexer.

Documentation

As part of the DRY (Don’t Repeat Yourself) principle, manifest information is oftena automatically imported into documentation, such as header information on ROS.org wiki pages, as well as in Doxygen documentation.

Compilation

The <depend> tags of manifests are used to order ROS packages for compilation. Also, the <export> section of manifests is frequently used by libraries like roscpp and rosjava to export properties to their respective build systems, as well as by rospy to configure PYTHONPATH.

System dependency specification

In addition to declaring dependencies between ROS packages, manifests can declare system dependencies (e.g. on the Boost library). This information is used to release and deploy code to other machines.

XML Reference

Please see the manifest.xml tags reference.

Example

<package>
  <description brief="ROS Python client library">

    <p>
    rospy is a pure Python client library for ROS. The rospy client
    API enables Python programmers to quickly interface with
    ROS <a href="http://ros.org/wiki/Topics">Topics</a>, <a href="http://ros.org/wiki/Services">Services</a>,
    and <a href="http://ros.org/wiki/Parameter Server">Parameters</a>. The
    design of rospy favors implementation speed (i.e. developer time)
    over runtime performance so that algorithms can be quickly
    prototyped and tested within ROS. It is also ideal for
    non-critical-path code, such as configuration and initialization
    code. Many of the ROS tools are written in rospy to take advantage
    of the type introspection capabilities.
    </p>
    <p>
    Many of the ROS tools, such
    as <a href="http://ros.org/wiki/rostopic">rostopic</a>
    and <a href="http://ros.org/wiki/rosservice">rosservice</a>, are
    built on top of rospy.
    </p>

  </description>
  <author>Ken Conley/kwc@willowgarage.com</author>
  <license>BSD</license>
  <review status="Doc reviewed" notes="2010/01/18"/>
  <url>http://ros.org/wiki/rospy</url>
  <depend package="roslib"/>
  <depend package="rosgraph_msgs"/>
  <depend package="std_msgs"/>
  <depend package="roslang"/>
  <export>
    <rosdoc config="rosdoc.yaml"/>
  </export>
</package>

Types of Dependencies

The most common type of dependency that is expressed by a manifest is a dependency on another ROS package, which is expressed by the <depend> tag. As explained earlier, the exact meaning of this dependency depends on the code involved and may either mean a compile-time dependency or runtime dependency.

A manifest can also declare dependencies on thirdparty software provided by the operating system, which is expressed by the <rosdep>. For example, your package may need boost:

<rosdep name="boost" />

By declaring this, users can now use the rosdep tool to install boost. rosdep will examine their operating system, find the appropriate package manager and package name, and install it.

Tools

rospack parses and retrieves information from manifest.xml files. For example, rospack depends package-name will tell you all of the dependencies of package-name (use depends1 to retrieve the direct dependencies).

Library Support

See the rospkg.RosPack and rospkg.RosStack for Python APIs to retrieve and parse manifest files.