Stack manifest XML tags reference

NOTE: Stack manifests always have the filename stack.xml.

Required Tags

The required set of tags in a stack.xml file is very minimal and only provides the most basic metadata about your stack, 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. The website is most commonly a wiki page on ROS.org so that users can easily edit and update information about your stack.

Example

<stack>
  <description brief="Common code for working with images">
    Common code for working with images in ROS.
  </description>
  <author>Maintained by Patrick Mihelich</author>
  <license>BSD</license>
  <review status="Doc reviewed" notes="2009/6/10"/>
  <url>http://ros.org/wiki/image_common</url>
  <depend stack="common_msgs" />
  <depend stack="common_rosdeps" />
  <depend stack="pluginlib" />
  <depend stack="ros" />
  <depend stack="ros_comm" />

</stack>

<stack>

The <stack> tag is the top-level tag in a stack manifest.

<description>

Text

Description of the stack. It may be multi-line and include XHTML.

Example

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

Attributes

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

<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 person maintaining the stack.

Example

<author>Alyssa P. Hacker/aphacker@willowgarage.com</author>

<depend>

Declares a stack that this stack depends on.

Example

<depend stack="ros"/>

Attributes

stack="stack_name"
Name of ROS stack dependency.

<url>

Text

Website for the stack. This is important for guiding users to online documentation.

Example

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

<review>

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

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.

Example

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

<version>

Text

The version number of the stack.

IMPORTANT:

  • This should only be used with stacks that follow the release process
  • Do not combine this with the rosbuild_make_distribution() CMake macro. Use the <version> tag or the CMake macro, but not both.

Example

<version>1.2.7</version>