Package manifest XML tags reference

Manifests always have the filename manifest.xml.

Manifests must use valid XML syntax, including escaping special characters such as <, >, and & when they are used inside strings (use &lt;, &gt;, and &amp;, respectively).

Required Tags

The required set of tags in a manifest.xml file is very minimal and only provides the most basic metadata about your package, including what it is, who wrote it, and who can use it.

Optional Tags

The most common optional tags are <depend> and <url>. We strongly recommend the use of the <url> tag to point users to a website where they can find out more information about your stack. This website is most commonly a wiki page on ros.org.

<description>

Text

Description of your package. It may be multi-line and include XHTML.

Attributes

brief="brief text" (optional)
One-line summary of your Package. Useful for UI displays where the package name isn’t sufficiently descriptive.

Example

<description brief="ROS for Python">
   Python implementation of the ROS master/node APIs and client library.
</description>

<license>

Text

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 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
  • ZLib
  • wxWindows

Attributes

url="license url" (optional)
For lesser-known licenses, it is helpful to add this attribute with a link to the text of the license.

Example

<license>BSD</license>

<author>

Text

Name and contact information for the package. If there are multiple authors, use a comma-separated list in a single author tag.

Example

<author>Alyssa P. Hacker/aphacker@willowgarage.com, Norman Contributor/norcon@example.com</author>

<depend>

Declare a ROS package that this package depends on.

Attributes

package="ros_package_name"
Name of ROS package dependency.

Example

<depend package="pkgname"/>

<rosdep>

Declare an external dependency that this package requires and can be installed via rosdep. These external dependencies are generally libraries that can be installed by OS package managers, like apt.

Attributes

name="rosdep_dependency"
Name of rosdep dependency.

Example

<rosdep name="boost"/>

<url> tag

Text

Web site for your package. This is important for guiding users to your online documentation.

Example

<url>http://ros.org/wiki/rospy</url>

<export>

The <export> ... </export> portion of the manifest declares various flags and settings that a package wishes to export to support tools, such as CMake. This section is extensible by individual tools and these properties can be extracted from the command-line using the rospack tool.

Elements

You are free to add your own XML elements to the <export> section of a manifest. This is used by a variety of packages for functionality such as plugins. Tags currently used include:

export: <cpp>

Export flags to the make compiler. These flags are made available to users of this package, not the package itself. This is not the place to put flags that you’ll need in building your package. Instead, encode those needs in the [[CMakeLists|CMakeLists.txt]] file, using standard CMake macros, such as include_directories() and target_link_libraries().

Attributes

cflags="${prefix}/include"
cflags export value.
lflags="..."
lflags export value.
os="osx"
Restricts settings to a particular OS.

Example

<cpp cflags="-I${prefix}/include" lflags="-L${prefix}/lib -Wl,-rpath,${prefix}/lib -lros"/>
<cpp os="osx" cflags="-I${prefix}/include" lflags="-L${prefix}/lib -Wl,-rpath,${prefix}/lib -lrosthread -framework CoreServices"/>

Note the use of -Wl,-rpath,${prefix}/lib. This tells the linker to look in ${prefix}/lib for shared libraries when running an executable. This flag is necessary to allow the use of shared libraries that reside in a variety of directories, without requiring the user to modify LD_LIBRARY_PATH. Every time you add a -Lfoo option to your exported lflags, add a matching -Wl,-rpath,foo option. The -Wl options can be chained together, e.g.: -Wl,-rpath,foo,-rpath,bar.

export: <python>

Export a path other than the default ${prefix}/src to the PYTHONPATH.

Attributes

path="${prefix}/mydir"
Path to append to PYTHONPATH.

Example

<python path="${prefix}/different_dir"/>

export: <rosdoc>

Override settings in the rosdoc documentation generator. Currently this is used to disable auto-generated code documentation on the package. This is common for thirdparty packages, which have their own documentation. This tag enables packages to link to this external documentation.

Attributes

external="http://link" (optional)
URL to external documentation. rosdoc will not run a documentation tool (e.g. Doxygen) on this package.
config="rosdoc.yaml" (optional)
Name of rosdoc configuration file.

Examples

External API documentation:

<rosdoc external="http://external/documentation.html"/>

Using an external config file:

<rosdoc config="rosdoc.yaml"/>

Attributes

excludes="build" (optional)
Path to exclude (see Doxygen documentation on EXCLUDES).
file-patterns="*.c *.cpp *.dox" (optional)
Patterns for files to include (see Doxygen documentation on FILE_PATTERNS).

export: <roslang>

This tag should only be used by ROS client libraries, such as roscpp and rospy.

The <roslang> export specifies a CMake file that should be exported to the rosbuild system. The CMake rules will be exported to every ROS package, which is necessary for functionality such as message and service generation.

Attributes

cmake="${prefix}/cmake/file.cmake"
CMake file.

Example

<roslang cmake="${prefix}/cmake/rospy.cmake"/>

export: <roswtf>

Declare a roswtf plugin.

Attributes

plugin="python.module"
Python modulename to export as a [[roswtf]] plugin.

Example

<roswtf plugin="tf.tfwtf" />

<review>

Status of the package in the review process (Design, API, and Code review). See QAProcess. Packages that have not yet been reviewed should be marked as “experimental”.

Example

<review status="experimental" notes="reviewed on 3/14/09" />

Attributes

status="status"
See list of valid review statuses.
notes="notes on review status" (optional)
Notes on review status, such as date of last review.