Skip to content

Latest commit

 

History

History
661 lines (473 loc) · 18.6 KB

rep-0127.rst

File metadata and controls

661 lines (473 loc) · 18.6 KB
Raw

REP: 127 Title: Specification of package manifest format Author: Dirk Thomas Status: Draft Type: Standards Track Content-Type: text/x-rst Created: 12-Sep-2012 Post-History: 22-Sep-2012

Table of Contents

  1. Abstract
  2. Motivation
  3. Rationale
  4. Data
  5. Concerns
  6. Specification
  7. References
  8. Copyright

Abstract

This REP specifies the format for package manifest used starting with Groovy when packages are getting packaged. This is only relevant for packages which use the new buildsystem catkin. The filename is package.xml which will replace stack.xml and manifest.xml.

Motivation

The decision to remove the concept of stacks and therefore package packages [8] suggests that the information contained in the both files stack.xml and manifest.xml should be merged.

The file contains different kind of information:

  • descriptive data (i.e. a description, maintainer)
  • dependencies to other packages and system dependencies
  • meta-information (i.e. the author and website)
  • packaging information (i.e. the version)

Rationale

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

One file per package with all the information

Each package has one package.xml which contains all necessary information (instead of having multiple separate files with semantically grouped informations). This design decision is based on the need to utilize these information in several tools (i.e. buildfarm, wiki) which should only require to fetch one file from a repository.

Catkin-only - no rosbuild information inside

The file only specifies information needed for a ROS ecosystem which is entirely based on catkin. Any additional information necessary for backward compatibility with rosbuild is kept separate (i.e. in the legacy manifest.xml files). This enable to easily remove the legacy files in the future. Legacy files required for rosbuild interaction are fully generated from the new package.xml and the CMakeLists.txt, rather than manually maintained.

Store normalized data

All data is stored in atomic units to enable automated processing. I.e. names and email addresses are not mixed in a single field but stored separately.

Data format

Beside XML (which is used in ROS for stack.xml and manifest.xml) other formats have been considered. Especially yaml has been investigates extensively during the Fuerte cycle. The benchmark results [6] showed that parsing YAML is significantly slower (by a factor of 10). Therefore the format is not changed but will stay XML.

Tags vs. attributes

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

Additional (most times optional) information is stored in attributes of the related tag instead of grouping multiple tags inside a parent tag.

Data

<package>

The <package> tag is the unique top-level tag in a package.xml file. All other tags are nested under this.

Attributes

format="NUMBER" (optional) Specifying the version of the package.xml format being used. If it is not set the default format 1 is assumed. This will be used to detect future specification changes, and thus allow to have one current and several deprecated formats at the same time.

Required Tags

The required set of tags in a package.xml file provides basic meta data about the package:

Optional Tags

Meta information

We strongly recommend the use of the <url> tag to point users to a website and/or bug tracker where they can find more information or give feedback about the package. The website is most commonly a wiki page on ROS.org so that users can easily find and update information about the package.

Furthermore authors can be stated:

Dependencies

The dependencies and relations to other packages and system packages have been discussed in [8] and are described with:

Various

There is a need to store further meta-data in the manifest regarding various other tools that work with packages (message generators, plugin discovery, etc.). All of this dynamic information is stored in tags under a single tag:

Tool providers are responsible for defining the tag structure their tool requires.

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="[email protected]">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="[email protected]">Jane Doe</author>

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

  <build_depend>libboost-thread-dev</build_depend>
  <run_depend>libboost-thread</run_depend>

  <test_depend>gtest</test_depend>

  <conflict>my_old_package</conflict>

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

<name>

The name of the package consisting only of lower case alphanumeric characters and underscores and must start with a letter [1]. The package name must be unique in the ROS ecosystem. It does not need to be identical with the folder name where it is checked out to, but it is a good habit to use the same name for the folder.

Reasons for naming convention

Package names are used in various contexts:
  • namespaces
  • variables
  • part of a binary package name (i.e. Debian, Fedora)

The 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 can only be a letter is derived from the fact that some language do not allow this for namespaces/packages.

<version>

The version number of the package in the format MAJOR.MINOR.PATCH where each part is numeric only.

Attributes

abi="FORMAT-TBD" (optional) Specifying an ABI version number.

The packages generated are version-locked against the exact ABI version of packages it depends on (if not specified the normal version number). When increasing the version number while keeping the same ABI version all dependent packages do not need to be rebuilt.

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

Attributes

email="[email protected]" (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 <[email protected]>. These packages are considered maintained by the ROS Community as a whole until a volunteer takes over maintenance.

Example

::
<maintainer email="[email protected]">ROS Community</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 would have multiple licenses if different source files have different licenses. Every license occurring the 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)

The URL to a website, a bug tracker or anything else for the package.

Attributes

type="TYPE" (optional) The type should be one of the following identifiers: website (default), bugtracker and repository.

<author> (multiple)

The name of a person who is an author of the package, as acknowledgement of their work and for questions.

Attributes

email="[email protected]" (optional)
Email address of author.

<build_depend> (multiple)

Declares a ROS dep key that this package depends on at build-time.

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

Attributes

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 set at the same time 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.

<buildtool_depend> (multiple)

Declares a ROS dep key that this package depends on at build-time. But it identifies a tool which is executed during the build process. For cross-compilation it is necessary to distinguish them from normal build dependencies which the package is linked against (they need to be for the target architecture) and tools which are use on the build architecture to compile the package.

Attributes

The same attributes as for <build_depend> (multiple).

<run_depend> (multiple)

Declares a ROS dep key that this package depends on at run-time.

Attributes

The same attributes as for <build_depend> (multiple).

<test_depend> (multiple)

Declares a ROS dep key that this package depends on for running tests.

While build, buildtoold and run define independent sets of dependencies test dependencies are only additive and specify only what is required in addition to the other dependencies.

Attributes

The same attributes as for <build_depend> (multiple).

<conflict> (multiple)

Declares a ROS dep key that this package conflicts with. This package can not be installed at the same time as the conflicting package. This maps to conflicts for both dpkg and rpms.

For a detailed explanation how these relationships are utilized see [4] and [5].

Attributes

The same attributes as for <build_depend> (multiple).

<replace> (multiple)

Declares a ROS dep key that this package replaces. This maps to Replaces for dpkg and Obsoletes for rpms.

Attributes

The same attributes as for <build_depend> (multiple).

<export>

It serves as a container for any kind of additional information various packages and subsystems need to embed to fulfill their goal. To avoid potential collisions packages must use their package name as the tag name inside of the export block. The content of that tag is up to the package to define and utilize.

The existing tags for use cases like exporting plugins for pluginlib etc. will remain as-is.

For example, a package which implements an rviz plugin might include this:

<export>
  <rviz plugin="${prefix}/plugin_description.xml"/>
</export>

The following tags will list some additional tags which are necessary to fulfill specific task in the area of package and message generation. These all belong inside an <export> tag.

<architecture_independent/>

The empty tag is used to indicate that a package is architecture independent and therefore does not contain any architecture specific code.

<deprecated>

The tag is used to indicate that a package is deprecated which enables to notify users about that fact. The tag may either be empty or optionally contain an arbitrary text content giving the user more information about the deprecation:

<export>
  <deprecated>This package will be removed in ROS Hydro. Instead use
    package FOO which provides similar functionality but with a
    different API.</deprecated>
</export>

<message_generator>

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>

<metapackage/>

The empty tag is used to indicate that a package is a metapackage which implies that it does only have a fixed minimal CMakeLists.txt which will only install the package.xml file. This information is necessary for the ROS wiki to show the relationship between these metapackages and other packages and as a backward compatibility with rosbuild. Non-metapackages must not depend on metapackages but instead on the packages they depend on.

The CMakeLists.txt file for a metapackage is supposed to look like:

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

Concerns

Modification to previous specifications

  • Authors are now split into authors and maintainers.
  • Multiple persons and their emails are specified in separate tags and attributes.
  • Authors are now optional.
  • Maintainers must have an email.
  • At least one maintainer is now required.
  • Multiple licenses can now be used (even if a single license per package is desired).
  • Multiple url tags can be specified and the type attributes gives them semantic meaning.
  • 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, since this functionality is handled by catkin.
  • The roslang tag has been dropped, since this functionality is handled by catkin.
  • The copyright tag has been dropped.
  • The logo tag has been dropped.
  • The review tag has been dropped, these information will be stored on the website of that package.
  • The versioncontrol tag has been dropped.

Backwards Compatibility

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

The update of existing stacks and packages only effect catkin-ized packages. The existing dry packages stay as-is. Rosdep will be able to distinguish between wet and dry and return the appropriate system dependencies.

For backward compatibility with dry packages catkin will generate a manifest.xml which provides information necessary for rosbuild to work (namely exporting compiler and linker flags).

Future enhancements

Additional meta information can be easily added within the export tag in the future if necessary.

Furthermore new features related to the infrastructure can be specified and integrated using additional tags and attributes:

Specification

A schema to validate a package.xml file against will be provided.

Implementation

A reference implementation will be developed as soon as the specification is fixed.

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.

References

[1]Naming conventions (http://www.ros.org/wiki/Naming)
[2]Manifest (http://ros.org/wiki/Manifest)
[3]Stack Manifest (http://www.ros.org/wiki/Stack%20Manifest)
[4]Declaring relationships between packages (Debian Policy Manual) (http://www.debian.org/doc/debian-policy/ch-relationships.html)
[5]Advances RPM Packaging (Fedora Documentation) (http://docs.fedoraproject.org/en-US/Fedora_Draft_Documentation/0.1/html/RPM_Guide/ch-advanced-packaging.html)
[6]Comparison between YAML and XML for manifests (ros/catkin#128)
[7]Discussion on the buildsystem mailing list (https://groups.google.com/forum/?fromgroups=#!topic/ros-sig-buildsystem/_jRvhXFfsVk)
[8](1, 2) Discussion on the buildsystem mailing list (regarding package dependencies and relationships) (https://groups.google.com/forum/?fromgroups=#!topic/ros-sig-buildsystem/fXGSZG0SC08)

Copyright

This document has been placed in the public domain.