REP: 140 Title: Package Manifest Format Two Specification Author: Dirk Thomas, Jack O'Quin Status: Draft Type: Standards Track Content-Type: text/x-rst Created: 26-Jun-2013
This REP specifies the second package.xml format, replacing the
one specified in REP-0127 [1]. It is relevant for packages using the
catkin build system.
Overall, the initial package definition worked well. Hundreds of packages were converted from rosbuild to catkin using that interface. But, experience has revealed some areas which need to be improved.
The biggest problem was user confusion due to the two meanings of the
<run_depend> tag. Replacing it with <exec_depend> and
<build_export_depend> makes the semantics of both types much clearer.
A lesser issue was the need to declare most ROS package dependencies
twice, using both <run_depend> and <build_depend>. To aleviate this
redundancy the <depend> tag was introduced.
Also, as use of the package format has matured, the need has arrisen for
some additional dependency tag types, e.g. <doc_depend>. Additionally,
the <test_depend> tag's semantics is changed such that you do not have
to additionally list it as a <build_depend> tag.
REP-0127 [1] provides the basic package.xml design rationale,
which is not repeated here.
The <run_depend> tag generated considerable confusion within the
ROS user and developer community [3]. Everyone understood that
it was needed when a package required another to be available at
execution-time. But, most people did not grasp the subtle transitive
build-time dependency introduced when a header exported by a package
included one from some other package. In that case, the required
<run_depend> tag name was quite misleading.
Creating specific tags for those two different meanings reduces
confusion, and improves packaging efficiency because
<build_export_depend> normally resolves to a development package, while
<exec_depend> generally refers to an execution-time binary package [8].
Although most existing ROS components are not divided into development
and execution-time packages, many system dependencies are separated in
that way. The new tags can take advantage of that immediately.
With the new tags defined, <run_depend> was no longer needed.
Removing it draws attention to the former confusion and helps resolve
it correctly. When each package is upgraded from format one to this
new specification, <run_depend> must be converted to one or both
of the new tags, as appropriate.
Very few ROS packages have been split into separate development and
execution-time packages. So, most ROS package dependencies must repeat the
same name in several tags, typically <build_depend> and
<run_depend>. With <run_depend> now divided into
<build_export_depend> and <exec_depend>, that problem gets worse.
The <depend> tag eliminates the repetition, combining all those
dependencies into one [3]. While <depend> can be misused [6],
it is good to have when appropriate.
Formerly, catkin unit tests were not cleanly separated from the rest of the package. There are sometimes reasons to build a package without its tests or their dependencies. For generated Debian or RPM packages they would not run anyway, and should not be installed. When building from source for small embedded systems, disabling the tests reduces the number of dependencies which must also be built and installed.
The solution adopted introduces two CMake configuration variables:
CATKIN_ENABLE_TESTINGcontrols whether the tests will be built. Packages should test this variable within theirCMakeLists.txt, to ensure that no test artifacts are configured or built, unless enabled.CATKIN_SKIP_TESTINGcan be used to build without tests even for packages created beforeCATKIN_ENABLE_TESTINGbecame available. This option does not build as efficiently, and may display warning messages during the build. It is a migration aid, for use while packages are being upgraded to explicitly enable and disable testing themselves.
With format one, <test_depend> could not co-exist with other types
of dependencies, nor could testing-only packages provide any build or
configuration information.
For example, rostest defines an add_rostest() CMake command.
Using it required a <build_depend>rostest</build_depend>, even
though it was only needed when testing is enabled. Even worse, also
declaring <test_depend>rostest</test_depend> was considered an
error.
With format two, a <test_depend> for rostest works as expected, no
separate <build_depend> is required in that case. Moreover,
packages needed for several reasons may now be declared using any
desired combination of dependency types, including <test_depend>.
The package manifest is an XML file, with restricted syntax.
The only top-level element allowed is <package>. Immediately
subordinate to that are several required or optional elements, defined
here. No other tags are permitted directly under the <package>
element.
The <package> tag is the unique top-level tag in a package.xml
file. All other tags are nested under it.
format="NUMBER"Specifying the
package.xmlformat being used. If not set,format="1"would be assumed, which is not the format described here. For this interface, you must specifyformat="2". If you are using a different format, please refer to the relevant specification. REP-0127 [1] described format one.
The required tags in a package.xml file provide package meta-data:
Optional, but recommended, meta-data include the names of the original authors and links to support documentation.
The dependencies and relations to other packages and system packages have been discussed in [7]. They are described using:
These dependency tags are used with both system packages and ROS packages. For system dependencies specify the rosdep key name, for ROS dependencies use the package name.
The dependency graph must be acyclic. No package may directly or indirectly depend on itself.
There is a need for additional meta-data in the manifest for other tools that work with packages, like message generators and plugin discovery. Tags for that kind of information are wrapped within this tag:
Some <export> tags used by catkin are defined below. Others are
defined by various tools, which must specify their own specific tag
structures.
<package format="2">
<name>my_package</name>
<version>1.2.3</version>
<description>
This is my package's description.
</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="repository">http://www.github.com/my_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>
<depend>roscpp</depend>
<build_depend>libgstreamer0.10-dev</build_depend>
<build_export_depend>libgstreamer0.10-dev</build_export_depend>
<exec_depend>libgstreamer0.10-0</exec_depend>
<test_depend>gtest</test_depend>
<doc_depend>doxygen</doc_depend>
<conflict>alternative_implementation</conflict>
<replace>my_old_package</replace>
<export>
...
</export>
</package>
The package name must start with a letter and contain only lowercase alphabetic, numeric or underscore characters [2]. 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 version number of the package in the format MAJOR.MINOR.PATCH
where each part is numeric only.
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.
The name of the person maintaining the package. All packages require a maintainer. For orphaned packages see below.
email="name@domain.tld"(required)Email address of the maintainer.
An orphaned package is one with no current maintainer. Orphaned
packages should have their maintainer set to ROS Community
<ros-release@code.ros.org>. These packages will be maintained by
the ROS Community as a whole until a volunteer takes over maintenance.
<maintainer email="ros-release@code.ros.org">ROS Community</maintainer>
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
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.
type="TYPE"(optional)The type should be one of the following identifiers:
website(default),bugtrackerorrepository.
The name of a person who is an author of the package, as acknowledgement of their work and for questions.
email="name@domain.tld"(optional)Email address of author.
Declares a rosdep key or ROS package name that this package requires
at build-time. For system packages, the rosdep key will normally
specify the "development" package, which frequently ends in "-dev".
The build and buildtool dependencies are used to determine
the build order of multiple packages.
All dependencies and relationships may restrict their applicability to particular versions. For each comparison operator an attribute can be used. Two of these attributes can be used together to describe a version range.
version_lt="VERSION"(optional)The dependency to the package is restricted to versions less than the stated version number.
version_lte="VERSION"(optional)The dependency to the package is restricted to versions less or equal than the stated version number.
version_eq="VERSION"(optional)The dependency to the package is restricted to a version equal than the stated version number.
version_gte="VERSION"(optional)The dependency to the package is restricted to versions greater or equal than the stated version number.
version_gt="VERSION"(optional)The dependency to the package is restricted to versions greater than the stated version number.
Declares a rosdep key or ROS package name that this package needs as
part of some build interface it exports. For system packages, the
rosdep key will normally specify the "development" package, which
frequently ends in "-dev".
The <build_export_depend> declares a transitive build dependency. 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.
The same attributes as for <build_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. For system packages, the rosdep key will normally
specify the "development" package, which frequently ends in
"-dev".
The same attributes as for <build_depend> (multiple).
Declares a rosdep key or ROS package name that this package exports which must be compiled and run on the build system, not the target system. For cross-compilation, one must distinguish these from target build dependencies, which may be linked with your package and must be compiled for the target architecture.
The same attributes as for <build_depend> (multiple).
Declares a rosdep key or ROS package name that this package needs at
execution-time. For system packages, the rosdep key will normally
not specify the "development" package, so it will generally lack the
"-dev" suffix.
The <exec_depend> is needed for packages providing shared
libraries, executable commands, Python modules, launch scripts or any
other files required for running your package. It is also used by
metapackages for grouping packages.
The same attributes as for <build_depend> (multiple).
Declares a rosdep key or ROS package name that this package needs for
multiple reasons. A <depend> tag is equivalent to specifying
<build_depend>, <build_export_depend> and <exec_depend>,
all on the same package.
The same attributes as for <build_depend> (multiple).
Declares a rosdep key or ROS package name that your package needs for
building its documentation. A <doc_depend> may reference a
package also declared as some other type of dependency.
Documentation will be built if the CMake variable
CATKIN_ENABLE_DOC is set to 1, as it is by default. When
building documentation is enabled, the <doc_depend> packages are
available for configuring and building it. Generated Debian packages
are built without documentation or its dependencies.
The same attributes as for <build_depend> (multiple).
Declares a rosdep key or ROS package name that your package needs
for running its unit tests. A <test_depend> may reference a
package also declared as some other type of dependency.
All tests and their dependencies will be built if the CMake variables
CATKIN_ENABLE_TESTING=1 and CATKIN_SKIP_TESTING=0, the default
settings. CMakeLists.txt should only define its test targets when
CATKIN_ENABLE_TESTING=1 [9].
When building with testing enabled, the <test_depend> packages are
available for configuring and building the tests as well as running
them. Generated Debian packages are built without the unit tests or
their dependencies.
The same attributes as for <build_depend> (multiple).
Declares a rosdep key or ROS package name with which your package
conflicts. This package and the conflicting package should not be
installed at the same time. This has no effect on source builds, but
maps to Conflicts when creating Debian or RPM packages.
For a detailed explanation how these relationships are used see [4] and [5].
The same attributes as for <build_depend> (multiple).
Declares a rosdep key or ROS package name that your package replaces.
This has no effect on source builds, but maps to Replaces when
creating Debian packages and Obsoletes for RPM packages.
The same attributes as for <build_depend> (multiple).
This tag serves as a container for additional information various packages and subsystems need to embed. To avoid potential collisions, an export tag should have the same name as the package which is meant to process it. 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.
This empty tag indicates that your package contains no architecture-specific files. That information is intended for possible future use, the current ROS packaging tools and build farm ignore it.
Specifying <architecture_independent/> is recommended for
metapackages and for packages defining only ROS messages and services.
Python-only packages are reasonable candidates, too.
Be sure to remove this tag if some subsequent update adds architecture-dependent targets to a formerly independent package.
Various tools use this tag to determine how to handle a package. It was defined in REP-0134 [10], which currently specifies only two valid values:
<build_type>catkin</build_type> <build_type>cmake</build_type>
If no <build_type> is provided, catkin is assumed.
When the build type is cmake, the package is handled as a
non-catkin CMake project. It cannot be included in a normal catkin
workspace, but can instead use catkin_make_isolated, which
configures and builds a different kind of workspace in which
cmake, make, and make install are invoked separately for
each package. See REP-0134 for details.
Further build types may eventually be defined, such as: "make", "autotools", "rosbuild", or "custom".
This tag indicates that your package is deprecated, enabling tools to notify users about that fact. The tag may be empty or may optionally contain an arbitrary text providing user more information about the deprecation:
<export>
<deprecated>
This package will be removed in ROS Indigo. Instead, use package
FOO, which provides similar features with a different API.
</deprecated>
</export>
The content defines the identifier for the language bindings
generated by this package, i.e. in gencpp this is set to cpp:
<export> <message_generator>cpp</message_generator> </export>
This empty tag declares a special kind of catkin package used for
grouping other packages. Metapackages only provide execution-time
dependencies. They cannot be used for catkin builds and compile
nothing themselves. Metapackages may not install any code or other
files, although package.xml does get installed automatically.
They can depend on other metapackages, but regular catkin packages
cannot.
A good use for metapackages is to group the major components of your
robot and then provide a comprehensive grouping for your whole system.
Package installation tools like apt-get or yum can
automatically install all the packages on which a metapackage directly
or indirectly depends. Metapackages can also be used to resolve
dependencies declared by legacy rosbuild stacks not yet converted to
catkin.
Every metapackage must have a CMakeLists.txt containing these
commands:
cmake_minimum_required(VERSION 2.8.3) project(PACKAGE_NAME) find_package(catkin REQUIRED) catkin_metapackage()
Because the metapackage CMakeLists.txt contains a catkin macro,
its package.xml must declare a buildtool dependency on catkin:
<buildtool_depend>catkin</buildtool_depend>
Additional buildtool, build or test dependencies are not permitted.
Because metapackages only supply execution-time dependencies, they use
<exec_depend> to list the packages in their group:
<exec_depend>your_custom_msgs</exec_depend> <exec_depend>your_server_node</exec_depend> <exec_depend>your_utils</exec_depend> <exec_depend>another_metapackage</exec_depend>
<run_depend>was replaced by<build_export_depend>and<exec_depend>.<depend>was added as a synonym for<build_depend>,<build_export_depend>and<exec_depend>.<test_depend>now fulfills configuration and build-time test requirements in addition to the objects needed for running them.
Format one packages following REP-0127 [1] are not affected unless
they are updated to declare <package format="2">, at which time
all <run_depend> elements must be removed and replaced with other
appropriate dependencies.
| [1] | (1, 2, 3, 4) REP-0127 (http://ros.org/reps/rep-0127) |
| [2] | ROS naming conventions (http://www.ros.org/wiki/ROS/Patterns/Conventions#Naming_ROS_Resources) |
| [3] | (1, 2) ros-infrastructure/catkin_pkg#43: "add support for depend tag" |
| [4] | Declaring relationships between packages (Debian Policy Manual) (http://www.debian.org/doc/debian-policy/ch-relationships.html) |
| [5] | Advanced RPM Packaging (Fedora Documentation) (http://docs.fedoraproject.org/en-US/Fedora_Draft_Documentation/0.1/html/RPM_Guide/ch-advanced-packaging.html) |
| [6] | Buildsystem mailing list discussion: "adding <depend> syntax to package.xml" |
| [7] | Buildsystem mailing list discussion: "Dependency tag types for REP 127" |
| [8] | Buildsystem mailing list discussion: "dev/non-dev packages and required meta information" |
| [9] | Buildsystem mailing list discussion: "REP-0140: internal review" |
| [10] | REP-0134 (http://ros.org/reps/rep-0134) |
This document has been placed in the public domain.