1.. _manifest_xml: 2 3Package manifest XML tags reference 4=================================== 5 6Manifests always have the filename ``manifest.xml``. 7 8Manifests must use `valid XML syntax <http://www.w3schools.com/xml/xml_syntax.asp>`_, including escaping special characters such as ``<``, ``>``, and ``&`` when they are used inside strings (use ``<``, ``>``, and ``&``, respectively). 9 10.. contents:: Table of Contents 11 :depth: 2 12 13Required Tags 14------------- 15 16The 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. 17 18 * :ref:`\<package\> <package_tag>` 19 * :ref:`\<description\> <manifest_description_tag>` 20 * :ref:`\<description|<manifest_description_tag>` 21 * :ref:`\<license|<manifest_license_tag>` 22 * :ref:`\<author\> <manifest_author_tag>` 23 24Optional Tags 25------------- 26 27The most common optional tags are :ref:`\<depend\> <manifest_depend_tag>` and 28:ref:`\<url\> <manifest_url_tag>`. We strongly recommend the use of the 29``<url>`` tag to point users to a website where they can find out 30more information about your stack. This website is most commonly a 31wiki page on ros.org. 32 33 34 * :ref:`\<depend\> <manifest_depend_tag>` 35 * :ref:`\<rosdep\> <manifest_rosdep_tag>` 36 * :ref:`\<url\> <manifest_url_tag>` 37 * :ref:`\<review\> <manifest_review_tag>` 38 * :ref:`\<export\> <manifest_export_tag>` 39 * :ref:`\<versioncontrol\> <versioncontrol_tag>` 40 41.. _package_tag: 42 43<package> 44--------- 45 46This is the top-level tag in a manifest. 47 48Elements 49'''''''' 50 51 * :ref:`\<description\> <manifest_description_tag>` 52 * :ref:`\<license\> <manifest_license_tag>` 53 * :ref:`\<author\> <manifest_author_tag>` 54 * :ref:`\<url\> <manifest_url_tag>` 55 * :ref:`\<depend\> <manifest_depend_tag>` 56 * :ref:`\<rosdep\> <manifest_rosdep_tag>` 57 * :ref:`\<export\> <manifest_export_tag>` 58 * :ref:`\<review\> <manifest_review_tag>` 59 * :ref:`\<versioncontrol\> <versioncontrol_tag>` 60 61.. _manifest_description_tag: 62 63<description> 64------------- 65 66Text 67'''' 68 69Description of your package. It may be multi-line and include XHTML. 70 71Attributes 72'''''''''' 73 74 ``brief="brief text"`` *(optional)* 75 One-line summary of your Package. Useful for UI displays where the package name isn't sufficiently descriptive. 76 77Example 78''''''' 79 80:: 81 82 <description brief="ROS for Python"> 83 Python implementation of the ROS master/node APIs and client library. 84 </description> 85 86 87.. _manifest_license_tag: 88 89<license> 90--------- 91 92Text 93'''' 94 95Name 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. 96 97Most common open-source licenses are described on the `OSI website <http://www.opensource.org/licenses/alphabetical>`_. 98 99Commonly used license strings: 100 101 - Apache 2.0 102 - BSD 103 - Boost Software License 104 - GPLv2 105 - GPLv3 106 - LGPLv2.1 107 - LGPLv3 108 - MIT 109 - Mozilla Public License Version 1.1 110 - ZLib 111 - wxWindows 112 113 114Attributes 115'''''''''' 116 117 ``url="license url"`` *(optional)* 118 For lesser-known licenses, it is helpful to add this attribute with a link to the text of the license. 119 120Example 121''''''' 122 123:: 124 125 <license>BSD</license> 126 127 128.. _manifest_author_tag: 129 130<author> 131-------- 132 133Text 134'''' 135 136Name and contact information for the package. If there are multiple authors, use a comma-separated list in a single author tag. 137 138Example 139''''''' 140 141:: 142 143 <author>Alyssa P. Hacker/aphacker@willowgarage.com, Norman Contributor/norcon@example.com</author> 144 145 146.. _manifest_depend_tag: 147 148<depend> 149-------- 150 151Declare a ROS package that this package depends on. 152 153Attributes 154'''''''''' 155 156 ``package="ros_package_name"`` 157 Name of ROS package dependency. 158 159Example 160''''''' 161 162:: 163 164 <depend package="pkgname"/> 165 166.. _manifest_rosdep_tag: 167 168<rosdep> 169-------- 170 171Declare an external dependency that this package requires and can be installed via `rosdep <http://ros.org/wiki/rosdep>`_. These external dependencies are generally libraries that can be installed by OS package managers, like ``apt``. 172 173Attributes 174'''''''''' 175 176 ``name="rosdep_dependency"`` 177 Name of rosdep dependency. 178 179Example 180''''''' 181 182:: 183 184 <rosdep name="boost"/> 185 186 187.. _manifest_url_tag: 188 189<url> tag 190--------- 191 192Text 193'''' 194 195Web site for your package. This is important for guiding users to your online documentation. 196 197Example 198''''''' 199 200:: 201 202 <url>http://ros.org/wiki/rospy</url> 203 204.. _versioncontrol_tag: 205 206.. _manifest_export_tag: 207 208<export> 209-------- 210 211The ``<export> ... </export>`` portion of the manifest declares 212various flags and settings that a package wishes to export to support 213tools, such as CMake. This section is extensible by individual tools 214and these properties can be extracted from the command-line using the 215`rospack <http://ros.org/wiki/rospack>`_ tool. 216 217Elements 218'''''''' 219 220You are free to add your own XML elements to the ``<export>`` section 221of a manifest. This is used by a variety of packages for functionality 222such as plugins. Tags currently used include: 223 224 * :ref:`\<cpp\> <cpp_tag>` 225 * :ref:`\<python\> <python_tag>` 226 * :ref:`\<rosdoc\> <rosdoc_tag>` 227 * :ref:`\<roslang\> <roslang_tag>` 228 * :ref:`\<roswtf\> <roswtf_tag>` 229 230 231.. _cpp_tag: 232 233export: <cpp> 234------------- 235 236Export flags to the make compiler. These flags are made available to 237*users* of this package, not the package itself. This is not the 238place to put flags that you'll need in building your package. 239Instead, encode those needs in the [[CMakeLists|CMakeLists.txt]] file, 240using standard CMake macros, such as ``include_directories()`` and 241``target_link_libraries()``. 242 243Attributes 244'''''''''' 245 246 ``cflags="${prefix}/include"`` 247 cflags export value. 248 ``lflags="..."`` 249 lflags export value. 250 ``os="osx"`` 251 Restricts settings to a particular OS. 252 253Example 254''''''' 255 256:: 257 258 <cpp cflags="-I${prefix}/include" lflags="-L${prefix}/lib -Wl,-rpath,${prefix}/lib -lros"/> 259 <cpp os="osx" cflags="-I${prefix}/include" lflags="-L${prefix}/lib -Wl,-rpath,${prefix}/lib -lrosthread -framework CoreServices"/> 260 261Note 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 :envvar:`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``. 262 263.. _python_tag: 264 265export: <python> 266---------------- 267 268Export a path other than the default ``${prefix}/src`` to the :envvar:`PYTHONPATH`. 269 270Attributes 271'''''''''' 272 273 ``path="${prefix}/mydir"`` 274 Path to append to :envvar:`PYTHONPATH`. 275 276Example 277''''''' 278 279:: 280 281 <python path="${prefix}/different_dir"/> 282 283 284.. _rosdoc_tag: 285 286export: <rosdoc> 287---------------- 288 289Override settings in the `rosdoc <http://ros.org/wiki/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. 290 291Attributes 292'''''''''' 293 294 ``external="http://link"`` *(optional)* 295 URL to external documentation. rosdoc will not run a documentation tool (e.g. Doxygen) on this package. 296 ``config="rosdoc.yaml"`` *(optional)* 297 Name of rosdoc configuration file. 298 299Examples 300'''''''' 301 302External API documentation:: 303 304 <rosdoc external="http://external/documentation.html"/> 305 306 307Using an external config file:: 308 309 <rosdoc config="rosdoc.yaml"/> 310 311 312Attributes 313'''''''''' 314 315 ``excludes="build"`` *(optional)* 316 Path to exclude (see Doxygen documentation on `EXCLUDES`). 317 ``file-patterns="*.c *.cpp *.dox"`` *(optional)* 318 Patterns for files to include (see Doxygen documentation on `FILE_PATTERNS`). 319 320.. _roslang_tag: 321 322export: <roslang> 323----------------- 324 325This tag should only be used by ROS client libraries, such as `roscpp <http://ros.org/wiki/roscpp>`_ and `rospy <http://ros.org/wiki/rospy>`_. 326 327The ``<roslang>`` export specifies a CMake file that should be exported to the `rosbuild <http://ros.org/wiki/rosbuild>`_ system. The CMake rules will be exported to *every* ROS package, which is necessary for functionality such as message and service generation. 328 329Attributes 330'''''''''' 331 332 ``cmake="${prefix}/cmake/file.cmake"`` 333 CMake file. 334 335Example 336''''''' 337 338:: 339 340 341 342 <roslang cmake="${prefix}/cmake/rospy.cmake"/> 343 344 345.. _roswtf_tag: 346 347export: <roswtf> 348---------------- 349 350Declare a `roswtf <http://ros.org/wiki/roswtf>`_ plugin. 351 352Attributes 353'''''''''' 354 355 ``plugin="python.module"`` 356 Python modulename to export as a [[roswtf]] plugin. 357 358Example 359''''''' 360 361:: 362 363 <roswtf plugin="tf.tfwtf" /> 364 365 366.. _manifest_review_tag: 367 368<review> 369-------- 370 371Status of the package in the review process (Design, API, and Code review). See `QAProcess <http://ros.org/wiki/QAProcess>`_. Packages that have not yet been reviewed should be marked as "experimental". 372 373Example 374''''''' 375 376:: 377 378 <review status="experimental" notes="reviewed on 3/14/09" /> 379 380 381Attributes 382'''''''''' 383 384 ``status="status"`` 385 See `list of valid review statuses <http://ros.org/wiki/Review Status>`_. 386 ``notes="notes on review status"`` *(optional)* 387 Notes on review status, such as date of last review. 388 389