【ROS2】Beginner: Client libraries - 使用 colcon 构建功能包

原创于 2025-09-21 16:13:44 发布 · 863 阅读

22 ·

CC 4.0 BY-SA版权

文章标签：

#ROS2 #自动驾驶 #机器人

ROS2 从入门到进阶专栏收录该内容

20 篇文章

订阅专栏

使用 colcon 构建功能包

目标：使用 colcon 构建 ROS 2 工作空间。
难度级别：初学者
预计时间：20 分钟

本教程简要介绍如何使用 colcon 创建并构建 ROS 2 工作空间，以实践操作为核心，不替代官方核心文档。

背景
前提条件
1. 安装 colcon
2. 安装 ROS 2
基础概念
操作步骤
1. 创建工作空间
2. 添加源码
3. 加载底层环境（Underlay）
4. 构建工作空间
5. 运行测试
6. 加载环境变量
7. 测试示例程序
8. 创建自定义功能包
工具配置
1. 配置 colcon_cd
2. 配置 colcon 命令补全
实用技巧
1. 忽略指定功能包
2. 跳过测试构建
3. 运行单个测试
4. 配置 colcon 混合选项（Mixin）

背景

colcon 是在 ROS 传统构建工具（catkin_make、catkin_make_isolated、catkin_tools、ament_tools）基础上迭代开发的新一代构建工具。关于其设计理念与细节，可参考官方设计文档。

colcon 的源代码托管于 colcon GitHub 组织，开源且支持社区贡献。

前提条件

1. 安装 colcon

根据操作系统选择对应命令，安装 colcon 及常用扩展组件：

Linux：

sudo apt install python3-colcon-common-extensions

macOS：

python3 -m pip install colcon-common-extensions

Windows：

pip install -U colcon-common-extensions

2. 安装 ROS 2

构建示例功能包需先完成 ROS 2 安装，可参考 ROS 2 安装指南操作。

注意：若通过 deb 包（Linux 系统）安装，本教程需使用“桌面版”（desktop）安装包，以确保依赖完整。

基础概念

ROS 工作空间是具有固定结构的目录，核心包含 src 子目录——用于存放所有 ROS 功能包的源代码，初始状态下其他目录为空。

colcon 采用源码外构建（out-of-source build）模式，默认会在 src 目录的同级目录下创建 3 个文件夹，各有明确分工：

build：存储构建过程中的中间文件（如编译生成的目标文件、CMake 缓存等），每个功能包会在此目录下生成独立子目录；
install：存储功能包的最终安装文件（可执行程序、库、配置文件等），默认每个功能包对应独立子目录；
log：记录每次 colcon 命令的执行日志（构建进度、错误信息等），便于问题排查。

注意：与 catkin 工具不同，colcon 不生成 devel 目录。

操作步骤

1. 创建工作空间

首先创建工作空间根目录（命名为 ros2_ws）及核心的 src 子目录：

Linux / macOS：

mkdir -p ~/ros2_ws/src  # -p 确保父目录不存在时自动创建
cd ~/ros2_ws             # 进入工作空间根目录

Windows：

md \dev\ros2_ws\src      # 创建 src 子目录
cd \dev\ros2_ws          # 进入工作空间根目录

此时工作空间结构如下（仅含空的 src 目录）：

.
└── src
1 directory, 0 files

2. 添加源码

将 ROS 2 官方示例代码仓库克隆到 src 目录，并切换到 kilted 版本分支（与当前 ROS 2 发行版匹配）：

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

克隆完成后，工作空间结构更新为：

.
└── src
    └── examples
        ├── CONTRIBUTING.md  # 贡献指南
        ├── LICENSE          # 许可证文件
        ├── rclcpp           # C++ 示例功能包（如发布者/订阅者）
        ├── rclpy            # Python 示例功能包
        └── README.md        # 示例说明文档
4 directories, 3 files

3. 加载底层环境（Underlay）

需先加载已安装的 ROS 2 环境（称为“底层”，Underlay），为当前工作空间提供构建示例功能包所需的依赖（如 rclcpp、rclpy 等核心库）。加载方式为执行 ROS 2 安装目录下的环境配置脚本（具体路径需根据安装方式调整，参考 ROS 2 安装指南）。

当前创建的 ros2_ws 工作空间称为“叠加层”（Overlay），叠加在底层 ROS 2 环境之上。通常建议：仅对少量功能包进行迭代开发时使用叠加层，避免将所有功能包集中在一个工作空间中，以降低依赖管理复杂度。

4. 构建工作空间

注意：Windows 系统需在 Visual Studio 环境（如 x64 Native Tools Command Prompt for VS2019）中执行构建命令，否则会因编译工具缺失导致失败，详情参考 ROS 2 源码构建指南。

在工作空间根目录执行 colcon build 命令。对于 ament_cmake 等构建类型，需添加 --symlink-install 选项启用“符号链接安装”——修改源码（如 Python 脚本、配置文件等非编译资源）后，无需重新构建即可生效，大幅提升开发迭代效率：

Linux：
```
colcon build --symlink-install
```

macOS：

colcon build --symlink-install --merge-install

Windows：
由于 Windows 对文件路径长度有限制，需添加 --merge-install 选项，将所有功能包的安装文件合并到 install 目录下（避免路径过长报错）：
```
colcon build --symlink-install --merge-install
```

提示：在 CPU、内存或 I/O 资源有限的设备（如树莓派）上，并行构建可能导致系统卡顿甚至无响应，可添加 --executor sequential 选项改为“串行构建”（逐个构建功能包）：
colcon build --symlink-install --executor sequential
更多 colcon 命令参数可参考 colcon 官方文档。

构建完成后，工作空间根目录会生成 build、install、log 三个目录，结构如下：

.
├── build    # 中间构建文件目录
├── install  # 安装文件目录
├── log      # 日志目录
└── src      # 源码目录
4 directories, 0 files

5. 运行测试

执行以下命令，对刚构建的功能包运行自动化测试（验证功能包是否正常工作）：

Linux / macOS：
```
colcon test
```
Windows：
需在 x64 Native Tools Command Prompt for VS2019 终端中执行，且需与构建时一致，添加 --merge-install 选项：
```
colcon test --merge-install
```

6. 加载环境变量

colcon 构建成功后，所有可执行程序、库文件等均输出到 install 目录。使用这些文件前，需将其路径添加到系统环境变量中（如 PATH、LD_LIBRARY_PATH 等）。install 目录下已自动生成环境配置脚本，执行对应命令即可完成加载：

Linux：
```
source install/setup.bash
```

macOS：

. install/setup.bash  # 等效于 source 命令

Windows（命令提示符）：
```
call install\setup.bat
```
Windows（PowerShell）：
```
install\setup.ps1
```

7. 测试示例程序

加载环境变量后，即可运行 colcon 构建生成的可执行程序。以示例中的“C++ 发布者-订阅者”节点为例：

打开新终端，加载环境变量后运行订阅者节点：

ros2 run examples_rclcpp_minimal_subscriber subscriber_member_function

再打开一个新终端，加载环境变量后运行发布者节点：
```
ros2 run examples_rclcpp_minimal_publisher publisher_member_function
```

此时两个终端会分别输出消息：发布者终端持续发送递增数字的消息，订阅者终端接收并打印这些消息，验证功能包构建成功且可正常通信。

8. 创建自定义功能包

colcon 遵循 REP 149 定义的 package.xml 规范（同时兼容格式 2），支持多种构建类型，推荐优先使用以下两种：

ament_python：适用于 Python 功能包，以 setup.py 作为构建入口（如 ament_index_python 功能包）；
ament_cmake：适用于 C++ 功能包，基于 CMake 构建（如 demo_nodes_cpp 功能包）。

此外，colcon 也支持纯 cmake 功能包。

为简化操作，可使用 ros2 pkg create 工具基于模板快速创建新功能包（类似 catkin 工具的 catkin_create_package）。关于功能包创建的详细步骤及 ros2 pkg create 命令的用法，将在后续《创建功能包》（Create a Package）教程中详细介绍。

工具配置

1. 配置 `colcon_cd`

colcon_cd 是 colcon 的便捷工具，可快速将终端当前工作目录切换到指定功能包的源码目录。例如，执行 colcon_cd some_ros_package 后，终端会直接跳转至 ~/ros2_ws/src/some_ros_package（路径需根据实际工作空间位置调整）。

通过以下命令修改 shell 启动脚本（如 ~/.bashrc），完成 colcon_cd 配置：

Linux（假设 ROS 2 安装在 /opt/ros/kilted/）：

# 将 colcon_cd 功能脚本添加到 bash 启动项
echo "source /usr/share/colcon_cd/function/colcon_cd.sh" >> ~/.bashrc
# 设置 colcon_cd 的根目录（指向 ROS 2 安装目录）
echo "export _colcon_cd_root=/opt/ros/kilted/" >> ~/.bashrc

macOS（假设 ROS 2 安装在 ~/ros2_install）：

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

Windows：暂不支持 colcon_cd

注意：上述命令需根据 colcon_cd 的实际安装路径和 ROS 2 工作空间位置调整。若需撤销配置（Linux/macOS），可直接编辑 ~/.bashrc 文件，删除添加的 source 和 export 命令。

2. 配置 `colcon` 命令补全

colcon 支持 bash 及类 bash shell（如 zsh）的命令补全功能，输入 colcon 后按 Tab 键即可自动补全子命令或参数。需先安装 colcon-argcomplete 包，部分系统可能还需额外配置（具体步骤参考该包的官方文档）。

实用技巧

忽略指定功能包：若无需构建某个功能包，在该功能包的目录下创建空文件 COLCON_IGNORE 即可。colcon 会自动跳过该功能包的索引与构建。
跳过测试构建：对 CMake 功能包，若无需配置和构建测试代码，可在构建时添加 --cmake-args -DBUILD_TESTING=0 选项：
```
colcon build --symlink-install --cmake-args -DBUILD_TESTING=0
```
运行单个测试：若只需验证某个功能包中的特定测试，执行以下命令（将 YOUR_PKG_NAME 替换为功能包名，YOUR_TEST_IN_PKG 替换为测试名）：
```
colcon test --packages-select YOUR_PKG_NAME --ctest-args -R YOUR_TEST_IN_PKG
```
配置 colcon 混合选项（Mixin）：
部分常用命令行参数（如设置 CMake 构建类型为 Debug）输入繁琐且易遗忘，可通过“混合选项”（Mixin）创建快捷方式。
- 安装默认的 colcon 混合选项库：
```
# 添加默认混合选项仓库
colcon mixin add default https://raw.githubusercontent.com/colcon/colcon-mixin-repository/master/index.yaml
# 更新混合选项
colcon mixin update default
```
- 使用 debug 混合选项（等效于 --cmake-args -DCMAKE_BUILD_TYPE=Debug）：
```
colcon build --symlink-install --mixin debug
```