创建软件包 [4496]

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

教程级别: 初学者 [3951]

时间： 15分钟 [3507]

内容 [16422]

背景 [16410]
先决条件 [16411]
任务 [16427]
总结 [16454]
下一步 [16493]

背景 [16410]

1 什么是ROS 2包？ [4498]

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

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

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

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

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

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

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

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

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

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

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

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

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

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/

先决条件 [16411]

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

任务 [16427]

1 创建一个包 [3283]

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

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

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

cd ~/ros2_ws/src

cd ~/ros2_ws/src

cd \ros2_ws\src

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

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

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

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

在终端中输入以下命令： [4523]

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``的新文件夹。 [4524]

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

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

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

2 构建软件包 [4527]

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

返回工作区的根目录： [4529]

cd ~/ros2_ws

cd ~/ros2_ws

cd \ros2_ws

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

colcon build

colcon build

colcon build --merge-install

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

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

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

colcon build --packages-select my_package

3 导入设置文件 [4533]

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

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

source install/local_setup.bash

. install/local_setup.bash

call install/local_setup.bat

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

4 使用软件包 [4537]

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

ros2 run my_package my_node

将在终端返回一条消息： [4539]

hello world my_package package

Hi from my_package.

5 检查软件包内容 [4540]

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

CMakeLists.txt  include  package.xml  src

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

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

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

6 自定义 package.xml [4544]

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

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

<?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”行以对包进行概括： [4547]

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

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

<license>Apache License 2.0</license>

编辑完成后别忘了保存。 [4549]

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

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

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

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

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 匹配。 [4554]

不要忘记保存文件。 [4555]

总结 [16454]

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

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

下一步 [16493]

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