Colcon 构建教程

目标： 使用 colcon 构建一个 ROS 2 工作空间。

教程级别： 初级

预计用时： 20 分钟

本教程简要介绍如何使用 colcon 创建并构建一个 ROS 2 工作空间。这是一个实践教程，并非用来替代核心文档。

背景

colcon 是对 ROS 构建工具 catkin_make、catkin_make_isolated、catkin_tools 和 ament_tools 的迭代改进。有关 colcon 设计的更多信息，请参阅此文档。

源代码可以在 colcon GitHub 组织中找到。

前置条件

安装 colcon

Ubuntu：

$ sudo apt install python3-colcon-common-extensions

RHEL：

$ sudo dnf install python3-colcon-common-extensions

macOS：

$ python3 -m pip install colcon-common-extensions

Windows：

$ pip install -U colcon-common-extensions

安装 ROS 2

要构建示例，你需要安装 ROS 2。

请按照安装指南进行操作。

注意：如果通过 deb 包安装，本教程需要 desktop 安装。

基础知识

ROS 工作空间（workspace）是一个具有特定结构的目录。通常其中会有一个 src 子目录，ROS 包的源代码就位于该目录中。在初始状态下，除了 src 目录外，工作空间是空的。

colcon 执行 out-of-source 构建（源外构建）。默认情况下，它会在 src 目录的同级创建以下目录：

build 目录用于存储中间文件。对于每个包，都会在其中创建一个子目录，例如在其中调用 CMake。
install 目录是每个包安装到的位置。默认情况下，每个包都会安装到单独的子目录中。
log 目录包含每次 colcon 调用的各种日志信息。

注意：与 catkin 相比，这里没有 devel 目录。

创建工作空间

首先，创建一个目录（ros2_ws）来作为我们的工作空间：

Linux：

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

macOS：

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

Windows：

$ md \dev\ros2_ws\src
$ cd \dev\ros2_ws

此时，工作空间包含一个空的 src 目录：

.
└── src

1 directory, 0 files

添加一些源代码

将 examples 仓库克隆到工作空间的 src 目录中：

$ git clone https://github.com/ros2/examples src/examples -b {REPOS_FILE_BRANCH}

现在工作空间应该包含 ROS 2 示例的源代码：

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

4 directories, 3 files

Source 一个 underlay（底层环境）

我们需要先 source 一个已有的 ROS 2 安装环境，以便为示例包提供必要的构建依赖，这一步非常重要。这可以通过 source 二进制安装或源码安装（即另一个 colcon 工作空间）提供的 setup 脚本来实现（参见安装指南）。我们将这个环境称为 underlay（底层环境）。

我们的工作空间 ros2_ws 将是现有 ROS 2 安装之上的一个 overlay（覆盖层）。一般来说，当你只需要对少量包进行迭代开发时，推荐使用 overlay，而不必将所有包都放在同一个工作空间中。

构建工作空间

注意：在 Windows 上构建包需要处于 Visual Studio 环境中，详情请参见 Building the ROS 2 Code。

在工作空间的根目录下，运行 colcon build。由于 ament_cmake 等构建类型不支持 devel 空间的概念，并要求包被安装，colcon 提供了 --symlink-install 选项。该选项允许通过修改 source 空间中的文件（例如 Python 文件或其他非编译资源）来更改已安装的文件，从而加快迭代速度。

Linux：

$ colcon build --symlink-install

macOS：

$ colcon build --symlink-install

Windows：

$ colcon build --merge-install

Windows 对路径长度有限制，因此 merge-install 会将所有路径合并到 install 目录中。在 Windows 上，创建符号链接需要特殊权限，因此默认不使用 --symlink-install。要使用它，你需要以管理员身份运行命令或在系统设置中启用开发者模式。

提示：运行 colcon build 可能会导致 CPU、内存和 I/O 受限的系统（例如 Raspberry Pi）出现屏幕和鼠标冻结，因此使用 --executor sequential 参数逐个构建包而不是并行构建可能会有所帮助。如需更多参数，请参阅 colcon 文档。

构建完成后，你将看到 build、install 和 log 目录：

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

4 directories, 0 files

运行测试

要运行刚刚构建的包的测试，请执行以下命令：

Linux：

$ colcon test

macOS：

$ colcon test

Windows：

请记住使用 x64 Native Tools Command Prompt for VS 2019 来执行以下命令，因为我们要构建一个工作空间。

$ colcon test --merge-install

你还需要在此处指定 --merge-install，因为我们在上面的构建中使用了它。

Source 环境

当 colcon 成功完成构建后，输出将位于 install 目录中。在使用任何已安装的可执行文件或库之前，你需要将它们添加到你的路径和库路径中。 colcon 会在 install 目录中生成 bash/bat 文件来帮助设置环境。这些文件会将所有必需的元素添加到你的路径和库路径中，并提供由各个包导出的任何 bash 或 shell 命令。

Linux：

$ source install/setup.bash

macOS：

$ . install/setup.bash

Windows：

在 Windows 命令行界面中：

$ call install\setup.bat

或者使用 PowerShell：

$ install\setup.ps1

尝试一个 demo

在 source 环境之后，我们就可以运行 colcon 构建的可执行文件了。运行 examples 中的一个订阅者节点：

$ ros2 run examples_rclcpp_minimal_subscriber subscriber_member_function

在另一个终端中，运行一个发布者节点（不要忘记 source setup 脚本）：

$ ros2 run examples_rclcpp_minimal_publisher publisher_member_function

你应该能看到发布者和订阅者的消息，数字在不断递增。

创建你自己的包

colcon 使用 REP 149 中定义的 package.xml 规范（也支持 format 2）。

colcon 支持多种构建类型。推荐的构建类型是 ament_cmake 和 ament_python。也支持纯 cmake 包。

ament_python 构建的一个示例是 ament_index_python 包，其中 setup.py 是构建的主要入口点。

像 demo_nodes_cpp 这样的包使用 ament_cmake 构建类型，并以 CMake 作为构建工具。

为方便起见，你可以使用 ros2 pkg create 工具基于模板创建新包。关于创建包以及如何使用 ros2 pkg create 的完整说明，请参阅接下来的教程：创建一个包。

注意：对于 catkin 用户来说，这相当于 catkin_create_pkg。

设置 `colcon_cd`

colcon_cd 命令允许你快速将 shell 的当前工作目录切换到某个包的目录。例如，colcon_cd some_ros_package 会快速将你带到 ~/ros2_ws/src/some_ros_package 目录。要设置 colcon_cd，你需要运行以下命令来修改你的 shell 启动脚本：

Linux：

$ echo "source /etc/profile.d/colcon_cd.sh" >> ~/.bashrc
$ echo "export _colcon_cd_root=/opt/ros/{DISTRO}/" >> ~/.bashrc

macOS：

$ echo "source /usr/local/share/colcon_cd/function/colcon_cd.sh" >> ~/.bashrc
$ echo "export _colcon_cd_root=~/ros2_install" >> ~/.bashrc

Windows：

暂不可用

根据你安装 colcon_cd 的方式以及工作空间的位置，上述说明可能会有所不同，请参阅文档了解更多详情。要在 Linux 和 macOS 上撤销此操作，请找到系统的 shell 启动脚本并移除追加的 source 和 export 命令。

设置 `colcon` tab 补全

colcon 命令支持 bash 及类 bash shell 的命令补全。必须安装 colcon-argcomplete 包，并且可能需要一些设置才能使其正常工作。

技巧

如果你不想构建某个特定的包，可以在该目录中放置一个名为 COLCON_IGNORE 的空文件，这样它就不会被索引。
如果你想避免在 CMake 包中配置和构建测试，可以传递：--cmake-args -DBUILD_TESTING=0。

如果你想从某个包中运行单个特定的测试：

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

设置 `colcon` mixins

各种命令行选项写起来比较繁琐，而且难以记忆。

例如，要将 CMake 构建类型更改为 debug，通常使用：

$ colcon build --cmake-args -DCMAKE_BUILD_TYPE=Debug

为了让常用的命令行选项更容易调用，该仓库提供了这些”快捷方式”。

要安装默认的 colcon mixins，请运行以下命令：

$ colcon mixin add default https://raw.githubusercontent.com/colcon/colcon-mixin-repository/master/index.yaml
$ colcon mixin update default

然后，尝试使用 debug mixin：

$ colcon build --mixin debug

更多详情，请参阅 colcon mixin repository。

Colcon 构建教程

背景

前置条件

安装 colcon

安装 ROS 2

基础知识

创建工作空间

添加一些源代码

Source 一个 underlay（底层环境）

构建工作空间

运行测试

Source 环境

尝试一个 demo

创建你自己的包

设置 colcon_cd

设置 colcon tab 补全

技巧

设置 colcon mixins

设置 `colcon_cd`

设置 `colcon` tab 补全

设置 `colcon` mixins