ROS 2 构建工具 colcon 使用指南

在 ROS 1 时代，我们习惯使用 catkin_make 或 catkin build。而在 ROS 2 中，colcon (collective construction) 成为了官方推荐的构建工具。它不仅支持 ROS 2，是一个通用的构建工具，旨在构建一组相互依赖的软件包。

本文将详细介绍 colcon 的安装、基础用法、常用参数及进阶技巧。

1. 安装 colcon

通常在安装 ROS 2 时，colcon 不会自动包含在核心库中，需要单独安装。

Ubuntu / Debian

sudo apt update
sudo apt install python3-colcon-common-extensions

注意：python3-colcon-common-extensions 是一个元包，它包含了构建、测试、自动补全等常用功能的扩展。

2. 基础构建流程

2.1 创建工作空间

在开始构建之前，确保你有一个标准的 ROS 2 工作空间结构：

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

2.2 编译所有包

在工作空间根目录下（~/ros2_ws），运行以下命令即可编译 src 目录下的所有包：

colcon build

2.3 构建产物

构建完成后，工作空间下会自动生成三个目录：

1. build/：存储中间构建文件（如 .o 文件、CMake 缓存）。每个包都有自己的子目录。
2. install/：存储最终的安装文件（可执行文件、库、脚本、Setup 文件）。
3. log/：存储构建日志，用于排查错误。

3. 常用构建参数

colcon build 提供了丰富的参数来满足不同的开发需求。

3.1 软链接安装 (Symlink Install) —— 最常用

默认情况下，colcon 会将文件复制到 install 目录。这意味着如果你修改了 Python 脚本或配置文件，必须重新编译才能生效。

使用 --symlink-install 参数可以创建软链接，修改 Python 代码或配置文件后无需重新编译即可生效（C++ 代码仍需重新编译）。

colcon build --symlink-install

3.2 编译指定的包

如果工作空间有很多包，全量编译会很慢。可以使用以下参数指定编译对象：

• 只编译特定包：

  colcon build --packages-select <package_name>

• 编译特定包及其依赖（递归编译）：

  colcon build --packages-up-to <package_name>

• 忽略特定包：

  colcon build --packages-ignore <package_name>

3.3 传递 CMake 参数

如果需要构建 Release 版本或传递宏定义，可以使用 --cmake-args：

# 编译 Release 版本（优化代码，去除调试信息）

3.4 显示实时日志

默认情况下，colcon 并行构建多个包，并隐藏输出以保持整洁。如果构建失败或需要调试，可以让输出直接打印到控制台：

colcon build --event-handlers console_direct+

3.5 遇到错误继续构建

默认情况下，如果一个包构建失败，colcon 会尝试完成正在进行的任务然后退出。

• --continue-on-error：即使某个包失败，也尝试构建其他不依赖于它的包。

4. 环境配置 (Sourcing)

构建完成后，必须配置环境变量才能让系统找到你编译的节点和库。

# Linux / macOS
# Linux / macOS
source install/setup.bash

# Windows
call install/setup.bat

技巧：可以将 source ~/ros2_ws/install/setup.bash 添加到你的 ~/.bashrc 文件中，以便每次打开终端自动加载。

5. 测试 (Test)

ROS 2 鼓励单元测试。colcon 提供了统一的测试入口。

5.1 构建并运行测试

colcon test

5.2 查看测试结果

测试完成后，可以使用以下命令查看摘要：

colcon test-result --all

如果想查看详细的错误信息：

colcon test-result --all --verbose

6. 清理工作空间

colcon 目前没有内置的 clean 命令（不像 catkin clean）。清理构建环境的标准做法是直接删除生成的目录：

rm -rf build/ install/ log/

7. 进阶配置与技巧

7.1 colcon_cd

这是一个非常实用的命令，允许你快速跳转到某个包的目录，而无需知道它的具体路径。 需在 .bashrc 中配置：

source /usr/share/colcon_cd/function/colcon_cd.sh
export _colcon_cd_root=~/ros2_ws

使用方法：

colcon_cd some_ros_package

7.2 自动补全

如果按 Tab 键没有补全 colcon 命令，请确保已加载补全脚本：

source /usr/share/colcon_argcomplete/hook/colcon-argcomplete.bash

7.3 全局配置 (mixin)

你可以通过 mixin 来简化长命令。例如，配置一个默认包含 --symlink-install 的别名。这通常需要安装 colcon-mixin 并配置相应的仓库。

8. 总结速查表

希望这份指南能帮助你更高效地使用 ROS 2 进行开发！