ROS2开篇入门–工作空间与 colcon 编译机制详解
1. 核心概念
ROS 2 的编译不是把整个工作空间当成一个巨大工程来处理,而是:
工作空间包含多个相互依赖的 ROS 2 Package,colcon 负责发现、排序、调度并调用每个 Package 自己的构建系统。
在常见场景中:
- C/C++ Package 使用
ament_cmake和 CMake; - Python Package 使用
ament_python和 setuptools; package.xml描述包的元信息和依赖;colcon是多包构建工具,不是具体的 C++ 编译器;rosdep负责解析并安装系统级或 ROS 级依赖。
可以把整个链路记成:
package.xml
↓
colcon 发现 Package
↓
解析依赖并建立有向图
↓
拓扑排序和并行调度
↓
调用 CMake / setuptools
↓
安装到 install/
↓
生成环境脚本
↓
source install/setup.bash
↓
ros2 run / ros2 launch
2. 工作空间目录结构
典型工作空间如下:
ros2_ws/
├── src/
│ ├── robot_msgs/
│ │ ├── package.xml
│ │ ├── CMakeLists.txt
│ │ └── msg/
│ ├── robot_driver/
│ │ ├── package.xml
│ │ ├── CMakeLists.txt
│ │ └── src/
│ └── robot_bringup/
│ ├── package.xml
│ ├── setup.py
│ └── launch/
├── build/
├── install/
└── log/
2.1 src/
保存源代码。ROS 2 社区约定把所有 Package 放在工作空间的 src/ 目录下,但 colcon 实际上可以递归搜索工作空间中的其他目录。
每个 Package 的根目录必须包含 package.xml,它既是 Package 的描述文件,也是 colcon 识别 Package 的重要标记。COLCON_IGNORE 文件则可以阻止某个目录被发现和构建。
2.2 build/
保存编译过程产生的中间文件,例如:
- CMake Cache;
- 编译目标;
.o、.a、.so等构建产物;- Python 构建临时文件;
- 每个 Package 的独立构建目录。
默认情况下,每个 Package 在 build/<package_name>/ 下拥有自己的构建目录。
2.3 install/
保存真正供运行时使用的安装结果,例如:
- 可执行文件;
- 动态库;
- Python 模块;
- launch、config、模型等资源;
- ROS 2 的 ament index;
setup.bash和local_setup.bash。
ROS 2 的 colcon 不采用 ROS 1 中传统的 devel 空间。Package 必须正确执行安装步骤,之后才能被环境脚本和 ROS 2 工具发现。
2.4 log/
保存每次构建和测试的日志:
log/
├── build_2026-07-16_10-30-00/
│ ├── events.log
│ ├── logger_all.log
│ └── robot_driver/
│ ├── command.log
│ ├── stdout_stderr.log
│ └── stderr.log
└── latest_build -> build_2026-07-16_10-30-00
构建失败时,Package 对应目录中的 stderr.log、stdout_stderr.log 和 command.log 通常比终端输出更完整。
3. package.xml 的作用
package.xml 是 ROS 2 Package 的清单文件,主要描述:
- 包名、版本、描述;
- 维护者和许可证;
- 构建工具;
- 编译依赖;
- 运行依赖;
- 测试依赖;
- Package 类型;
- 插件、接口生成器等扩展信息。
常见依赖标签:
<buildtool_depend>ament_cmake</buildtool_depend>
<build_depend>some_build_dependency</build_depend>
<build_export_depend>some_header_dependency</build_export_depend>
<exec_depend>some_runtime_dependency</exec_depend>
<test_depend>ament_cmake_gtest</test_depend>
<!-- 等价于 build + build_export + exec 依赖 -->
<depend>rclcpp</depend>
<depend> 在 Package Manifest Format 3 中相当于同时声明 <build_depend>、<build_export_depend> 和 <exec_depend>。依赖关系必须构成无环图,不能出现循环依赖。
需要注意:
<depend>rclcpp</depend>
只是在清单层面声明依赖。对于 CMake Package,通常仍然需要在 CMakeLists.txt 中写:
find_package(rclcpp REQUIRED)
package.xml 解决的是 ROS 包管理、依赖解析和构建排序;CMakeLists.txt 解决的是当前 CMake 工程如何查找、编译和链接依赖。
4. colcon build 的内部流程
执行:
colcon build
概念上会经历以下阶段。
4.1 阶段一:解析命令行参数
colcon 读取:
- 当前工作目录;
- 构建目录;
- 安装目录;
- Package 选择条件;
- executor 配置;
- CMake 或 Python 构建参数;
- 是否启用符号链接安装等。
4.2 阶段二:发现 Package
colcon 递归搜索工作空间,识别包含 package.xml 的目录,并判断 Package 的名称、路径和类型。
例如:
colcon list
colcon list --topological-order
输出通常包括:
/path/to/robot_msgs robot_msgs ament_cmake
/path/to/robot_driver robot_driver ament_cmake
/path/to/robot_bringup robot_bringup ament_python
如果某个包没有被列出来,应优先检查:
- 是否在工作空间根目录执行命令;
package.xml是否位于 Package 根目录;- 是否存在
COLCON_IGNORE; - Package 是否被
--packages-ignore排除。
4.3 阶段三:建立依赖图
假设:
robot_driver 依赖 robot_msgs
robot_bringup 依赖 robot_driver
依赖图为:
robot_msgs ───> robot_driver ───> robot_bringup
箭头表示“左侧必须先完成,右侧才能构建”。
colcon 根据 package.xml 中的依赖关系进行拓扑排序。没有依赖关系的 Package 可以并行构建;有依赖关系的 Package 必须等待依赖完成。并行执行器的最大并发数可以通过 --parallel-workers 控制,也可以使用顺序执行器进行逐包构建。
可以查看依赖图
colcon graph
colcon graph --legend
colcon graph --dot
4.4 阶段四:选择需要构建的 Package
依赖图建立后,colcon 再根据命令行参数选择实际需要处理的 Package。
例如:
colcon build --packages-select robot_driver
只选择 robot_driver。这个命令假设它的依赖已经被构建并且可用。
更常用的是:
colcon build --packages-up-to robot_driver
它会构建 robot_driver 以及它递归依赖的所有 Package。
如果修改了一个底层库,希望重新构建依赖它的上层 Package,可以使用:
colcon build --packages-above robot_msgs
常用选项如下:
| 参数 | 含义 |
|---|---|
--packages-select A |
只构建 A |
--packages-up-to A |
构建 A 以及 A 的所有依赖 |
--packages-above A |
构建 A 以及依赖 A 的 Package |
--packages-skip A |
跳过 A |
--packages-select-regex |
按正则表达式选择 |
--packages-select-build-failed |
选择上次构建失败的包 |
--packages-skip-build-finished |
跳过已经成功构建的包 |
这些参数可以组合使用,多个选择条件通常按逻辑 AND 处理。
4.5 阶段五:调用具体构建系统
colcon 不直接实现 CMake 或 setuptools 的编译逻辑,而是通过扩展调用对应的构建任务。
4.5.1 ament_cmake
典型流程是:
CMake configure
↓
CMake build
↓
CMake install
↓
ament index / environment hooks
典型的 CMakeLists.txt:
cmake_minimum_required(VERSION 3.8)
project(robot_driver)
find_package(ament_cmake REQUIRED)
find_package(rclcpp REQUIRED)
add_executable(driver_node src/driver_node.cpp)
ament_target_dependencies(driver_node rclcpp)
install(
TARGETS driver_node
DESTINATION lib/${PROJECT_NAME}
)
ament_package()
ament_package() 通常应调用一次,并放在 CMakeLists.txt 的末尾。它负责安装 package.xml、注册 ament index,并生成供其他 Package 使用的 CMake 配置。
4.5.2 ament_python
Python Package 通常通过 setuptools 安装 Python 模块和命令行入口:
package.xml
setup.py
setup.cfg
resource/<package_name>
<package_name>/
├── __init__.py
└── node.py
setup.py 中的 console_scripts 会生成可被 ros2 run 查找的可执行入口,例如:
entry_points={
'console_scripts': [
'driver_node = robot_driver.node:main',
],
}
Python Package 还需要安装 package.xml 和 ament index 的资源标记文件,否则 ROS 2 工具可能无法识别该包。
4.6 阶段六:安装并生成环境脚本
每个 Package 编译成功后,输出会安装到 install/,随后 colcon 生成工作空间级别的环境脚本。
主要脚本区别:
install/local_setup.bash
install/setup.bash
local_setup.bash:只加载当前安装前缀中的 Package;setup.bash:先加载父级工作空间,再加载当前工作空间。
这些脚本会更新 PATH、PYTHONPATH、CMAKE_PREFIX_PATH、动态库搜索路径以及 ROS 2 Package 的环境 Hook。
5. Underlay 与 Overlay
ROS 2 工作空间可以层层叠加。
系统 ROS 2 安装
↓ underlay
基础工作空间
↓ underlay
项目工作空间
↓ overlay
实验工作空间
- Underlay:底层工作空间,为上层提供依赖;
- Overlay:当前正在开发的工作空间;
- Overlay 中的同名 Package 通常会优先于 Underlay 中的版本。
例如:
source /opt/ros/<distro>/setup.bash
cd ~/ros2_ws
colcon build --symlink-install
构建完成后,在新的终端中:
source /opt/ros/<distro>/setup.bash
source ~/ros2_ws/install/local_setup.bash
或者直接:
source ~/ros2_ws/install/setup.bash
对于构建 Overlay,必须先让 Underlay 环境可见,因为 Overlay 的 Package 可能依赖 Underlay 中的 ROS 2 Package。官方文档还建议在新的终端中加载 Overlay,避免在已经加载过自身 Overlay 的终端里再次构建。
6. 常用构建选项
6.1 --symlink-install
colcon build --symlink-install
尽可能使用符号链接代替复制文件到 install/。
它对以下内容特别有用:
- Python 源码;
- launch 文件;
- YAML 配置;
- URDF、RViz、模型等非编译资源。
修改这些文件后,通常不需要重新执行完整安装步骤。C/C++ 源码或生成代码发生变化时,仍然需要重新编译。
6.2 --merge-install
colcon build --merge-install
默认情况下是 isolated workspace:
install/
├── pkg_a/
├── pkg_b/
└── pkg_c/
使用 --merge-install 后:
install/
├── bin/
├── lib/
├── share/
└── setup.bash
优点:
- 环境变量中的路径更短;
- Windows 等环境下更不容易遇到路径长度限制。
缺点:
- Package 之间的安装隔离变弱;
- 未声明的依赖更容易被意外“借用”;
- 可能掩盖
package.xml中缺失的直接依赖。
6.3 控制并行度
colcon build --parallel-workers 4
顺序构建:
colcon build --executor sequential
调试构建过程时,顺序构建通常更容易阅读日志。并行构建则更适合大型工作空间。
6.4 传递 CMake 参数
colcon build \
--cmake-args \
-DCMAKE_BUILD_TYPE=RelWithDebInfo
强制重新配置 CMake:
colcon build --cmake-force-configure
清除某个 Package 的 CMake Cache:
colcon build \
--packages-select robot_driver \
--cmake-clean-cache
6.5 构建失败后继续处理其他包
colcon build --continue-on-error
这会继续构建互不依赖的其他 Package,但依赖失败 Package 的上层 Package 仍然会被跳过。
7. 推荐的标准工作流
# 1. 进入工作空间根目录
cd ~/ros2_ws
# 2. 加载 ROS 2 Underlay
source /opt/ros/<distro>/setup.bash
# 3. 安装外部依赖
rosdep install \
--from-paths src \
--ignore-src \
-r -y
# 4. 检查 Package 是否被发现
colcon list
# 5. 查看依赖图
colcon graph --legend
# 6. 编译
colcon build --symlink-install
# 7. 在新的终端中加载工作空间
source /opt/ros/<distro>/setup.bash
source ~/ros2_ws/install/local_setup.bash
# 8. 运行测试
cd ~/ros2_ws
colcon test
colcon test-result --all
colcon 负责构建和测试,但并不负责自动下载源码或安装外部依赖;外部依赖通常由 rosdep、系统包管理器或其他工具处理。
8. 常见问题定位
8.1 colcon list 看不到 Package
检查:
colcon list
重点排查:
- 当前是否在工作空间根目录;
- Package 根目录是否有
package.xml; - 是否存在
COLCON_IGNORE; - 是否被
--packages-ignore忽略; package.xml是否格式错误。
8.2 编译成功但 ros2 run 找不到
通常是:
- 没有 source
install/setup.bash; - CMake 中没有
install(TARGETS ...); - Python 中没有配置
console_scripts; - 使用了错误的终端或错误的工作空间。
可以检查:
ros2 pkg prefix <package_name>
ros2 pkg executables <package_name>
8.3 find_package(...) 失败
检查顺序:
source /opt/ros/<distro>/setup.bash
rosdep install --from-paths src --ignore-src -r -y
然后确认:
package.xml声明了依赖;CMakeLists.txt中存在对应的find_package;- 依赖 Package 确实已经安装或构建;
- 当前使用的 ROS 2 发行版没有混用。
8.4 修改了 CMake 但行为没有变化
可以尝试:
colcon build \
--packages-select <package_name> \
--cmake-clean-cache
如果 Package 名称、构建类型、安装路径发生过较大变化,可以删除该 Package 的:
build/<package_name>/
install/<package_name>/
不要删除 src/ 中的源代码。
8.5 依赖顺序异常
不要依赖“传递依赖”碰巧可用。每个 Package 都应在 package.xml 中声明自己直接使用的依赖。默认 isolated workspace 可以帮助暴露这类遗漏,因为测试环境只提供已声明的依赖。
9. 最重要的三个区别
9.1 colcon、CMake、ament 的关系
colcon 管理多个 Package,负责发现、排序、调度
CMake 构建单个 C/C++ Package
ament_cmake 为 CMake 增加 ROS 2 的安装、索引和环境能力
Python 场景则类似:
colcon 管理多个 Package
setuptools 构建和安装 Python Package
ament_python 规定 ROS 2 Python Package 的安装和索引方式
9.2 build/ 与 install/ 的区别
build/ 编译过程的中间结果
install/ 运行时真正使用的结果
构建成功不等于当前终端已经能使用 Package,通常还需要:
source install/setup.bash
9.3 setup.bash 与 local_setup.bash 的区别
local_setup.bash 只加载当前工作空间
setup.bash 加载父级 Underlay,再加载当前工作空间
总结来说:
package.xml 描述依赖,colcon 组织构建,CMake/setuptools 实际构建,install/ 提供运行结果,setup.bash 把这些结果放进当前 Shell 环境。
