创建软件包

目标： 使用CMake或Python创建一个新的包，并运行其可执行文件。

教程级别: 初学者

时间： 15分钟

内容

背景
先决条件
任务
总结
下一步

背景 

1 什么是ROS 2包？

包是ROS 2代码的组织单元。如果您希望能够安装代码或与他人共享代码，那么您需要将其组织成一个包。通过包，您可以发布ROS 2工作并允许其他人轻松构建和使用它。

ROS 2中的包创建使用ament作为构建系统和colcon作为构建工具。您可以使用CMake或Python创建一个包，这两种方式得到官方支持，尽管还存在其他构建类型。

2 什么构成了一个ROS 2软件包?

ROS 2的Python和CMake软件包各自有其最小要求的内容:

``CMakeLists.txt``文件，描述了如何构建软件包内的代码
包含该包的公共头文件的 include/<package_name> 目录
包含有关该包的元信息的 package.xml 文件
包含该包源代码的 src 目录

包含有关该包的元信息的 package.xml 文件
用于标记该包的 resource/<package_name> 文件
当一个软件包包含可执行文件时，需要使用``setup.cfg``，以便``ros2 run``能够找到它们
``setup.py``包含了安装该软件包的指令
<package_name> - 与软件包同名的目录，被ROS 2工具用于查找软件包，包含``__init__.py``

最简单的软件包的文件结构可能如下所示：

my_package/
     CMakeLists.txt
     include/my_package/
     package.xml
     src/

my_package/
      package.xml
      resource/my_package
      setup.cfg
      setup.py
      my_package/

工作空间中的3个软件包 

一个工作空间可以包含任意多个软件包，每个软件包位于自己的文件夹中。您还可以在一个工作空间中拥有不同构建类型的软件包（如CMake、Python等）。但不能嵌套软件包。

最佳实践是在工作空间中创建一个``src``文件夹，并在其中创建您的软件包。这样可以保持工作空间的顶层“清洁”。

一个简单的工作空间可能如下所示：

workspace_folder/
    src/
      cpp_package_1/
          CMakeLists.txt
          include/cpp_package_1/
          package.xml
          src/

      py_package_1/
          package.xml
          resource/py_package_1
          setup.cfg
          setup.py
          py_package_1/
      ...
      cpp_package_n/
          CMakeLists.txt
          include/cpp_package_n/
          package.xml
          src/

先决条件 

在按照先前教程的说明操作后，您应该拥有一个 ROS 2 工作空间。您将在该工作空间中创建您的软件包。

任务 

1 创建一个包 

首先，配置您的 ROS 2 安装环境。

让我们使用您在先前教程中创建的工作空间 ros2_ws 来创建您的新软件包。

在运行软件包创建命令之前，请确保您位于 src 文件夹中。

cd ~/ros2_ws/src

cd ~/ros2_ws/src

cd \ros2_ws\src

在ROS 2中创建新包的命令语法如下：

ros2 pkg create --build-type ament_cmake <package_name>

ros2 pkg create --build-type ament_python <package_name>

在本教程中，您将使用可选参数``--node-name``，它将在包中创建一个简单的Hello World类型的可执行文件。

在终端中输入以下命令：

ros2 pkg create --build-type ament_cmake --node-name my_node my_package

ros2 pkg create --build-type ament_python --node-name my_node my_package

现在，您的工作空间的``src``目录中将有一个名为``my_package``的新文件夹。

运行该命令后，您的终端会返回以下消息：

going to create a new package
package name: my_package
destination directory: /home/user/ros2_ws/src
package format: 3
version: 0.0.0
description: TODO: Package description
maintainer: ['<name> <email>']
licenses: ['TODO: License declaration']
build type: ament_cmake
dependencies: []
node_name: my_node
creating folder ./my_package
creating ./my_package/package.xml
creating source and include folder
creating folder ./my_package/src
creating folder ./my_package/include/my_package
creating ./my_package/CMakeLists.txt
creating ./my_package/src/my_node.cpp

going to create a new package
package name: my_package
destination directory: /home/user/ros2_ws/src
package format: 3
version: 0.0.0
description: TODO: Package description
maintainer: ['<name> <email>']
licenses: ['TODO: License declaration']
build type: ament_python
dependencies: []
node_name: my_node
creating folder ./my_package
creating ./my_package/package.xml
creating source folder
creating folder ./my_package/my_package
creating ./my_package/setup.py
creating ./my_package/setup.cfg
creating folder ./my_package/resource
creating ./my_package/resource/my_package
creating ./my_package/my_package/__init__.py
creating folder ./my_package/test
creating ./my_package/test/test_copyright.py
creating ./my_package/test/test_flake8.py
creating ./my_package/test/test_pep257.py
creating ./my_package/my_package/my_node.py

您可以看到为新软件包自动生成的文件。

2 构建软件包 

将软件包放入工作区尤其有价值，因为您可以通过在工作区根目录下运行``colcon build``一次性构建多个软件包。否则，您将需要逐个构建每个软件包。

返回工作区的根目录：

cd ~/ros2_ws

cd ~/ros2_ws

cd \ros2_ws

现在你可以构建你的软件包：

colcon build

colcon build

colcon build --merge-install

Windows 不允许使用过长的路径，所以 merge-install 将会把所有路径合并到 install 目录中。

从上个教程中你记得你的``ros2_ws``里也有``ros_tutorials``软件包。你可能已经注意到运行``colcon build``时还会构建``turtlesim``软件包。当你的工作区只有几个软件包时这没问题，但当有很多软件包时，``colcon build``会花费很长时间。

下次只构建``my_package``软件包，你可以运行：

colcon build --packages-select my_package

3 导入设置文件 

要使用您的新软件包和可执行文件，请首先打开一个新终端并导入您的主要ROS 2安装。

然后，在``ros2_ws``目录内运行以下命令以导入您的工作空间：

source install/local_setup.bash

. install/local_setup.bash

call install/local_setup.bat

现在，您的工作空间已添加到路径中，您将能够使用您的新软件包的可执行文件。

4 使用软件包 

要运行您使用``--node-name``参数在创建软件包时创建的可执行文件，请输入以下命令：

ros2 run my_package my_node

将在终端返回一条消息：

hello world my_package package

Hi from my_package.

5 检查软件包内容 

在 ros2_ws/src/my_package 内，您将看到 ros2 pkg create 自动创建的文件和文件夹：

CMakeLists.txt  include  package.xml  src

my_node.cpp 位于 src 目录中。这是您以后将放置所有自定义 C++ 节点的位置。

my_package  package.xml  resource  setup.cfg  setup.py  test

my_node.py 位于 my_package 目录中。这是您以后将放置所有自定义 Python 节点的位置。

6 自定义 package.xml 

在创建包后，您可能会注意到返回消息中的字段“description”和“license”包含“TODO”注释。这是因为包的描述和许可声明不会自动设置，但是如果您想发布包，它们是必需的。如果需要，还可以填写“maintainer”字段。

从“ros2_ws/src/my_package”目录下，使用您喜欢的文本编辑器打开“package.xml”文件：

<?xml version="1.0"?>
<?xml-model
   href="http://download.ros.org/schema/package_format3.xsd"
   schematypens="http://www.w3.org/2001/XMLSchema"?>
<package format="3">
 <name>my_package</name>
 <version>0.0.0</version>
 <description>TODO: Package description</description>
 <maintainer email="user@todo.todo">user</maintainer>
 <license>TODO: License declaration</license>

 <buildtool_depend>ament_cmake</buildtool_depend>

 <test_depend>ament_lint_auto</test_depend>
 <test_depend>ament_lint_common</test_depend>

 <export>
   <build_type>ament_cmake</build_type>
 </export>
</package>

<?xml version="1.0"?>
<?xml-model
   href="http://download.ros.org/schema/package_format3.xsd"
   schematypens="http://www.w3.org/2001/XMLSchema"?>
<package format="3">
 <name>my_package</name>
 <version>0.0.0</version>
 <description>TODO: Package description</description>
 <maintainer email="user@todo.todo">user</maintainer>
 <license>TODO: License declaration</license>

 <test_depend>ament_copyright</test_depend>
 <test_depend>ament_flake8</test_depend>
 <test_depend>ament_pep257</test_depend>
 <test_depend>python3-pytest</test_depend>

 <export>
   <build_type>ament_python</build_type>
 </export>
</package>

如果“maintainer”行没有自动填充，请在该行上输入您的姓名和电子邮件。然后，编辑“description”行以对包进行概括：

<description>Beginner client libraries tutorials practice package</description>

然后，更新“license”行。您可以在此处阅读有关开源许可证的更多信息：<https://opensource.org/licenses/alphabetical>。由于此包仅用于练习，使用任何许可证都是安全的。我们将使用“Apache License 2.0”：

<license>Apache License 2.0</license>

编辑完成后别忘了保存。

在许可证标签下面，你会看到一些以``_depend``结尾的标签名。这是你的``package.xml``文件列出了它对其他软件包的依赖关系，供colcon进行搜索。``my_package``很简单，并不依赖其他软件包，但你将在接下来的教程中看到这个空间被利用起来。

目前为止，你已经完成了！

setup.py``文件包含了与``package.xml``相同的描述、维护者和许可证字段，所以你也需要设置它们。两个文件中的内容必须完全匹配。版本和名称（``package_name）也必须完全匹配，并且应该在两个文件中自动填充。

用你喜欢的文本编辑器打开 setup.py 。

from setuptools import setup

package_name = 'my_py_pkg'

setup(
 name=package_name,
 version='0.0.0',
 packages=[package_name],
 data_files=[
     ('share/ament_index/resource_index/packages',
             ['resource/' + package_name]),
     ('share/' + package_name, ['package.xml']),
   ],
 install_requires=['setuptools'],
 zip_safe=True,
 maintainer='TODO',
 maintainer_email='TODO',
 description='TODO: Package description',
 license='TODO: License declaration',
 tests_require=['pytest'],
 entry_points={
     'console_scripts': [
             'my_node = my_py_pkg.my_node:main'
     ],
   },
)

编辑 maintainer、maintainer_email 和 description 行，使其与 package.xml 匹配。

不要忘记保存文件。

总结 

你创建了一个用于组织代码并方便他人使用的包。

您的软件包已自动填充所需文件，然后您使用 colcon 构建它，以便在本地环境中使用其可执行文件。

下一步 

接下来，让我们向软件包添加一些有意义的内容。您可以选择使用 C++ 或 Python 来编写一个简单的发布者/订阅者系统。