ROS 2 Iron 教程 第二章 Client libraries 第一节 使用 colcon 构建包

本节教程简要介绍了如何使用colcon创建并构建 ROS 2 工作空间。这是一个实用的教程，并非旨在取代核心文档。

前言

本系列文章是由笔者翻译自ROS 2 官方教程。笔者水平有限，如有错误，还请读者指正。
本节教程中部分代码为 Liunx下，请使用其他操作系统的读者前往原文查看。

背景

colcon是 ROS 构建工具catkin_make，catkin_make_isolated，catkin_tools和ament_tools的迭代。有关更多信息，详见 A universal build tool。
源码可在 Github 项目主页上找到。

先决条件

安装 Colcon （Liunx）

sudo apt install python3-colcon-common-extensions

安装 ROS 2

详见安装教程。

基础任务

ROS 工作空间是有特定结构的目录。通常有src子目录。ROS 包的源码将被存放在src子目录中。通常目录初始时为空。

colcon 会进行源代码构建。默认情况下它会在src目录同级创建以下目录：

• build目录将会用来存放中间文件。对于每个包，在bulid目录下都会创建一个子目录，例如在其中调用 CMake 。
• install目录是每个包的安装位置。默认情况下每个包将会被安装到不同的子目录。
• log目录用于存放每次调用 colcon 的日志记录信息。

提示：
在 colcon 中没有devel目录。

Create a workspace （创建一个工作空间）

首先，创建一个目录（ros2_ws）来存放工作空间（Liunx）：

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

此时，工作空间中只有一个空目录src：

.
└── src

1 directory, 0 files

Add some sources （添加一些文件）

让我们将示例仓库克隆到工作空间的src目录：

git clone https://github.com/ros2/examples src/examples -b iron

现在工作空间中应该有了 ROS 2 示例的源代码：

.
└── src
    └── examples
        ├── CONTRIBUTING.md
        ├── LICENSE
        ├── rclcpp
        ├── rclpy
        └── README.md

4 directories, 3 files

Source an underlay （添加底层）

重要的是，我们已经将安装好了的 ROS 2 添加到工作空间，这将为我们的工作区提供必要的构建依赖。这是通过添加二进制或是源代码安装的启动文件来实现的，这就是另一个 colcon 工作空间。我们把这个环境称为底层。

我们的工作空间，也就是ros2_ws，将会成为现有安装的 ROS 2 之上的叠加层。通常，当你计划迭代少量包时，建议使用覆盖层，而不是将所有包放入同一个工作区

Build the workspace （构建工作区）

注意：
假如你在 Windows 上构建包，你将会需要在 Visual Studio 环境中构建，详见 Building the ROS 2 Code

在工作空间的根目录中，运行colcon build。由于ament_cmake之类的构建类型不支持devel空间的概念，并需要安装包，colcon支持--symlink-install选项。这允许通过更改源空间中的文件（例如 Python 文件或其他非编译源文件）来更改已经安装的文件，以加快迭代速度。

colcon build --symlink-install

在构建完成后，我们应该能看到build，install和log目录：

.
├── build
├── install
├── log
└── src

4 directories, 0 files

Run tests （运行测试）

为了运行我们刚刚构建的包的测试，运行如下命令（Linux）：

colcon test

Soucre the environment （添加环境）

当 colcon 成功完成构建，将会输出到install目录。在你可以使用任何安装的可执行文件或是库之前，你将会需要把它们添加到你的 path 或是库 path。colcon 将会在install目录中生成 bash 或 bat 脚本以帮助环境配置。这些脚本将会在你的 path 或是 库 path 中添加所需的元素，以及包所提供的命令。

source install/setup.bash 

Try a demo （尝试示例）

在环境配置完后，我们可以运行 colcon 构建的可执行文件。让我们运行示例中的订阅者节点：

ros2 run examples_rclcpp_minimal_subscriber subscriber_member_function

在另一个终端中，让我们运行发布者节点（不要忘记添加启动文件）：

ros2 run examples_rclcpp_minimal_publisher publisher_member_function

你应该能看到发布者和订阅者的消息，数字也将会递增。

Create your own package （创建你自己的包）

colcon 使用 REP 149 中定义的package.xml规范 （同时支持 REP 140 ）。

colcon 支持多种构建类型。推荐的构建类型是ament_camke和ament_python。同时支持纯cmake包。

ament_python构建类型的示例是 ament_index_python_package，在此 setup.py 是主要构建入口。

ament_cmake构建类型的示例是demo_nodes_cpp，使用 Cmake作为构建工具。

为了方便，你可以使用ros2 pkg create工具来创建一个新包。

提示：
对于catkin用户，catkin_create_package是等效的。

Setup colcon_cd （设置 colcon_cd）

colcon_cd命令允许你快速将 shell 的工作目录更改为包目录。例如，colcon_cd some_ros_package将会将工作目录更改为~/ros2_ws/src/some_ros_package。

echo "source /usr/share/colcon_cd/function/colcon_cd.sh" >> ~/.bashrc
echo "export _colcon_cd_root=/opt/ros/iron/" >> ~/.bashrc

根据安装colcon_cd的方式以及你的工作空间的位置，上述说明可能会有所不同，详见 文档。为了在 Linux 和 macOS 中撤销这一设置，找到你系统 shell 启动文件的位置，并删除添加的路径以及命令。

Setup colcon tab completion （设置 colcon tab 补全）

colcon命令支持 bash 和 类bash 的 shell 中的命令补全，前提条件是colcon-argcomplete包被安装。

echo "source /usr/share/colcon_argcomplete/hook/colcon-argcomplete.bash" >> ~/.bashrc

根据安装colcon_cd的方式以及你的工作空间的位置，上述说明可能会有所不同，详见 [文档]https://colcon.readthedocs.io/en/released/user/installation.html)。为了在 Linux 和 macOS 中撤销这一设置，找到你系统 shell 启动文件的位置，并删除添加的路径以及命令。

小提示

• 如果您不想构建特定的包，请在目录中放置一个名为COLCON_IGNORE 的空文件，它将不会被索引。
• 如果要避免在 CMake 包中配置和构建测试，可以传递：--cmake-args -DBUILD_TESTING=0。
• 如果要从包运行单个特定测试：

colcon test --packages-select YOUR_PKG_NAME --ctest-args -R YOUR_TEST_IN_PKG