常用的 colcon build 参数

1. 安装方式#

• ​ ​--symlink-install​​
  使用符号链接安装文件，而不是复制。当你修改了 Python 脚本、配置文件或 launch 文件时，无需重新构建就能直接生效（对 Python 包、配置文件、launch 文件这类“改动频繁”的内容特别方便，但C++ 代码仍需重新编译）。开发调试时常用。
• ​ ​--merge-install​​
  将所有包安装到同一个 install/​ 目录下（类似 ROS 1 的结构），而不是默认的 install/<pkg_name>。某些场景下可以简化环境变量设置，不过通常推荐独立安装方式。

2. 包选择#

• ​ ​--packages-select​
  只构建指定的几个包，不处理其他包。
• --packages-up-to
  构建指定包以及它的所有递归依赖包。适合你只关心某个包和它依赖的包链。
• ​ ​--packages-above​
  构建所有直接或间接依赖于指定包的包（反向依赖）。用于检查改动影响哪些下游包。
• ​ ​--packages-skip​
  跳过指定包不构建，但其他包仍正常构建。

3. 构建过程控制#

• ​ ​--continue-on-error​
  即便某个包构建失败，也继续构建其他包，便于一次性发现问题包。
• ​ ​--executor sequential​
  强制顺序构建（默认会并行构建），方便调试依赖问题或排查编译顺序。
• ​ ​--parallel-workers N​​
  限制并行构建的任务数，避免资源紧张，例如 --parallel-workers 4。
• ​ ​--cmake-args​​
  将参数直接传递给 CMake，如：
  ​--cmake-args -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_FLAGS="-O2"
• ​ ​--ament-cmake-args​​
  将参数传递给 ament_cmake 构建系统（ROS 2 专用），用法同上。
• ​ ​--cmake-clean-cache​
  删除之前的 CMake 缓存，重新从头配置，相当于强制 clean 配置。
• ​ ​--cmake-force-configure​
  即使缓存存在，也强制重新运行 CMake 配置步骤。
• ​ ​--allow-overriding​ ​
  改变某个包的构建类型（例如把一个原本用 ament_cmake​ 的包强制当成纯 cmake 包来构建），在混用不同构建系统时有用。

4. 输出与事件处理#

• ​ ​--event-handlers​
  控制终端输出和通知行为。常用值：

  • ​console_direct+ – 直接在终端实时打印所有包的编译输出（不缓冲）。
  • ​console_cohesion+ – 每个包输出聚合显示（默认之一）。
  • ​desktop_notification-​ – 关闭桌面通知（构建完成/失败的通知）。
    示例：--event-handlers console_direct+

5. 测试相关#

• ​ ​--build-tests​​
  在构建过程中同时编译测试代码，后续才能运行 colcon test​。
  也可以直接用 CMake 参数开启：--cmake-args -DBUILD_TESTING=ON。

6. 工作空间路径#

• ​ ​--build-base​​
  指定构建中间文件存放目录，默认为工作空间下的 build/。
• ​ ​--install-base​ ​
  指定最终安装文件的存放目录，默认为 install/。
• ​ ​--paths​​
  指定包含 ROS 包的源代码目录，默认为 src/，如果你的包放在别处可以用它指定。

7. 其他#

• ​ ​--metas​
  使用一个元信息文件（meta file）来统一覆盖某些包的编译选项，适合复杂的混合工作空间。

常见场景示例#

• 日常开发最常用
  ​colcon build --symlink-install --packages-select my_package
• 重新全量构建（清除缓存）
  ​colcon build --cmake-clean-cache --cmake-force-configure
• 只构建某个包及其依赖，并实时查看输出
  ​colcon build --packages-up-to my_package --event-handlers console_direct+
• 以 Release 模式编译
  ​colcon build --cmake-args -DCMAKE_BUILD_TYPE=Release

掌握这些参数基本就能覆盖绝大部分开发和集成场景了。