功能包与依赖管理：ROS2 的交付单元

01问题引入：交付代码，怎么才不抓瞎

上一章 colcon build 你已经敲顺了，但每个源码目录里那份 package.xml 还一直没细看——今天就把它拆开。先换个角度想：把代码交给别人，怎么才能不靠嘴解释？各家生态早有答案了，都靠一份「说明书」：

说明书上写的就是三件事：我是谁、我依赖谁、别人该怎么构建我。ROS2 里它格外重要——一个工作空间几十个包，机器要靠这份说明书自动排序编译、补齐依赖、登记入口，同事拿到才知道先跑什么。这一章就走三步：看懂说明书（演示）→ 弄明白机器照着它编译时都干了啥（原理）→ 自己从零写一份、跑通（实操）。

02演示：拆开两个真实功能包

先不写代码。上一章工作空间里就躺着两个官方包，正好一 C++ 一 Python，拆开对着看，差别一目了然：

# ① C++ 那个：源码是 .cpp，构建说明书叫 CMakeLists.txt
ls ~/ros2_ws/src/xflz_eai_car1/ros2_demos/demo_nodes_cpp/
# package.xml  CMakeLists.txt  include/  src/

# ② Python 那个：没有 CMakeLists，换成 setup.py
ls ~/ros2_ws/src/xflz_eai_car1/ros2_demos/demo_nodes_py/
# package.xml  setup.py  setup.cfg  resource/  demo_nodes_py/

# ③ 两份"说明书"各看一眼（下面是节选对照）
cat ~/ros2_ws/src/xflz_eai_car1/ros2_demos/demo_nodes_cpp/package.xml
cat ~/ros2_ws/src/xflz_eai_car1/ros2_demos/demo_nodes_py/package.xml

# package.xml 主线字段：两边结构一样，只差几行依赖（节选）
<package format="3">
  <name>demo_nodes_cpp</name>                     # ← 我是谁
  <buildtool_depend>ament_cmake</buildtool_depend> # ← 用什么构建（py 包这里换成 ament_python）
  <depend>rclcpp</depend>                         # ← 依赖谁（py 包写 rclpy）
  <depend>std_msgs</depend>                       # ← 消息类型
  <export><build_type>ament_cmake</build_type></export>
</package>

03原理：从清单到 build / install

演示里两个包的差别看清了。现在回答最要紧的问题：在根目录敲下 colcon build 之后、到 ros2 run 能跑，中间机器到底干了什么？清单在每一步起什么作用——这条线走完，build/ 和 install/ 里为什么会多出东西，就全明白了。

先定调：两种构建类型

编译流程：一步清单 → 一个 build/ → 一份 install/

把依赖这条暗线画出来

依赖的生命周期：声明 → 解析 → 补装 → 链接；四个环节任一断裂都会在"链接成功"处报错。

读懂清单：字段与依赖的"生效阶段"

# 节选自真机 demo_nodes_cpp/package.xml（cat ~/ros2_ws/src/xflz_eai_car1/ros2_demos/demo_nodes_cpp/package.xml，真文件更长）
<package format="3">
  <name>demo_nodes_cpp</name>
  <version>…</version>                    # 版本/维护者/license 等四件套从略
  # ① 构建工具期：用什么构建我
  <buildtool_depend>ament_cmake</buildtool_depend>
  # ② 仅编译期（build_depend）：g++ 编代码时要用
  <build_depend>rclcpp</build_depend>
  <build_depend>std_msgs</build_depend>
  # ③ 仅运行期（exec_depend）：跑起来/launch 时才用
  <exec_depend>launch_ros</exec_depend>
  <exec_depend>rclcpp</exec_depend>
  # ④ 测试期（test_depend）：colcon test 才用
  <test_depend>ament_lint_auto</test_depend>
  <export><build_type>ament_cmake</build_type></export>
</package>

# 对照 demo_nodes_py/package.xml（同样节选）——rclpy、std_msgs 挂在 exec_depend 下：
# Python 不编译，不存在"仅编译期"要装而运行期不用的依赖，所以看不到 build_depend。
# 两个文件都可以真机 cat、再用 grep build_depend 对比着核对一遍

04实操 A：从零建包，跑通话题闭环

cd ~/ros2_ws/src                                        # ① 进 src 目录才能建包
ros2 pkg create my_test_pkg --build-type ament_python \
  --node-name hello_node --dependencies rclpy            # ② 生成骨架：package.xml + setup.py + hello_node.py
cd ~/ros2_ws && colcon build --packages-select my_test_pkg # ③ 回根目录编译，产物进 build/ 与 install/
source install/setup.bash                                # ④ 加载环境——不 source，下面两条都找不到这个包
# ⑤ 查"配料表"：列出该包里所有可被 ros2 run 启动的可执行文件
#   （两列输出 = 包名 + 可执行名，正是 run 第二参数的合法值；清单为空 → 先查③④）
ros2 pkg executables my_test_pkg   # → my_test_pkg hello_node
# ⑥ 按配料表启动
ros2 run my_test_pkg hello_node    # 输出 Hi from my_test_pkg. 后直接退出——模板只是 4 行 print 脚本，还不是真节点

create 是本章第一条要记熟的命令，拆开看各参数（建 C++ 包时完全一样，只把 --build-type 换成 ament_cmake）：

生成的模板文件其实只有 4 行 print——没 import rclpy、没有节点、没有 spin，所以打完就退出，ros2 node list 里自然也查不到它。现在把它改成真节点，每秒往 /chatter 发一条消息。这是第一次改代码，不整份重写——跟着三处改动做，每处都写清楚加什么、加在哪。

第 0 步，先看看现在的文件长什么样（一共就 4 行）：

cat ~/ros2_ws/src/my_test_pkg/my_test_pkg/hello_node.py
# def main():  print('Hi from my_test_pkg.')，加上两句入口调用——
# 没有 rclpy、没有节点、没有 spin，所以打完就退出，连 node list 都查不到

改动 1｜文件最顶部（def main 之前）加三行 import：

import rclpy
from rclpy.node import Node
from std_msgs.msg import String   # 缺模块时：sudo apt install ros-humble-std-msgs

改动 2｜紧接着 import 下面、def main 之前，加一个节点类——发布者和定时器都在这里：

class HelloNode(Node):
    def __init__(self):
        super().__init__('hello_node')
        self.pub = self.create_publisher(String, 'chatter', 10)  # 发布者：话题 chatter，队列 10
        self.timer = self.create_timer(1.0, self.tick)           # 每秒调一次 tick
        self.n = 0

    def tick(self):
        self.n += 1
        self.pub.publish(String(data=f'Hello World: {self.n}'))
        self.get_logger().info(f'发出: Hello World: {self.n}')

改动 3｜把原来整个 def main 函数换成下面这 4 行（print 换成初始化 + spin；spin 让进程停在这里持续发消息，不再打完就退）：

def main():
    rclpy.init()
    rclpy.spin(HelloNode())
    rclpy.shutdown()

# ⑦ 保存后重新编译、运行，用上一章的命令验收
cd ~/ros2_ws
colcon build --packages-select my_test_pkg   # 改了源码必须重编（--symlink-install 可省这步，见 EXP-03 第 03 节）
source install/setup.bash
ros2 run my_test_pkg hello_node              # 窗口 1：每秒打一条"发出: …"，保持运行

# 窗口 2：EXP-02 学的四条命令逐项验收
ros2 node list              # → /hello_node   节点活着
ros2 topic list             # → /chatter      话题在
ros2 topic echo /chatter    # → 每秒一条 data: 'Hello World: N'
ros2 topic hz /chatter      # → 约 1.0 Hz     频率对

四项全中，闭环完成：自己建包 → 改代码 → 选定包编译 → 运行 → 用上一章的工具验收。以后每个新包都走这一套，只是把 my_test_pkg 换成你自己的包名。

05实操 B：编译两个真包，对比 C++ 与 Python

不自己造包了，直接拿工作空间里现成的两个真包下手：demo_nodes_cpp 和 demo_nodes_py 干的是同一件事（话题 talker/listener），但构建类型一 C++ 一 Python——正好把原理那节说的"两条线"亲手走一遍。

# ① 回到工作空间根目录，先编 C++ 那个——真编译，build/ 里会堆出 .o
cd ~/ros2_ws
colcon build --packages-select demo_nodes_cpp
ls build/demo_nodes_cpp/CMakeFiles/   # 大堆 .o 中间产物——g++ 真的干活了

# ② 再编 Python 那个——没有 g++ 这一步，秒过
colcon build --packages-select demo_nodes_py
ls build/demo_nodes_py/               # 几乎是空的：流程照走，只是不真编译

# ③ source 后对比两层产物去了哪
source install/setup.bash
ls install/demo_nodes_cpp/lib/demo_nodes_cpp/    # C++：可执行文件装这里
ls install/demo_nodes_py/lib/demo_nodes_py/      # Python：入口脚本也汇到这里
ls install/demo_nodes_cpp/share/demo_nodes_cpp/  # 两边都有 share/：清单、launch 都在

# ④ 清单与 CMake 成对核对：depend 决定装谁、find_package 决定链谁
grep depend ~/ros2_ws/src/xflz_eai_car1/ros2_demos/demo_nodes_cpp/package.xml
grep find_package ~/ros2_ws/src/xflz_eai_car1/ros2_demos/demo_nodes_cpp/CMakeLists.txt

# ⑤ 各跑一个节点，确认真能用
ros2 run demo_nodes_cpp talker   # 另开窗口 ros2 topic echo /chatter 看得到
ros2 run demo_nodes_py talker

收口：清单里的 build_type 决定走哪条线（python 秒过 / cmake 真编译），depend 决定谁先编、缺了找谁，find_package 决定链接——三者对齐，包才健康。demo_nodes_cpp 和 demo_nodes_py 同样的功能、同样的验收方式，只有中间那段 build/ 产物完全不同：这就是原理节画的那条流程线跑在真包上的样子。

06自查：依赖标签选配器（按阶段分类）

07注意事项与验收清单

08本课总结与思考题