[Documentation] [TitleIndex] [WordIndex

Overview

The package manifest is an XML file called package.xml that must be included with any catkin-compliant package's root folder. This file defines properties about the package such as the package name, version numbers, authors, maintainers, and dependencies on other catkin packages. Note the concept is similar to the manifest.xml file used in the legacy rosbuild build system.

Your system package dependencies are declared in package.xml. If they are missing or incorrect, you may be able to build from source and run tests on your own machine, but your package will not work correctly when released to the ROS community. Others depend on this information to install the software they need for using your package (excepted from task-oriented doc for catkin at U-Texas).

Format 2 (Recommended)

This is the recommended format for new packages. It is also recommended that older format 1 packages be migrated to format 2. For instructions on migrating from format 1 to format 2, see Migrating from Format 1 to Format 2 in the catkin API docs.

The full documentation for format 2 can be found in the catkin API docs. More information can be found in REP 140 -- Package Manifest Format Two Specification.

Basic Structure

Each package.xml file has the <package> tag as the root tag in the document.

<package format="2">

</package>

Required Tags

There are a minimal set of tags that need to be nested within the <package> tag to make the package manifest complete.

As an example, here is package manifest for a fictional package called foo_core.

<package format="2">
  <name>foo_core</name>
  <version>1.2.4</version>
  <description>
  This package provides foo capability.
  </description>
  <maintainer email="ivana@osrf.org">Ivana Bildbotz</maintainer>
  <license>BSD</license>
</package>

Dependencies

The package manifest with minimal tags does not specify any dependencies on other packages. Packages can have six types of dependencies:

These six types of dependencies are specified using the following respective tags:

All packages have at least one dependency, a build tool dependency on catkin as the following example shows.

<package format="2">
  <name>foo_core</name>
  <version>1.2.4</version>
  <description>
    This package provides foo capability.
  </description>
  <maintainer email="ivana@osrf.org">Ivana Bildbotz</maintainer>
  <license>BSD</license>

  <buildtool_depend>catkin</buildtool_depend>
</package>

A more realistic example that specifies build, exec, test, and doc dependencies could look as follows.

<package format="2">
  <name>foo_core</name>
  <version>1.2.4</version>
  <description>
    This package provides foo capability.
  </description>
  <maintainer email="ivana@willowgarage.com">Ivana Bildbotz</maintainer>
  <license>BSD</license>

  <url>http://ros.org/wiki/foo_core</url>
  <author>Ivana Bildbotz</author>

  <buildtool_depend>catkin</buildtool_depend>

  <depend>roscpp</depend>
  <depend>std_msgs</depend>

  <build_depend>message_generation</build_depend>

  <exec_depend>message_runtime</exec_depend>
  <exec_depend>rospy</exec_depend>

  <test_depend>python-mock</test_depend>

  <doc_depend>doxygen</doc_depend>
</package>

More details on dependencies can be found in the catkin API docs here.

Metapackages

It is often convenient to group multiple packages as a single logical package. This can be accomplished through metapackages. A metapackage is a normal package with the following export tag in the package.xml:

 <export>
   <metapackage />
 </export>

Other than a required <buildtool_depends> dependency on catkin, metapackages can only have execution dependencies on packages of which they group.

Additionally a metapackage has a required, boilerplate CMakeLists.txt file:

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

Note: replace <PACKAGE_NAME> with the name of the metapackage.

Additional Tags

Format 1 (Legacy)

Older catkin pakages use format 1. If the <package> tag has no format attribute, it is a format 1 package. Use format 2 for new packages.

The format of package.xml is straightforward.

Basic Structure

Each package.xml file has the <package> tag as the root tag in the document.

<package>

</package>

Required Tags

There are a minimal set of tags that need to be nested within the <package> tag to make the package manifest complete.

As an example, here is package manifest for a fictional package called foo_core.

<package>
  <name>foo_core</name>
  <version>1.2.4</version>
  <description>
  This package provides foo capability.
  </description>
  <maintainer email="ivana@willowgarage.com">Ivana Bildbotz</maintainer>
  <license>BSD</license>
</package>

Build, Run, and Test Dependencies

The package manifest with minimal tags does not specify any dependencies on other packages. Packages can have four types of dependencies:

These four types of dependencies are specified using the following respective tags:

All packages have at least one dependency, a build tool dependency on catkin as the following example shows.

<package>
  <name>foo_core</name>
  <version>1.2.4</version>
  <description>
    This package provides foo capability.
  </description>
  <maintainer email="ivana@willowgarage.com">Ivana Bildbotz</maintainer>
  <license>BSD</license>

  <buildtool_depend>catkin</buildtool_depend>
</package>

A more realistic example that specifies build, runtime, and test dependencies could look as follows.

<package>
  <name>foo_core</name>
  <version>1.2.4</version>
  <description>
    This package provides foo capability.
  </description>
  <maintainer email="ivana@willowgarage.com">Ivana Bildbotz</maintainer>
  <license>BSD</license>

  <url>http://ros.org/wiki/foo_core</url>
  <author>Ivana Bildbotz</author>

  <buildtool_depend>catkin</buildtool_depend>

  <build_depend>message_generation</build_depend>
  <build_depend>roscpp</build_depend>
  <build_depend>std_msgs</build_depend>

  <run_depend>message_runtime</run_depend>
  <run_depend>roscpp</run_depend>
  <run_depend>rospy</run_depend>
  <run_depend>std_msgs</run_depend>

  <test_depend>python-mock</test_depend>
</package>

More details on dependencies can be found here.

Metapackages

It is often convenient to group multiple packages as a single logical package. This can be accomplished through metapackages. A metapackage is a normal package with the following export tag in the package.xml:

 <export>
   <metapackage />
 </export>

Other than a required <buildtool_depends> dependency on catkin, metapackages can only have run dependencies on packages of which they group.

Additionally a metapackage has a required, boilerplate CMakeLists.txt file:

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

Note: replace <PACKAGE_NAME> with the name of the metapackage.

Metapackage now have CMakeLists.txt files after a discussion about installing the package.xml files:

https://groups.google.com/forum/#!msg/ros-sig-buildsystem/mn-VCkl2OHk/dUsHBBjyK30J

So now the package.xml files for metapackages are installed, but the requirement that other packages should not depend on metapackages is still enforced by requiring the users do not deviate from the suggested boilerplate CMakeLists.txt code.

Additional Tags

For more info see http://ros.org/reps/rep-0127.html


2024-02-24 12:28