The package name must start with a letter and contain only lowercase
alphabetic, numeric or underscore characters . 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 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 use the following maintainer information to
guide volunteers how they can claim maintainership:
<maintainer email="ros-orphaned-packages@googlegroups.com">Unmaintained see http://wiki.ros.org/MaintenanceGuide#Claiming_Maintainership</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
file="FILE" (optional)
A path relative to the package.xml file containing the full license text.
Many licenses require including the license text when redistributing the
software.
E.g. the Apache License, Version 2.0 states in paragraph 4.1:
"You must give any other recipients of the Work or Derivative Works a copy of this License"
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.
condition="CONDITION_EXPRESSION"
Every dependency can be conditional on a condition expression.
If the condition expression evaluate to "true" the dependency is being used
and considered as if it doesn't have a condition attribute.
If the condition expression evaluate to "false" the dependency is being
ignored and considered as if it doesn't exist.
The condition expression can consist of:
- parenthesis (which must be balanced)
- logical operators and and or
- comparison operators: ==, !=, <, <=, >, >=
- variable names which start with a $ sign and are followed by
alphanumerics and underscores
- literals which can only contain alphanumerics, underscores and dashes
- quoted literals (single or double quotes) which can contain any characters
except the used quote character
- arbitrary whitespaces between these tokens
An expression syntactically correct by the previous definition will be
evaluated as follows:
- All variables are substituted by their values and treated as strings.
- All literals are also treated as strings.
- The resulting expression is evaluated as a Python interpreter would
evaluate it.
Please note that the comparison operators only do a string comparison and
don't attempt to interpret the string as a numerical value.
Tools may populate the values for the variables starting with a $ sign in
different ways, but typically they are evaluated as environment variables.
As an example, a dependency might only be needed in a ROS 1 environment.
Such dependency could be described as follows where the value of
$ROS_VERSION is coming from an environment variable:
<depend condition="$ROS_VERSION == 1">roscpp</depend>
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.
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.
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 or key. The <depend> tag cannot be used
in combination with any of the three equivalent tags for the same
package or key name.
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.
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.
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 .
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.
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
and .
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.
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 produces no
architecture-specific files once built.
That information is intended for allowing optimization of packaging.
Specifying <architecture_independent/> 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 , 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.
Only one build type should be active after conditions are evaluated.
If multiple are active then the last build type is to be used.
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 Hydro. 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>
