From aa729dc344bde1f50c7ac291bbe5047ceb54ba76 Mon Sep 17 00:00:00 2001 From: Dirk Thomas Date: Tue, 10 Oct 2017 11:54:34 -0700 Subject: [PATCH] add draft for REP 149: Package Manifest Format Three Specification --- rep-0149.rst | 967 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 967 insertions(+) create mode 100644 rep-0149.rst diff --git a/rep-0149.rst b/rep-0149.rst new file mode 100644 index 00000000..d4c6c861 --- /dev/null +++ b/rep-0149.rst @@ -0,0 +1,967 @@ +REP: 149 +Title: Package Manifest Format Three Specification +Author: Dirk Thomas +Status: Draft +Type: Standards Track +Content-Type: text/x-rst +Created: 11-Oct-2017 + +Outline +======= + +#. Abstract_ +#. Motivation_ +#. Rationale_ +#. `Data Representation`_ +#. Compatibility_ +#. Schema_ +#. References_ +#. Copyright_ + +.. raw:: html + + The current draft highlights significant changes compared to REP-0140 [2]_ + in red. + Trivial changes appear in green. + + +Abstract +======== + +.. raw:: html + + + +This REP specifies the third ``package.xml`` format, replacing the ones +specified in REP-0127 [1]_ and REP-0140 [2]_. +It is relevant for packages using the catkin as well as the ament build system. + +.. raw:: html + + + + +Motivation +========== + +.. raw:: html + + + +* Dependency groups + +* ABI version on the package level + +* Considerations for specifying dependencies for packages which are used in ROS 1 as well as ROS 2 + +.. raw:: html + + + + +Rationale +========= + +.. raw:: html + + + +REP-0127 [1]_ and REP-0140 [1]_ provide the ``package.xml`` design rationale +for format one and two, which is not repeated here. + +.. raw:: html + + + +.. raw:: html + + + +Adding <\*group_depend> +----------------------- + +Creating specific tags for the group dependencies was chosen over +distinguishing them from existing tags using an attribute. +Since the API in e.g. ``catkin_pkg`` is closely following the XML structure +using an attribute would have made the API more complicated and potentially +changed the sematic of code using the existing dependencies. +In order to support dependency group existing code needs to be extended +anyway, therefore exposing new members / tags is straight forward. + +The content of the group dependency tag is the name of the group. +Leading and trailing whitespace is being ignore from the name and for +consistency it is recommended to following the naming rules for packages. + +There are different criteria for when a group dependency is being satisfied: + +* either all members of the group need to be available +* or at least one member of the group needs to be available + +ABI version attribute +--------------------- + +Dependencies across ROS 1 and ROS 2 +----------------------------------- + +.. raw:: html + + + + +Data Representation +=================== + +The package manifest is an XML file, with restricted syntax. + +The only top-level element allowed is ````. Immediately +subordinate to that are several required or optional elements, defined +here. No other tags are permitted directly under the ```` +element. + +.. raw:: html + + + + +-------------------- + +The ```` tag is the unique top-level tag in a ``package.xml`` +file. All other tags are nested under it. + +.. raw:: html + + + +Attributes +'''''''''' + + ``format="NUMBER"`` + + Specifying the ``package.xml`` format being used. If not set, + ``format="1"`` would be assumed, which is *not* the format described + here. For this interface, you *must* specify ``format="3"``. If + you are using a different format, please refer to the relevant + specification. REP-0127 [1]_ described format one, REP-0140 [12]_ format two. + + .. raw:: html + + + + ``abi_version="MAJOR.MINOR.PATCH"`` + + Specifying the version the package is ABI compatible with. + If not set, the same value as specified in the ``version`` tag is assumed. + + .. raw:: html + + + +Required Tags +------------- + +The required tags in a ``package.xml`` file provide package meta-data: + + * `\`_ + * `\`_ + * `\`_ + * `\ (multiple, but at least one)`_ + * `\ (multiple, but at least one)`_ + +Optional Tags +------------- + +Meta-information +'''''''''''''''' + +Optional, but recommended, meta-data include the names of the original +authors and links to support documentation. + + * `\ (multiple)`_ + * `\ (multiple)`_ + +Dependencies +'''''''''''' + +The dependencies and relations to other packages and system packages +have been discussed in [7]_. They are described using: + + * `\ (multiple)`_ + * `\ (multiple)`_ + * `\ (multiple)`_ + * `\ (multiple)`_ + * `\ (multiple)`_ + * `\ (multiple)`_ + * `\ (multiple)`_ + * `\ (multiple)`_ + * `\ (multiple)`_ + * `\ (multiple)`_ + +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. + +.. raw:: html + + + +Group dependencies +'''''''''''''''''' + +For every dependency tag there is a corresponding group dependency tag, +except for ``conflict`` and ``replace``: + + * `\ (multiple)`_ + * `\ (multiple)`_ + * `\ (multiple)`_ + * `\ (multiple)`_ + * `\ (multiple)`_ + * `\ (multiple)`_ + * `\ (multiple)`_ + * `\ (multiple)`_ + +.. raw:: html + + + +Various +''''''' + +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 ```` tags used by catkin are defined below. Others are +defined by various tools, which must specify their own specific tag +structures. + +Example +------- + +:: + + + my_package + 1.2.3 + + This is my package's description. + + Someone + + BSD + LGPL + + http://wiki.ros.org/my_package + http://www.github.com/my_org/my_package + http://www.github.com/my_org/my_package/issues + John Doe + Jane Doe + + catkin + genmsg + + roscpp + + libgstreamer0.10-dev + libgstreamer0.10-dev + libgstreamer0.10-0 + + gtest + + doxygen + + alternative_implementation + + my_old_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 following recommended exemptions apply, which are optional for +implementations: + +- Dashes may be permitted in package names. This is to support + maintaining a consistent dependency name when transitioning back + and forth between a system dependency and in-workspace package, + since many rosdep keys contain dashes (inherited from the + Debian/Ubuntu name). +- In support of some legacy packages, capital letters may also be + accepted in the package name, with a validation warning. + + + +--------- + +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. + + + (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="name@domain.tld"`` *(required)* + + Email address of the maintainer. + +An orphaned package is one with no current maintainer. +Orphaned packages should use the following maintainer information to +guide volunteers how they can claim maintainership: + +Example +''''''' + +:: + + Unmaintained see http://wiki.ros.org/MaintenanceGuide#Claiming_Maintainership + + + (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 +will have multiple licenses if different source files have different +licenses. Every license occurring in the source files should have +a corresponding ```` tag. For any explanatory text about +licensing caveats, please use the ```` 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 + + (multiple) +---------------- + +A Uniform Resource Locator for the package's website, bug tracker or +source repository. + +It is a good idea to include ```` 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. + +Attributes +'''''''''' + + ``type="TYPE"`` *(optional)* + + The type should be one of the following identifiers: ``website`` + (default), ``bugtracker`` or ``repository``. + + + (multiple) +------------------- + +The name of a person who is an author of the package, as +acknowledgement of their work and for questions. + +Attributes +'''''''''' + + ``email="name@domain.tld"`` *(optional)* + + Email address of author. + + +Dependency tags +--------------- + + (multiple) +''''''''''''''''''''''''' + +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. + +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 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. + + + (multiple) +'''''''''''''''''''''''''''''''' + +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 ```` 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. + +Attributes +.......... + + The same attributes as for `\ (multiple)`_. + + + (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"``. + + +Attributes +.......... + + The same attributes as for `\ (multiple)`_. + + + (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. + + +Attributes +.......... + + The same attributes as for `\ (multiple)`_. + + + (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 ```` 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. + +Attributes +.......... + + The same attributes as for `\ (multiple)`_. + + + (multiple) +''''''''''''''''''' + +Declares a rosdep key or ROS package name that this package needs for +multiple reasons. A ```` tag is equivalent to specifying +````, ```` and ````, +all on the same package or key. The ```` tag cannot be used +in combination with any of the three equivalent tags for the same +package or key name. + +Attributes +.......... + + The same attributes as for `\ (multiple)`_. + + + (multiple) +''''''''''''''''''''''' + +Declares a rosdep key or ROS package name that your package needs for +building its documentation. A ```` *may* reference a +package also declared as some other type of dependency. + +The current version of the buildsystem does not provide any +documentation specific functionality or targets but may do so in the +future, similar to how the unit tests are integrated into the configure +and make steps. Other infrastructure (like the documentation jobs on +the buildfarm) will utilize these additional doc dependencies. + +Generated Debian packages are built without the documentation or the +documentation dependencies. + +Attributes +.......... + + The same attributes as for `\ (multiple)`_. + + + (multiple) +'''''''''''''''''''''''' + +Declares a rosdep key or ROS package name that your package needs +for running its unit tests. A ```` *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 ```` 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. + +Attributes +.......... + + The same attributes as for `\ (multiple)`_. + + + (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]_. + +Attributes +.......... + + The same attributes as for `\ (multiple)`_. + + + (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. + +Attributes +.......... + + The same attributes as for `\ (multiple)`_. + + +Group dependency tags +--------------------- + +.. raw:: html + + + + (multiple) +''''''''''''''''''''''''''''''' + +Declares a group name that this package requires at build-time. + + +Attributes +.......... + + ``satisfy="TYPE"`` *(optional)* + + The type should be one of the following identifiers: ``all`` + (default) or ``any``. + + + (multiple) +'''''''''''''''''''''''''''''''''''''' + +Declares a group dependency with a semantic similar to +`\ (multiple)`_. + +Attributes +.......... + + The same attributes as for `\ (multiple)`_. + + + (multiple) +''''''''''''''''''''''''''''''''''' + +Declares a group dependency with a semantic similar to +`\ (multiple)`_. + +Attributes +.......... + + The same attributes as for `\ (multiple)`_. + + + (multiple) +'''''''''''''''''''''''''''''''''''''''''' + +Declares a group dependency with a semantic similar to +`\ (multiple)`_. + +Attributes +.......... + + The same attributes as for `\ (multiple)`_. + + + (multiple) +'''''''''''''''''''''''''''''' + +Declares a group dependency with a semantic similar to +`\ (multiple)`_. + +Attributes +.......... + + The same attributes as for `\ (multiple)`_. + + + (multiple) +''''''''''''''''''''''''' + +Declares a group dependency with a semantic similar to +`\ (multiple)`_. + +Attributes +.......... + + The same attributes as for `\ (multiple)`_. + + + (multiple) +''''''''''''''''''''''''''''' + +Declares a group dependency with a semantic similar to +`\ (multiple)`_. + +Attributes +.......... + + The same attributes as for `\ (multiple)`_. + + + (multiple) +'''''''''''''''''''''''''''''' + +Declares a group dependency with a semantic similar to +`\ (multiple)`_. + +Attributes +.......... + + The same attributes as for `\ (multiple)`_. + +.. raw:: html + + + + + +-------- + +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:: + + + + + +The following are some tags used within an ```` for various +package and message generation tasks. + + +''''''''''''''''''''''''''' + +This empty tag indicates that your package produces no +architecture-specific files once built. +That information is intended for allowing optimization of packaging. + +Specifying ```` is recommended for +metapackages and for packages defining only ROS messages and services. +Python-only packages are reasonable candidates, too. +It is not appropriate for any package which compiles C or C++ code. + +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:: + + catkin + cmake + +If no ```` 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:: + + + + This package will be removed in ROS Hydro. Instead, use package + FOO, which provides similar features with a different API. + + + + +''''''''''''''''''' + +The content defines the *identifier* for the language bindings +generated by this package, i.e. in ``gencpp`` this is set to ``cpp``:: + + + cpp + + + +'''''''''''''' + +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:: + + catkin + +Additional buildtool, build or test dependencies are not permitted. + +Because metapackages only supply execution-time dependencies, they use +```` to list the packages in their group:: + + your_custom_msgs + your_server_node + your_utils + another_metapackage + +.. raw:: html + + + + (multiple) +'''''''''''''''''''''''''''' + +The content identifies the name of the dependency group:: + + + message_packages + + +.. raw:: html + + + + +Compatibility +============= + +.. raw:: html + + + +Support for format three +------------------------ + +Existing tools supporting up to format two will need to be updated to +honor the new information provided by format three. +If they are not checking that the format is two or lower they will +simply ignore the format three specific information when processing a +package with a format three manifest. + +Backward compatibility +---------------------- + +Format one or two packages following REP-0127 [1]_ or REP-0140 [12]_ are +not affected unless they are updated to declare ````. + +Since format three only adds new functionality and doesn't modify any +existing markup a migration to format three only makes sense when the +package wants to use any of the new features. + +.. raw:: html + + + + +.. raw:: html + + + +Schema +====== + +A schema defining the structure specified in this document is available +at [11]_. +To specify the schema within a manifest you can reference a self +contained schema file like this: + + + + + +.. raw:: html + + + + +References +========== + +.. [1] REP-0127 + (http://ros.org/reps/rep-0127) +.. [2] ROS naming conventions + (http://www.ros.org/wiki/ROS/Patterns/Conventions#Naming_ROS_Resources) +.. [3] 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 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) +.. [11] Schema file + (https://github.com/ros-infrastructure/rep/blob/master/xsd/package_format3.xsd) +.. [12] REP-0140 + (http://ros.org/reps/rep-0140) + + +Copyright +========= + +This document has been placed in the public domain. + + + +.. + Local Variables: + mode: indented-text + indent-tabs-mode: nil + sentence-end-double-space: t + fill-column: 70 + coding: utf-8 + End: