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).
The format of package.xml is straightforward.
Each package.xml file has the <package> tag as the root tag in the document.
There are a minimal set of tags that need to be nested within the <package> tag to make the package manifest complete.
<name> - The name of the package
<version> - The version number of the package (required to be 3 dot-separated integers)
<description> - A description of the package contents
<maintainer> - The name of the person(s) that is/are maintaining the package
<license> - The software license(s) (e.g. GPL, BSD, ASL) under which the code is released.
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="email@example.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:
Build Tool Dependencies specify build system tools which this package needs to build itself. Typically the only build tool needed is catkin. In a cross-compilation scenario build tool dependencies are for the architecture on which the compilation is performed.
Build Dependencies specify which packages are needed to build this package. This is the case when any file from these packages is required at build time. This can be including headers from these packages at compilation time, linking against libraries from these packages or requiring any other resource at build time (especially when these packages are find_package()-ed in CMake). In a cross-compilation scenario build dependencies are for the targeted architecture.
Run Dependencies specify which packages are needed to run code in this package, or build libraries against this package. This is the case when you depend on shared libraries or transitively include their headers in public headers in this package (especially when these packages are declared as (CATKIN_)DEPENDS in catkin_package() in CMake).
Test Dependencies specify only additional dependencies for unit tests. They should never duplicate any dependencies already mentioned as build or run 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="firstname.lastname@example.org">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="email@example.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.
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:
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.
<url> - A URL for information on the package, typically a wiki page on ros.org.
<author> - The author(s) of the package
For more info see http://ros.org/reps/rep-0127.html