ROS2系列教程：工作空间与colcon构建

本文是 ROS2 系列教程的第 3 篇本文是 ROS2 系列教程的第 3 篇工作空间与 colcon 构建。前两篇我们认识了节点与 ROS 图并运行了最简节点但那些脚本还只是散装的。本篇文章将建立 ROS2 工程的标准骨架工作空间Workspace、功能包Package与构建工具 colcon。学完本篇你就能创建自己的 ROS2 包并用ros2 run正式运行为后续话题、服务等通信篇目铺好工程基础。C 与 Python 两种包的构建方式都会讲到。一、为什么要工作空间与 colcon1.1 从散装脚本到工程化想象你写了 10 个节点脚本散落在不同目录有的用绝对路径引用有的依赖别人手动export PYTHONPATH有的改了代码却不生效……这就是散装开发。ROS2 用三件套解决这个问题工作空间Workspace所有包的统一存放目录包含src/build/install/log四个子目录。功能包PackageROS2 的最小可复用单元包含代码、依赖描述package.xml、构建规则CMakeLists.txt 或 setup.py。colconROS2 的官方构建工具负责编译、安装、生成环境变量。一句话概括工作空间管目录package 管单元colcon 管构建。三者配合让克隆一个包 → 构建 → 运行成为标准动作。1.2 工作空间的四目录结构ros2_ws/ # 工作空间名字可自定义习惯用 ros2_ws ├── src/ # 源代码目录放所有 package 源码 ├── build/ # 构建中间产物自动生成别手动改 ├── install/ # 安装结果可执行文件、库、Python 包source 这里 └── log/ # 构建日志自动生成四个目录的分工极其清晰目录内容是否手工维护说明src各 package 源码是你唯一需要写代码的地方buildCMake 中间文件、对象文件否colcon build自动生成install编译安装后的产物否必须source install/setup.bash才能用log构建与运行日志否排障时查看关键认知ROS2 不会自动看到src下的包必须经过colcon build把包安装到install目录再source install/setup.bash加载环境ros2 run才能找到你的可执行文件。1.3 colcon 与旧工具对比ROS1 时代构建工具是catkin_make/catkin_toolsROS2 官方推荐colcon。三者的核心差异特性catkin_makecatkin_toolscolcon推荐增量构建支持支持支持默认只构建指定包需-DCATKIN_WHITELIST_PACKAGES--pkg--packages-select多语言混合一般一般好CMake/Python/setuptools 统一日志管理单日志分包日志分包日志与 ROS2 契合否否是官方推荐colcon 是 CMake、Python setuptools、ament 等构建系统的统一前端它检测每个包的类型自动选择底层构建工具对外只暴露一致的命令行接口。二、创建第一个工作空间2.1 初始化工作空间# 创建工作空间骨架只需 src 目录其余自动生成mkdir-p~/ros2_ws/srccd~/ros2_ws# 在工作空间内编译src 为空也能构建生成 build/install/logcolcon build# 查看生成的结构ls-la此时会看到自动生成的build/、install/、log/三个目录。colcon build默认会递归扫描src下的所有 package 并逐个构建。2.2 source 环境变量构建完成后必须加载安装环境命令才能找到包source/opt/ros/humble/setup.bash# 系统级 ROS2 基础环境source~/ros2_ws/install/setup.bash# 工作空间级环境覆盖/追加注意顺序先 source 系统基础环境再 source 自己的工作空间。为了让每次打开终端都自动加载把这两行写入~/.bashrcechosource /opt/ros/humble/setup.bash~/.bashrcechosource ~/ros2_ws/install/setup.bash~/.bashrcsource~/.bashrcinstall/setup.bash本质上是在 PATH、PYTHONPATH、AMENT_PREFIX_PATH、LD_LIBRARY_PATH 等环境变量中追加本工作空间的路径。理解这一点对排障至关重要如果ros2 run报找不到包十有八九是没 source 或 source 顺序错了。2.3 环境变量速查# 查看当前已加载的所有 ROS2 包路径echo$AMENT_PREFIX_PATH# 查看可执行文件搜索路径应包含 install 目录echo$PATH# 查看 Python 模块搜索路径应包含 install 下的 Python 包echo$PYTHONPATH# 查看 ROS2 发行版echo$ROS_DISTRO# 输出 humble三、创建 Python 功能包3.1 用 ros2 pkg create 创建ROS2 提供了标准脚手架命令不要手动手写包结构容易出错cd~/ros2_ws/src# 创建 Python 包ros2 pkg create py_demo\--build-type ament_python\--node-name py_talker\--licenseApache-2.0\--maintainer-name your_name\--maintainer-email youremail.com\--descriptionA Python demo package生成的目录结构py_demo/ ├── package.xml # 包元数据名称、依赖、版本、许可 ├── setup.py # Python 包构建配置entry_points 是关键 ├── setup.cfg # 安装路径配置 ├── resource/py_demo # ament 索引标记文件 ├── test/ # 测试目录test_copyright.py 等 └── py_demo/ # Python 源码包与包同名 └── __init__.py3.2 理解 setup.py 的 entry_pointsPython 包的可执行入口由setup.py的entry_points定义这是ros2 run能找到命令的关键fromsetuptoolsimportsetupimportosfromglobimportglob package_namepy_demosetup(namepackage_name,version0.0.0,packages[package_name],data_files[# 把 launch 文件、config 安装到共享目录后面篇章用(share/ament_index/resource_index/packages,[resource/package_name]),(share/package_name,[package.xml]),(os.path.join(share,package_name,launch),glob(launch/*.launch.py)),],install_requires[setuptools],zip_safeTrue,maintaineryour_name,maintainer_emailyouremail.com,descriptionA Python demo package,licenseApache-2.0,entry_points{console_scripts:[# 格式命令名 模块路径:函数名py_talker py_demo.py_talker:main,py_listener py_demo.py_listener:main,],},)核心规则entry_points里的每一行cmd module:func定义了一个命令行命令。ros2 run py_demo py_talker就是执行py_demo.py_talker模块里的main()函数。3.3 编写节点并构建在py_demo/py_talker.py中写入# py_demo/py_talker.pyimportrclpyfromrclpy.nodeimportNodeclassPyTalker(Node):def__init__(self):super().__init__(py_talker)self.timerself.create_timer(1.0,self.tick)self.count0deftick(self):self.count1self.get_logger().info(fHello from py_talker #{self.count})defmain():rclpy.init()nodePyTalker()rclpy.spin(nod e)node.destroy_node()rclpy.shutdown()if__name____main__:main()构建与运行cd~/ros2_ws colcon build --packages-select py_demosourceinstall/setup.bash ros2 run py_demo py_talker看到每秒打印Hello from py_talker #N即成功。--packages-select只构建指定包大型工作空间下比全量构建快得多。四、创建 C 功能包4.1 创建 ament_cmake 包cd~/ros2_ws/src ros2 pkg create cpp_demo\--build-type ament_cmake\--node-name cpp_talker\--licenseApache-2.0\--maintainer-name your_name\--maintainer-email youremail.com\--descriptionA C demo packageC 包的结构cpp_demo/ ├── package.xml # 依赖声明这里会加 rclcpp ├── CMakeLists.txt # 构建规则核心 ├── include/cpp_demo/ # 头文件目录 └── src/ └── cpp_talker.cpp # 源文件4.2 理解 CMakeLists.txtC 包的一切构建规则都在CMakeLists.txt里核心四段cmake_minimum_required(VERSION 3.8) project(cpp_demo) # 1. 启用编译器特性 if(CMAKE_COMPILER_IS_GNUCXX OR CMAKE_CXX_COMPILER_ID MATCHES Clang) add_compile_options(-Wall -Wextra -Wpedantic) endif() # 2. 查找依赖rclcpp 是基础库必须声明 find_package(ament_cmake REQUIRED) find_package(rclcpp REQUIRED) # 3. 生成可执行文件目标名 源文件 add_executable(cpp_talker src/cpp_talker.cpp) # 4. 链接依赖库 安装缺一不可 ament_target_dependencies(cpp_talker rclcpp) install(TARGETS cpp_talker DESTINATION lib/${PROJECT_NAME}) ament_package()注意如果不写install(TARGETS ...)即使构建成功ros2 run也找不到可执行文件——因为产物没被安装到install目录。4.3 编写节点并构建src/cpp_talker.cpp// src/cpp_talker.cpp#includerclcpp/rclcpp.hpp#includechronoclassCppTalker:publicrclcpp::Node{public:CppTalker():Node(cpp_talker),count_(0){timer_this-create_wall_timer(std::chrono::seconds(1),std::bind(CppTalker::tick,this));}private:voidtick(){count_;RCLCPP_INFO(this-get_logger(),Hello from cpp_talker #%ld,count_);}rclcpp::TimerBase::SharedPtr timer_;longcount_;};intmain(intargc,char**argv){rclcpp::init(argc,argv);rclcpp::spin(std::make_sharedCppTalker());rclcpp::shutdown();return0;}构建运行cd~/ros2_ws colcon build --packages-select cpp_demosourceinstall/setup.bash ros2 run cpp_demo cpp_talker注意 C 与 Python 构建的差异C 需要编译耗时几秒到几十秒Python 是复制几乎瞬时。所以改 C 代码必须重新 build改 Python 代码同样要 build虽然快但可以用--symlink-install让 Python 包以软链接方式安装。五、colcon 常用选项精讲5.1 --packages-select只构建指定包# 只构建两个指定包colcon build --packages-select py_demo cpp_demo# 忽略某些包构建除 test_pkg 外的所有包colcon build --packages-ignore test_pkg大型工作空间几十个包时全量构建一次可能好几分钟用--packages-select精准构建改动的包能大幅提速。5.2 --symlink-installPython 开发神器colcon build --symlink-install这个选项让 Python 包以软链接方式安装到install目录改完代码不用重新 build直接运行即是新代码。C 包不受影响仍要编译。Python 开发强烈建议加这个选项。5.3 --cmake-args 与 --event-handlers# 向底层 CMake 传递参数比如 Debug 编译colcon build --cmake-args-DCMAKE_BUILD_TYPEDebug# 只显示错误信息减少刷屏colcon build --event-handlers console_direct21|grep-ierror5.4 常见构建问题速查现象原因解决Package xxx not found缺依赖未安装sudo apt install ros-humble-xxxros2 run找不到包没 source installsource install/setup.bashros2 run找不到命令entry_points 未配/未重新 build检查 setup.py 或 CMakeLists 的 install改了 Python 不生效没重新 buildcolcon build --packages-select 包名或加--symlink-installCommand colcon not found没装 colconsudo apt install python3-colcon-common-extensions构建报 CMake 缓存混乱缓存脏删除build/与install/对应包目录后重 build六、实战一个包含双语言包的工作空间6.1 完整演练流程# 1. 创建并初始化工作空间mkdir-p~/ros2_ws/srccd~/ros2_ws# 2. 创建 Python 包 C 包cdsrc ros2 pkg create py_demo --build-type ament_python --node-name py_talker--licenseApache-2.0 --maintainer-name you --maintainer-email youexample.com--descriptionpy demoros2 pkg create cpp_demo --build-type ament_cmake --node-name cpp_talker--licenseApache-2.0 --maintainer-name you --maintainer-email youexample.com--descriptioncpp democd..# 3. 按上文补全 py_talker.py 与 cpp_talker.cpp 内容# 4. 全量构建加 symlink 方便 Python 调试colcon build --symlink-install# 5. source 环境sourceinstall/setup.bash# 6. 双语言节点同时跑ros2 run py_demo py_talker# Python 节点ros2 run cpp_demo cpp_talker# C 节点运行后ros2 node list应能看到两个节点同时在线证明工作空间、双包、双语言全部打通。6.2 查看构建产物# 查看包是否被 ament 索引ros2 pkg list|grep-Epy_demo|cpp_demo# 查看包信息ros2 pkg prefix py_demo# 包安装位置ros2 pkg executables py_demo# 包内可执行命令# 查看包依赖树ros2 pkg xml py_demo# 打印 package.xml6.3 工作空间的管理建议每个包只做一件事话题包、服务包、工具包分开方便复用。package.xml 依赖要写全缺依赖在别的机器上构建直接失败。launch 文件放launch/目录并在setup.py/CMakeLists.txt中安装第 11 篇详讲。版本控制build/、install/、log/加入.gitignore只提交src/。七、总结本篇文章把 ROS2 从脚本提升到了工程理解了工作空间四目录结构、package 的概念与两种构建类型ament_python / ament_cmake掌握了 colcon 的完整用法并通过一个双语言实战工作空间验证了全链路。关键要点回顾工作空间 src源码build/install/log自动生成构建后必须source install/setup.bash。ros2 pkg create是创建包的唯一推荐方式别手写包结构。Python 包核心在setup.py的entry_pointsC 包核心在CMakeLists.txt的add_executable install(TARGETS)。colcon build --packages-select 包名精准构建--symlink-install让 Python 改完即用。排障第一招确认source顺序与环境变量AMENT_PREFIX_PATH。下一篇预告下一篇深入package 结构剖析逐字段讲解package.xml与CMakeLists.txt/setup.py的每个配置项介绍自定义消息/服务接口包ament_cmake的.msg/.srv定义与生成并对比 CMake 与 Python 两种包的异同。学完你能看懂任何开源 ROS2 包的目录结构也知道如何正确声明依赖。