【ROS2】Beginner: Client libraries - 使用 colcon 构建功能包
使用 colcon 构建功能包
目标：使用 colcon 构建 ROS 2 工作空间。
难度级别：初学者
预计时间：20 分钟
本教程简要介绍如何使用 colcon 创建并构建 ROS 2 工作空间，以实践操作为核心，不替代官方核心文档。
目录
- 背景
- 前提条件
- 安装 colcon
- 安装 ROS 2
- 基础概念
- 操作步骤
- 创建工作空间
- 添加源码
- 加载底层环境（Underlay）
- 构建工作空间
- 运行测试
- 加载环境变量
- 测试示例程序
- 创建自定义功能包
- 工具配置
- 配置
colcon_cd - 配置
colcon命令补全
- 配置
- 实用技巧
- 忽略指定功能包
- 跳过测试构建
- 运行单个测试
- 配置
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
- 安装默认的