1. 概览
程序包清单是一个名为 package.xml 的 XML 文件,必须包含在任何符合 catkin 规范的程序包的根目录中。此文件定义包的各种属性,例如包名称,版本号,作者,维护者以及对其他 catkin 包的依赖。请注意,此概念类似于旧版 rosbuild 构建系统中使用的 manifest.xml 文件。
你的系统包依赖项在 package.xml 中声明。 如果这些依赖项缺失或不正确,你可以在自己的计算机上构建源代码并运行测试,但是当发布到 ROS 社区时,你的程序包将无法正常运行。 其他人根据这些信息得知使用你的程序包需要安装的软件(除了 U-Texas 的 catkin 任务导向文档)。
2. 格式2(推荐)
这是新程序包的推荐格式,并且推荐你将格式 1 的程序包转换为格式 2 的程序包。有关从格式 1 迁移到格式 2的说明,请参阅 catkin API 文档中的 从格式 1 迁移到格式 2。
格式 2 的完整文档可以在 catkin API 文档中找到。更多信息可以在 REP 140 - Package Manifest Format Two Specification 中找到。
2.1 基本结构
每个 package.xml 文件都将 <package>
标记作为文档中的根标记。
<package format="2">
</package>
2.2 必需的标记
为使程序包清单完整,<package>
标记中需要嵌套一套最小标记。
<name>
- 程序包名<version>
- 包的版本号(需要 3 个点分隔的整数)<description>
- 对包内容的描述<maintainer>
- 包的维护者名字license
- 发布代码的软件许可证(例如 GPL, BSD, AS)
举个例子,这里是一个名为 foo_core 的虚构包的包清单。
<package format="2">
<name>foo_core</name>
<version>1.2.4</version>
<description>
This package provides foo capability.
</description>
<maintainer email="ivana@osrf.org">Ivana Bildbotz</maintainer>
<license>BSD</license>
</package>
2.3 依赖
上述带有最小标记的程序包清单没有指出对其他包的任何依赖性。程序包可以有六种类型的依赖项:
- Build 依赖指定构建此程序包所需的程序包。这种情况是在构建的时候需要一些来自这些包的文件,例如在编译时包含了来自这些包的头文件,需要链接来自这些包的库或在构建时需要任何其他资源(特别是当这些包是在 CMake 中的 find_package() 时)。在交叉编译方案中,构建依赖应当适用于目标体系结构。
- Build 导出依赖指定将此程序包构建为库所依赖的包。例如你在将要导出的头文件中包含了依赖项的头文件,则属于这种情况(特别是当这些包在 CMake 中的 catkin_package() 中声明为 (CATKIN_)DEPENDS时)。
- Execution 依赖指定运行此程序包中代码所需的包。当此包中的依赖有共享库时就是这种情况(特别是当这些包在 CMake 中的 catkin_package() 中声明为 (CATKIN_)DEPENDS 时)。
- Test 依赖仅指定用于单元测试的其他依赖项。不要重复指定已经提到的构建和运行时依赖。
- Build 工具依赖指定此程序包构建自身所需的构建系统工具。通常,唯一需要的构建工具是 catkin。 在交叉编译方案中,构建工具依赖应当适用于执行编译的体系结构。
- 文档工具依赖指定程序包用来生成文档的工具。
上述 6 种依赖项分别使用以下 6 个标签指定:
<depend>
<buildtool_depend>
<build_depend>
<build_export_depend>
<exec_depend>
<test_depend>
<doc_depend>
所有包都至少有一个依赖项,即构建工具依赖项 catkin,如下例所示。
<package format="2">
<name>foo_core</name>
<version>1.2.4</version>
<description>
This package provides foo capability.
</description>
<maintainer email="ivana@osrf.org">Ivana Bildbotz</maintainer>
<license>BSD</license>
<buildtool_depend>catkin</buildtool_depend>
</package>
一个指定了构建、执行、测试和文档依赖关系的更实际的例子可能如下所示。
<package format="2">
<name>foo_core</name>
<version>1.2.4</version>
<description>
This package provides foo capability.
</description>
<maintainer email="ivana@willowgarage.com">Ivana Bildbotz</maintainer>
<license>BSD</license>
<url>http://ros.org/wiki/foo_core</url>
<author>Ivana Bildbotz</author>
<buildtool_depend>catkin</buildtool_depend>
<depend>roscpp</depend>
<depend>std_msgs</depend>
<build_depend>message_generation</build_depend>
<exec_depend>message_runtime</exec_depend>
<exec_depend>rospy</exec_depend>
<test_depend>python-mock</test_depend>
<doc_depend>doxygen</doc_depend>
</package>
更多关于依赖关系的细节可以在 catkin API 文档中找到。
2.4 元功能包
将多个程序包组织为一个逻辑包通常可以带来方便,这可以通过元功能包来实现。元功能包是一个普通的功能包,但在其 package.xml 的 <export>
标记中嵌套了一个 <metapackage />
:
<export>
<metapackage />
</export>
除了对 catkin 必需的 <buildtool_depends>
依赖之外,元功能包只能对其所组织的包具有 execution 依赖性。
另外,元功能包需要一个如下面样板所示的 CMakeLists.txt 文件:
cmake_minimum_required(VERSION 2.8.3)
project(<PACKAGE_NAME>)
find_package(catkin REQUIRED)
catkin_metapackage()
注意:将 <PACKAGE_NAME> 替换为元功能包的名称。
2.5 其他标记
<url>
- 该程序包的 URL 信息,通常是 ros.org 上的维基页。- <
author>
- 程序包作者
3. 格式 1(旧的格式)
较旧的 catkin 程序包清单使用格式 1。 如果 <package>
标签没有 format 属性,则它是格式 1 的包。 格式 2 用于新程序包。
package.xml 的格式很简单。
3.1 基本结构
每个 package.xml 文件都将 <package>
标记作为文档中的根标记。
<package>
</package>
3.2 必需的标记
为使程序包清单完整,<package>
标记中需要嵌套一套最小标记。
<name>
- 程序包名<version>
- 包的版本号(需要 3 个点分隔的整数)<description>
- 对包内容的描述<maintainer>
- 包的维护者名字license
- 发布代码的软件许可证(例如 GPL, BSD, AS)
举个例子,这里是一个名为 foo_core 的虚构包的包清单。
<package>
<name>foo_core</name>
<version>1.2.4</version>
<description>
This package provides foo capability.
</description>
<maintainer email="ivana@osrf.org">Ivana Bildbotz</maintainer>
<license>BSD</license>
</package>
3.3 构建、运行和测试依赖
上述带有最小标记的程序包清单没有指出对其他包的任何依赖性。程序包可以有四种类型的依赖项:
- Build Tool 依赖指定此程序包构建自身所需的构建系统工具。通常,唯一需要的构建工具是 catkin。 在交叉编译方案中,构建工具依赖应当适用于执行编译的体系结构。
- Build 依赖指定构建此程序包所需的程序包。这种情况是在构建的时候需要一些来自这些包的文件,例如在编译时包含了来自这些包的头文件,需要链接来自这些包的库或在构建时需要任何其他资源(特别是当这些包是在 CMake 中的 find_package() 时)。在交叉编译方案中,构建依赖应当适用于目标体系结构。
- Run 依赖指定运行此程序包中代码所需的包,以及从此包构建库所需的包。当此包中的依赖有共享库,或在公共头文件中传递地包含了它们的头文件时就是这种情况(特别是当这些包在 CMake 中的 catkin_package() 中声明为 (CATKIN_)DEPENDS 时)。
- Test 依赖仅指定用于单元测试的其他依赖项。不要重复指定已经提到的构建和运行时依赖。
上述 4 种依赖项分别使用以下 4 个标签指定:
<buildtool_depend>
<build_depend>
<run_depend>
<test_depend>
所有包都至少有一个依赖项,即构建工具依赖项 catkin,如下例所示。
<package>
<name>foo_core</name>
<version>1.2.4</version>
<description>
This package provides foo capability.
</description>
<maintainer email="ivana@willowgarage.com">Ivana Bildbotz</maintainer>
<license>BSD</license>
<buildtool_depend>catkin</buildtool_depend>
</package>
一个指定了构建、执行、和测试依赖关系的更实际的例子可能如下所示。
<package>
<name>foo_core</name>
<version>1.2.4</version>
<description>
This package provides foo capability.
</description>
<maintainer email="ivana@willowgarage.com">Ivana Bildbotz</maintainer>
<license>BSD</license>
<url>http://ros.org/wiki/foo_core</url>
<author>Ivana Bildbotz</author>
<buildtool_depend>catkin</buildtool_depend>
<build_depend>message_generation</build_depend>
<build_depend>roscpp</build_depend>
<build_depend>std_msgs</build_depend>
<run_depend>message_runtime</run_depend>
<run_depend>roscpp</run_depend>
<run_depend>rospy</run_depend>
<run_depend>std_msgs</run_depend>
<test_depend>python-mock</test_depend>
</package>
有关依赖关系的更多细节请点击这里。
3.4 元功能包
将多个程序包组织为一个逻辑包通常可以带来方便,这可以通过元功能包来实现。元功能包是一个普通的功能包,但在其 package.xml 的 <export>
标记中嵌套了一个 <metapackage />
:
<export>
<metapackage />
</export>
除了对 catkin 必需的 <buildtool_depends>
依赖之外,元功能包只能对其所组织的包具有 execution 依赖性。
另外,元功能包需要一个如下面样板所示的 CMakeLists.txt 文件:
cmake_minimum_required(VERSION 2.8.3)
project(<PACKAGE_NAME>)
find_package(catkin REQUIRED)
catkin_metapackage()
注意:将 <PACKAGE_NAME> 替换为元功能包的名称。
在讨论了 package.xml 文件的安装之后,元功能包现在有了 CMakeLists.txt 文件:
https://groups.google.com/forum/#!msg/ros-sig-buildsystem/mn-VCkl2OHk/dUsHBBjyK30J
所以现在元功能包的 package.xml 文件是会安装到系统中的 ,但是仍然强制要求用户不要不要把元功能包作为依赖项,所以不要偏离建议的样板 CMakeLists.txt 代码。
3.5 其他标记
<url>
- 该程序包的 URL 信息,通常是 ros.org 上的维基页。- <
author>
- 程序包作者