ROS2开篇入门--工作空间与 `colcon` 编译机制详解

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 环境。


很好的教程,使我的ROS2工作空间成功编译 :nerd_face: