【ROS2】Beginner: Client libraries - create workspace & package

一、创建工作空间

目标：创建一个工作空间并学习如何设置一个用于开发和测试的叠加层。

教程级别：初学者
预计时间：20分钟

目录

• 背景
• 前提条件
• 任务
  1. 配置ROS 2环境
  2. 创建新目录
  3. 克隆示例仓库
  4. 解决依赖关系
  5. 使用colcon构建工作空间
  6. 配置叠加层
  7. 修改叠加层
• 总结
• 下一步

背景

工作空间是一个包含ROS 2功能包的目录。在使用ROS 2之前，需要在计划工作的终端中配置ROS 2安装工作空间，这样才能在该终端中使用ROS 2的功能包。

你也可以选择配置一个"叠加层"(overlay)——一个二级工作空间，你可以在其中添加新功能包，而不会干扰你正在扩展的现有ROS 2工作空间（即"底层"，underlay）。你的底层必须包含叠加层中所有功能包的依赖。叠加层中的功能包会覆盖底层中的同名功能包。也可以有多层底层和叠加层，每个后续叠加层都使用其父底层的功能包。

前提条件

• ROS 2安装
• colcon安装
• git安装
• turtlesim安装
• rosdep安装
• 基本终端命令理解（Linux指南）
• 任意文本编辑器

任务

1. 配置ROS 2环境

你的主要ROS 2安装将作为本教程的底层（请注意，底层不一定必须是主要ROS 2安装）。

根据你的ROS 2安装方式（源码或二进制）和平台，配置命令会有所不同：

Linux

source /opt/ros/kilted/setup.bash

macOS

. ~/ros2_install/ros2-osx/setup.bash

Windows

call C:\dev\ros2\local_setup.bat

（请使用VS 2019的x64 Native Tools Command Prompt执行以下命令）

如果这些命令不起作用，请参考你遵循的安装指南。

2. 创建新目录

最佳实践是为每个新工作空间创建一个新目录。名称无关紧要，但最好能表明工作空间的用途。我们选择ros2_ws作为目录名（表示"开发工作空间"）：

Linux/macOS

mkdir -p ~/ros2_ws/src
cd ~/ros2_ws/src

Windows

md \ros2_ws\src
cd \ros2_ws\src

另一个最佳实践是将工作空间中的所有功能包放入src目录。上面的代码在ros2_ws内创建了一个src目录并进入其中。

3. 克隆示例仓库

确保你仍在ros2_ws/src目录中再进行克隆。

在后续的初学者开发教程中，你将创建自己的功能包，但现在我们先使用现有功能包练习组装工作空间。

如果你完成了初学者CLI工具教程，你应该熟悉turtlesim，它是ros_tutorials中的一个功能包。

仓库可以有多个分支，你需要切换到与你安装的ROS 2发行版对应的分支。克隆时使用-b参数指定分支。

在ros2_ws/src目录中运行以下命令：

git clone https://github.com/ros/ros_tutorials.git -b kilted

现在ros_tutorials已克隆到你的工作空间中。该仓库包含turtlesim功能包（我们将在本教程其余部分使用）。仓库中的其他功能包不会被构建，因为它们包含COLCON_IGNORE文件。

到目前为止，你已经在工作空间中添加了一个示例功能包，但它还不是一个完全功能的工作空间。你需要先解决依赖关系，然后再构建工作空间。

4. 解决依赖关系

在构建工作空间之前，你需要解决功能包依赖。你可能已经拥有所有依赖，但最佳实践是每次克隆后都检查依赖。

从工作空间根目录(ros2_ws)运行以下命令：

Linux

cd ..
rosdep install -i --from-path src --rosdistro kilted -y

macOS/Windows
rosdep只在Linux上运行，所以可以直接跳到第5步"使用colcon构建工作空间"。

如果你在Linux上从源码或二进制归档安装ROS 2，需要使用对应安装指南中的rosdep命令。

如果所有依赖都已安装，控制台将返回：

#All required rosdeps installed successfully

功能包在package.xml文件中声明依赖（你将在下一个教程中学习更多关于功能包的内容）。该命令会检查这些声明并安装缺失的依赖。

5. 使用colcon构建工作空间

从工作空间根目录(ros2_ws)，你可以使用以下命令构建功能包：

Linux/macOS

colcon build

Windows

colcon build --merge-install

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

构建输出示例：

Starting >>> turtlesim
Finished <<< turtlesim [5.49s]
Summary: 1 package finished [5.58s]

有用的colcon build参数：

• --packages-up-to - 只构建指定功能包及其依赖，而非整个工作空间（节省时间）
• --symlink-install - 修改Python脚本时无需重新构建
• --event-handlers console_direct+ - 显示构建过程中的控制台输出
• --executor sequential - 按顺序处理功能包而非并行处理

构建完成后，在工作空间根目录(~/ros2_ws)中输入ls（Linux/macOS）或dir（Windows），你会看到colcon创建了新目录：

build  install  log  src

install目录包含工作空间的配置文件，可用于配置你的叠加层。

6. 配置叠加层

在配置叠加层之前，非常重要的一点是打开一个新终端，与构建工作空间的终端分开。在同一终端中配置叠加层并构建可能会导致复杂问题。

在新终端中，先配置你的主要ROS 2环境作为"底层"，然后才能在其上构建"叠加层"：

Linux

source /opt/ros/kilted/setup.bash

macOS

. ~/ros2_install/ros2-osx/setup.bash

Windows

call C:\dev\ros2\local_setup.bat

进入工作空间根目录：

cd ~/ros2_ws   # Linux/macOS
cd \ros2_ws    # Windows

在根目录中，配置你的叠加层：

Linux

source install/local_setup.bash

macOS

. install/local_setup.bash

Windows

call install\setup.bat

注意：

• 配置叠加层的local_setup只会将叠加层中的功能包添加到环境中
• setup会同时配置叠加层及其创建时的底层，使你能够使用两个工作空间

现在你可以运行叠加层中的turtlesim功能包：

ros2 run turtlesim turtlesim_node

但如何确定这是叠加层的turtlesim在运行，而不是主安装的turtlesim呢？

7. 修改叠加层

你可以通过编辑turtlesim窗口的标题栏来修改叠加层中的turtlesim。

找到~/ros2_ws/src/ros_tutorials/turtlesim/src目录中的 turtle_frame.cpp文件，用你喜欢的文本编辑器打开它。

找到函数setWindowTitle("TurtleSim");，将"TurtleSim"改为"MyTurtleSim"，并保存文件。

返回第一个终端（你之前运行colcon build的终端）再次运行构建命令。

返回第二个终端（已配置叠加层的终端）再次运行turtlesim：

ros2 run turtlesim turtlesim_node

你会看到turtlesim窗口的标题栏现在显示"MyTurtleSim"。

尽管你之前在这个终端中配置了主要ROS 2环境，但ros2_ws环境的叠加层优先于底层内容。

要查看底层仍然完好无损，打开一个全新终端，只配置ROS 2安装，再次运行turtlesim：

ros2 run turtlesim turtlesim_node

你会看到标题栏显示"TurtleSim"，表明叠加层中的修改并未影响到底层。

总结

在本教程中，你将主要ROS 2发行版安装配置为底层，并通过克隆和构建新工作空间中的功能包创建了一个叠加层。叠加层被添加到路径前面，优先于底层，正如你在修改后的turtlesim中看到的那样。

对于只修改少量功能包的情况，推荐使用叠加层，这样你不必将所有内容放在同一个工作空间中，也不必每次迭代都重新构建整个庞大的工作空间。

下一步

现在你已经了解了创建、构建和配置自己工作空间的细节，可以继续学习如何创建自己的功能包了。

二、创建你的第一个ROS 2功能包

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

教程级别：初学者
预计时间：15分钟

目录

• 背景
  1. 什么是ROS 2功能包？
  2. ROS 2功能包由什么组成？
  3. 工作空间中的功能包
• 前提条件
• 任务
  1. 创建功能包
  2. 构建功能包
  3. 配置设置文件
  4. 使用功能包
  5. 检查功能包内容
  6. 自定义package.xml
• 总结
• 下一步

背景

1. 什么是ROS 2功能包？

功能包是ROS 2代码的组织单元。如果你想安装代码或与他人分享，就需要将代码组织成功能包。通过功能包，你可以发布ROS 2作品，让他人能够轻松构建和使用。

ROS 2功能包创建使用ament作为构建系统，colcon作为构建工具。你可以使用CMake或Python创建功能包（官方支持），也存在其他构建类型。

2. ROS 2功能包由什么组成？

ROS 2的Python和CMake功能包各有自己的最小必需内容：

CMake功能包

• CMakeLists.txt - 描述如何构建功能包中的代码
• include/<package_name> - 包含功能包的公共头文件
• package.xml - 包含功能包的元信息
• src - 包含功能包的源代码

Python功能包

• package.xml - 包含功能包的元信息
• resource/<package_name> - 功能包的标记文件
• setup.cfg - 当功能包有可执行文件时必需，使ros2 run能找到它们
• setup.py - 包含安装功能包的指令
• <package_name> - 与功能包同名的目录，ROS 2工具用它找到功能包，包含__init__.py

最简单的功能包目录结构可能如下：

CMake

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

Python

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文件夹中：

Linux/macOS

cd ~/ros2_ws/src

Windows

cd \ros2_ws\src

在ROS 2中创建新功能包的命令语法：

CMake

ros2 pkg create --build-type ament_cmake --license Apache-2.0 <package_name>

Python

ros2 pkg create --build-type ament_python --license Apache-2.0 <package_name>

在本教程中，我们将使用可选参数--node-name和--license。--node-name会在功能包中创建一个简单的Hello World类型可执行文件，--license声明功能包的许可证信息。

在终端中输入以下命令：

CMake

ros2 pkg create --build-type ament_cmake --license Apache-2.0 --node-name my_node my_package

Python

ros2 pkg create --build-type ament_python --license Apache-2.0 --node-name my_node my_package

现在你的工作空间src目录中会有一个名为my_package的新文件夹。

运行命令后，终端会返回以下信息：

CMake

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: ['Apache-2.0']
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

Python

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: ['Apache-2.0']
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一次构建多个功能包，否则你需要逐个构建每个功能包。

返回到工作空间根目录：

Linux/macOS

cd ~/ros2_ws

Windows

cd \ros2_ws

现在你可以构建功能包：

Linux/macOS

colcon build

Windows

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目录内运行以下命令配置你的工作空间：

Linux

source install/local_setup.bash

macOS

. install/local_setup.bash

Windows

call install/local_setup.bat

现在你的工作空间已添加到路径中，你就可以使用新功能包的可执行文件了。

4. 使用功能包

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

ros2 run my_package my_node

终端会返回消息：

CMake

hello world my_package package

Python

Hi from my_package.

5. 检查功能包内容

在ros2_ws/src/my_package内，你会看到ros2 pkg create自动生成的文件和文件夹：

CMake

CMakeLists.txt  include  package.xml  src

my_node.cpp在src目录中。这是将来你所有自定义C++节点的存放位置。

Python

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：

CMake

<?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>

Python

<?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行。你可以在此处了解更多开源许可证。由于这个功能包只是用于练习，使用任何许可证都可以。我们将使用Apache-2.0：

<license>Apache-2.0</license>

完成编辑后别忘了保存。

在license标签下方，你会看到一些以_depend结尾的标签。这是package.xml列出对其他功能包依赖的地方，供colcon搜索。my_package很简单，没有任何依赖，但在后续教程中你会看到这里的使用。

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

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

from setuptools import find_packages, setup

package_name = 'my_py_pkg'

setup(
 name=package_name,
 version='0.0.0',
 packages=find_packages(exclude=['test']),
 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编写。