rosbag2 源码详细分析

工作区路径：/home/cp/work2/ros2Learn/ros2_humble/src/ros2/rosbag2
版本：0.15.16（Humble），子包 19 个，许可证 Apache 2.0。

rosbag2 是 ROS 2 录制与回放 的完整实现栈：可插拔存储后端（SQLite3 / MCAP）、消息/文件级压缩、序列化格式转换、C++/Python API，以及通过 ros2 bag 暴露的 CLI。设计文档见 ros2/design rosbags。

范围说明：本仓库不含 ROS 1 bag 读取插件（rosbag2_bag_v2 在独立仓库）；Humble 默认安装 sqlite3 + zstd 插件，MCAP 需额外安装 rosbag2_storage_mcap。

1. 总体认识

1.1 核心职责

1.2 在 ROS 2 栈中的位置

1.3 命令行分层（与 ros2cli 集成）

1
2
3
4
5
6
7
8

ros2                          ← ros2cli 主入口
  └── bag                     ← entry point: ros2bag.command.bag:BagCommand
        ├── record            ← ros2bag.verb.record:RecordVerb
        ├── play              ← ros2bag.verb.play:PlayVerb
        ├── info              ← ros2bag.verb.info:InfoVerb
        ├── convert           ← ros2bag.verb.convert:ConvertVerb
        ├── reindex           ← ros2bag.verb.reindex:ReindexVerb
        └── list              ← ros2bag.verb.list:ListVerb

ros2bag/setup.py 通过 setuptools entry_points 注册；BagCommand 使用 add_subparsers_on_demand 按需加载 verb 插件，与 ros2 topic 等命令模式一致。

2. 仓库结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

rosbag2/
├── README.md                          # 用户文档（record/play/split/compression/convert）
├── rosbag2/                           # ★ metapackage 0.15.16
├── rosbag2_storage/                   # ★ 存储抽象 (~2500 行 C++)
│   ├── include/rosbag2_storage/
│   │   ├── storage_interfaces/        # ReadOnly / ReadWrite / BaseWrite
│   │   ├── serialized_bag_message.hpp
│   │   ├── bag_metadata.hpp
│   │   ├── topic_metadata.hpp
│   │   ├── storage_options.hpp
│   │   └── storage_factory.hpp
│   └── src/.../storage_factory_impl.hpp # pluginlib 加载逻辑
├── rosbag2_storage_default_plugins/   # SQLite3 插件
├── rosbag2_storage_mcap/            # MCAP 插件
├── rosbag2_cpp/                       # ★ 核心 API (~9400 行)
│   ├── writer.hpp / reader.hpp
│   ├── writers/sequential_writer.cpp
│   ├── readers/sequential_reader.cpp
│   ├── cache/message_cache.hpp        # 双缓冲写缓存
│   └── reindexer.cpp
├── rosbag2_compression/               # 压缩读写包装 (~3100 行)
├── rosbag2_compression_zstd/          # zstd compressor 插件
├── rosbag2_transport/                 # ★ Recorder/Player (~8600 行)
│   ├── recorder.cpp / player.cpp
│   ├── bag_rewrite.cpp
│   └── reader_writer_factory.cpp
├── rosbag2_py/                        # Python 绑定
├── ros2bag/                           # CLI (Python)
├── rosbag2_interfaces/                # msg/srv 定义
├── sqlite3_vendor / zstd_vendor / mcap_vendor / shared_queues_vendor
├── rosbag2_tests / rosbag2_test_common
└── rosbag2_performance/               # 性能基准

2.1 子包一览

3. 三层插件体系

rosbag2 的可扩展性来自 三类独立插件，均通过 pluginlib 或工厂模式注册：

3.1 存储插件 (Storage)

基类：rosbag2_storage::storage_interfaces::ReadWriteInterface（读写合一）
只读变体：ReadOnlyInterface（部分插件可只读打开）

加载路径（storage_factory_impl.hpp）：

1. 若 storage_options.storage_id 非空 → 按 ID 加载对应 class（如 sqlite3、mcap）
2. 若为空且为 读 → 遍历已注册插件，逐个 open() 尝试，首个成功者选用
3. 读模式下若 ReadOnly 插件失败 → 回退尝试 ReadWrite 插件以 READ_ONLY 打开

1
2
3
4

<!-- rosbag2_storage_default_plugins/plugin_description.xml -->
<class name="sqlite3"
       type="rosbag2_storage_plugins::SqliteStorage"
       base_class_type="rosbag2_storage::storage_interfaces::ReadWriteInterface"/>

SQLite3 实现要点（sqlite_storage.cpp）：

• 表结构存储 topic metadata 与 serialized message blob
• 支持 storage_config_uri YAML 配置 SQLite pragma（read/write 分节）
• get_minimum_split_file_size() 返回最小 split 阈值（默认约 86KB，与 CLI -b 说明一致）
• 支持 IOFlag::READ_ONLY / READ_WRITE / APPEND

MCAP（rosbag2_storage_mcap）：面向 robotics 日志的单文件格式，索引与 Foxglove Studio 兼容；通过 --storage mcap 选用。

3.2 序列化格式转换 (Serialization Converter)

目的：bag 内存储的序列化格式可与录制时 RMW 格式不同（如 cdr ↔ protobuf 实验性路径）。

• ConverterOptions：input_serialization_format / output_serialization_format
• SerializationFormatConverterFactoryInterface 加载 *_converter 插件
• SequentialWriter::open() 若输入/输出格式不同则创建 converter_，在 write() 路径转换

Recorder 打开 writer 时传入：

1
2

writer_->open(storage_options_,
  {rmw_get_serialization_format(), record_options_.rmw_serialization_format});

即：输入为当前 RMW 格式，输出为 CLI --serialization-format 指定格式（默认同 RMW）。

3.3 压缩插件 (Compression)

配置（compression_options.hpp）：

工厂选择（reader_writer_factory.cpp）：

• 录制：compression_format 非空 → SequentialCompressionWriter 包装 SequentialWriter

• 回放：读 metadata.yaml 中 compression_format 非空 → SequentialCompressionReader

• MESSAGE 模式：每条消息压缩后写入 storage

• FILE 模式：关闭 bag 文件时对整文件压缩（split 时按文件压缩）

4. 数据模型

4.1 SerializedBagMessage

单条 bag 消息的最小单元（serialized_bag_message.hpp）：

1
2
3
4
5

struct SerializedBagMessage {
  std::shared_ptr<rcutils_uint8_array_t> serialized_data;
  rcutils_time_point_value_t time_stamp;  // 纳秒时间戳
  std::string topic_name;
};

• 不做 ROS 类型反序列化；payload 为 RMW 序列化字节流
• Recorder 从 rclcpp::SerializedMessage 拷贝 buffer 与时间戳写入

4.2 TopicMetadata

1
2
3
4
5
6

struct TopicMetadata {
  std::string name;
  std::string type;                    // 如 sensor_msgs/msg/Image
  std::string serialization_format;    // 如 cdr
  std::string offered_qos_profiles;    // YAML 序列化的 QoS 列表
};

回放时 Player 用 metadata 中的 type 创建 GenericPublisher，并按 recorded QoS（或 override）发布。

4.3 BagMetadata 与 metadata.yaml

BagMetadata（bag_metadata.hpp，version = 5）：

MetadataIo 负责读写 bag 目录下的 metadata.yaml；SequentialReader 打开时先读 metadata，再按 relative_file_paths 解析分片路径（version < 4 的路径规则不同，见 resolve_relative_paths）。

典型目录结构：

1
2
3
4

my_bag/
├── metadata.yaml
├── my_bag_0.db3          # sqlite3 分片
└── my_bag_0.db3.zstd     # FILE 压缩时可能出现

4.4 StorageOptions

录制/回放/convert 共用（storage_options.hpp）：

5. rosbag2_cpp：读写核心

5.1 Writer 门面

rosbag2_cpp::Writer 持有 BaseWriterInterface 实现（默认 SequentialWriter），提供：

• open(storage_options, converter_options)
• create_topic / remove_topic
• write(SerializedBagMessage) 或 write(SerializedMessage, topic, type, time)
• take_snapshot()（snapshot 模式）
• add_event_callbacks（如 split 事件）

线程安全：Writer 层有 mutex，防止并发 open/close/write 竞态。

5.2 SequentialWriter 流程

1. open()：storage_factory_->open_read_write() 创建插件实例
2. init_metadata()：初始化 BagMetadata，记录首个相对路径
3. create_topic()：写 topic 行到 storage + 更新 metadata
4. write()：
   • 可选 converter 转换序列化格式
   • 若 max_cache_size > 0 → MessageCache 双缓冲；否则直接 storage_->write()
   • 更新 duration、message_count
5. close()：刷 cache、写最终 metadata.yaml

Split 逻辑：当单文件 size 或 duration 超阈值，关闭当前 storage、新建分片文件，更新 relative_file_paths，触发 write_split_callback（Recorder 发布 WriteSplitEvent）。

默认常量：

1

static constexpr char const * kDefaultStorageID = "sqlite3";

5.3 MessageCache（双缓冲）

message_cache.hpp 实现 greedy consumer 双缓冲：

• Producer（subscription 回调）push 到主 buffer
• Consumer（磁盘写入线程）swap_buffers 取走数据
• buffer 满时 丢弃 消息并计数（性能告警信号）
• flush 状态用于 shutdown 时排空

设计目标：避免慢速磁盘阻塞 DDS 回调线程。

5.4 SequentialReader 流程

1. open()：读 metadata → 打开首个 storage 分片
2. has_next() / read_next()：顺序返回 SerializedBagMessage
3. 当前分片读完 → 自动打开 relative_file_paths 中下一个
4. 支持 seek(timestamp)、set_filter(StorageFilter)（topic 白名单）
5. 若存在 converter，读出的消息可转换为目标序列化格式

5.5 Reindexer

当 metadata.yaml 损坏或与 .db3 不一致时，Reindexer::reindex() 扫描目录内数据库文件，重建 metadata（reindexer.cpp）。CLI：ros2 bag reindex。

6. rosbag2_transport：录制路径

6.1 Recorder 架构

Recorder 继承 rclcpp::Node，核心成员：

• Writer（通过 ReaderWriterFactory::make_writer 创建，可能为压缩 writer）
• subscriptions_：GenericSubscription 映射
• topics_discovery 异步线程（除非 --no-discovery）
• paused_ 原子标志
• snapshot 模式下的 ~/snapshot 服务

6.2 record() 主流程

1
2
3
4
5
6
7

record()
  ├─ writer_->open(storage_options, converter_options)
  ├─ [snapshot_mode] 创建 Snapshot 服务
  ├─ 注册 write_split 回调 → 发布 WriteSplitEvent
  ├─ subscribe_topics(初始 topic 集)
  ├─ [可选] std::async topics_discovery 循环
  └─ 等待 spin（CLI 侧 rclpy/py 驱动 executor）

6.3 订阅与写入

关键顺序（避免竞态）：

1
2
3
4
5
6
7

void Recorder::subscribe_topic(const TopicMetadata & topic) {
  writer_->create_topic(topic);   // 必须先注册 topic
  auto sub = create_generic_subscription(..., [this](SerializedMessage msg) {
    if (!paused_.load())
      writer_->write(msg, topic_name, topic_type, get_clock()->now());
  });
}

QoS 适配：

• 默认 Rosbag2QoS::adapt_request_to_offers() 根据 publisher 的 offered QoS 选择 subscription QoS
• --qos-profile-overrides-path 可 per-topic 覆盖
• discovery 过程中若新 publisher QoS 与已订阅不兼容，会 warn_if_new_qos_for_subscribed_topic

Topic 选择：

• 显式 topic 列表、-a（全部）、-e / -x 正则过滤
• get_requested_or_available_topics() 合并请求与图发现结果
• --include-hidden-topics / --include-unpublished-topics 扩展发现范围

Sim time：use_sim_time 时 Recorder 使用 /clock；在收到首个 clock 前不应写消息（README 警告 time=0 问题）。

键盘控制：空格切换 pause/resume（keyboard_handler）。

7. rosbag2_transport：回放路径

7.1 Player 架构

• Reader + TimeControllerClock（速率、pause、seek）
• moodycamel::ReaderWriterQueue 预读队列（read_ahead_queue_size，默认 1000）
• GenericPublisher per topic
• 可选 /clock 定时发布（clock_publish_frequency）
• 控制服务：pause、resume、toggle_paused、set_rate、seek、burst、play_next 等（rosbag2_interfaces）

7.2 play() 主流程

1
2
3
4
5
6
7
8
9
10

play()
  loop (若 play_options_.loop):
    ├─ [delay] sleep
    ├─ reader_->seek(starting_time_); clock_->jump(...)
    ├─ async load_storage_content()  // 后台读 bag 填队列
    ├─ wait_for_filled_queue()
    ├─ play_messages_from_queue()
    │     └─ clock_->sleep_until(msg.timestamp)  // 节奏控制
    │     └─ generic_publisher->publish(serialized)
    └─ [可选] wait_for_all_acked

时间控制：TimeControllerClock 用 steady clock 映射 bag 时间戳，支持 rate 倍速、pause、seek。

QoS：默认从 bag metadata 恢复；PlayOptions::topic_qos_profile_overrides 可覆盖。

Remapping：topic_remapping_options 支持回放时改名。

8. bag_rewrite 与 convert

rosbag2_transport::bag_rewrite()（bag_rewrite.hpp）是 通用 bag 变换引擎：

输入：多个 StorageOptions（多个源 bag）
输出：多个 (StorageOptions, RecordOptions) 对（目标 bag 配置）

能力组合：

CLI：ros2 bag convert -i input_options.yaml -o output_options.yaml
Python：rosbag2_py.bag_rewrite()
C++：rosbag2_transport::bag_rewrite()

9. rosbag2_py 与 ros2bag CLI

9.1 pybind11 模块（_transport.cpp 等）

暴露类型：

• StorageOptions / RecordOptions / PlayOptions
• Recorder / Player
• bag_rewrite / Reindexer / Info
• get_registered_writers() / get_registered_compressors() 等 introspection

RecordVerb 典型用法：

1
2
3

from rosbag2_py import Recorder, RecordOptions, StorageOptions
recorder = Recorder('my_recorder', '', None)
recorder.record(storage_options, record_options)

CLI 解析参数后构造 C++ 对象，在 Python 侧 rclpy.spin 或直接调用阻塞式 record()。

9.2 各 verb 职责

10. rosbag2_interfaces

Recorder 发布 events/write_split；Player 提供 playback 控制服务（默认 namespace 下）。

11. 高级功能摘要

11.1 Bag splitting

• CLI：-b 字节阈值、-d 秒阈值
• 二者同时启用时 先触达者 split
• SequentialWriter 负责切换文件；metadata 记录所有分片

11.2 Snapshot 模式

• StorageOptions.snapshot_mode = true
• Writer 维护环形缓冲，仅保留最近 N 消息
• 调用 ~/snapshot 服务将缓冲 flush 到磁盘

11.3 QoS override 文件

YAML 指定 topic → QoS profile，用于录制订阅或回放发布，解决 recorded QoS 与当前系统不匹配问题。

11.4 性能相关选项

• max_cache_size：录制写缓存
• compression_queue_size / compression_threads：压缩流水线
• read_ahead_queue_size：回放预读
• SQLite storage_config_uri pragma tuning（如 WAL、synchronous）

12. 与 ROS 1 rosbag 对比

ROS 1 bag 直接读取需额外 rosbag2_bag_v2 插件（本仓库不含）。

13. 端到端序列图

13.1 录制

13.2 回放

14. 调试与常见问题

日志：各层使用 ROS_BAG_LOG / RCLCPP_*；storage 层 ROSBAG2_STORAGE_LOG_*。

实用命令：

1
2
3
4

ros2 bag info my_bag
ros2 bag list                    # 已注册 storage/compressor
ros2 bag record -a --storage mcap
ros2 bag play my_bag --rate 2.0 --clock 100

15. 源码阅读顺序

1. 数据模型：serialized_bag_message.hpp → topic_metadata.hpp → bag_metadata.hpp → storage_options.hpp
2. 插件加载：storage_factory_impl.hpp → plugin_description.xml（sqlite3）
3. 写路径：writer.hpp → sequential_writer.cpp → message_cache.hpp
4. 读路径：reader.hpp → sequential_reader.cpp
5. 压缩：reader_writer_factory.cpp → sequential_compression_writer.cpp
6. 录制：record_options.hpp → recorder.cpp（subscribe_topic / record）
7. 回放：play_options.hpp → player.cpp（play / play_messages_from_queue）
8. CLI：ros2bag/setup.py → verb/record.py → rosbag2_py/_transport.cpp
9. 高级：bag_rewrite.cpp → reindexer.cpp

16. 小结

rosbag2 目录实现 ROS 2 可插拔日志栈：底层 storage 插件 持久化序列化字节；rosbag2_cpp 提供顺序读写、缓存与 metadata；rosbag2_transport 连接 rclcpp 图（GenericSubscription/Publisher）与时间控制；rosbag2_compression 与 ros2bag/rosbag2_py 完成压缩与用户接口。

理解任意 bug 或性能问题，通常从 Recorder::subscribe_topic → Writer::write → storage 插件（录制）或 Player::play → Reader::read_next → GenericPublisher（回放）两条主链入手，并核对 metadata.yaml 与 QoS/serialization 配置 是否一致。

rosidl_dds 源码详细分析

工作区路径：/home/cp/work2/ros2Learn/ros2_humble/src/ros2/rosidl_dds
子包数量：1

1. 定位

rosidl_dds 目录含 1 个 ROS 2 包，工作区路径见下。

2. 子包列表

3. 在 ROS 2 Humble 栈中的关系

见 ros2总览.md 分层图。

4. 推荐阅读顺序

1. 阅读各子包 package.xml 2. 入口源码 3. 下游依赖方

5. 小结

rosidl_dds 为单包仓库，提供 rosidl_generator_dds_idl 功能。

rosidl_defaults 源码详细分析

工作区路径：/home/cp/work2/ros2Learn/ros2_humble/src/ros2/rosidl_defaults
子包数量：2

1. 定位

rosidl_defaults 目录含 2 个 ROS 2 包，工作区路径见下。

2. 子包列表

3. 在 ROS 2 Humble 栈中的关系

见 ros2总览.md 分层图。

4. 推荐阅读顺序

1. 阅读各子包 package.xml 2. 入口源码 3. 下游依赖方

5. 小结

rosidl_defaults 为含 2 个子包的源码树，是 ROS 2 Humble 发行版的一部分。

rosidl_python 源码详细分析

工作区路径：/home/cp/work2/ros2Learn/ros2_humble/src/ros2/rosidl_python
子包数量：1

1. 定位

rosidl_python 目录含 1 个 ROS 2 包，工作区路径见下。

2. 子包列表

3. 在 ROS 2 Humble 栈中的关系

见 ros2总览.md 分层图。

4. 推荐阅读顺序

1. 阅读各子包 package.xml 2. 入口源码 3. 下游依赖方

5. 小结

rosidl_python 为单包仓库，提供 rosidl_generator_py 功能。

rosidl_runtime_py 源码详细分析

工作区路径：/home/cp/work2/ros2Learn/ros2_humble/src/ros2/rosidl_runtime_py
子包数量：1

1. 定位

rosidl_runtime_py 目录含 1 个 ROS 2 包，工作区路径见下。

2. 子包列表

3. 在 ROS 2 Humble 栈中的关系

见 ros2总览.md 分层图。

4. 推荐阅读顺序

1. 阅读各子包 package.xml 2. 入口源码 3. 下游依赖方

5. 小结

rosidl_runtime_py 为单包仓库，提供 rosidl_runtime_py 功能。

rosidl_typesupport_fastrtps 源码详细分析

工作区路径：/home/cp/work2/ros2Learn/ros2_humble/src/ros2/rosidl_typesupport_fastrtps
版本：2.2.4（Humble），子包 3 个，许可证 Apache 2.0。

rosidl_typesupport_fastrtps 是 ROS 2 在 Fast-DDS / Fast-RTPS RMW 下的 CDR 序列化 typesupport 插件：为每条消息/服务生成 fastcdr::Cdr 读写代码，并通过 message_type_support_callbacks_t 回调表暴露给 rmw_fastrtps_cpp。本仓库 不实现 DDS 传输层——那是 rmw_fastrtps 的职责；此处只负责 ROS 消息 ↔ CDR 字节流。

范围说明：分发层（rosidl_typesupport_c/cpp）在独立仓库 rosidl_typesupport；本仓库是 RMW 实际调用的 concrete typesupport 插件 之一。Humble 默认 RMW 为 rmw_fastrtps_cpp，因此本插件为数据面关键路径。

1. 总体认识

1.1 核心职责

1.2 在 ROS 2 栈中的位置

1.3 端到端 publish 数据路径（简化）

1
2
3
4
5
6
7
8
9

rclcpp::Publisher::publish(msg)
  → rosidl_typesupport_cpp dispatch handle
  → dlopen libstd_msgs__rosidl_typesupport_fastrtps_cpp.so
  → get_message_type_support_handle<std_msgs::msg::String>()
  → rmw_fastrtps_cpp::MessageTypeSupport(callbacks)
  → TypeSupport::serializeROSmessage()
       ser.serialize_encapsulation()
       callbacks->cdr_serialize(ros_message, ser)
  → Fast-DDS 发送 CDR buffer

2. 仓库结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

rosidl_typesupport_fastrtps/
├── fastrtps_cmake_module/              # FindFastRTPS.cmake
│   └── cmake/Modules/FindFastRTPS.cmake
├── rosidl_typesupport_fastrtps_cpp/    # ★ C++ 消息 CDR + 回调结构定义
│   ├── include/rosidl_typesupport_fastrtps_cpp/
│   │   ├── message_type_support.h      # callbacks 结构体（C/C++ 共用）
│   │   ├── service_type_support.h
│   │   ├── message_type_support_decl.hpp
│   │   └── wstring_conversion.hpp
│   ├── src/identifier.cpp, wstring_conversion.cpp
│   ├── resource/*.em                   # Empy 生成模板
│   └── cmake/rosidl_typesupport_fastrtps_cpp_generate_interfaces.cmake
└── rosidl_typesupport_fastrtps_c/      # ★ C 消息 CDR（依赖 C++ 包头）
    ├── resource/*_c.cpp.em / *_c.h.em
    └── cmake/rosidl_typesupport_fastrtps_c_generate_interfaces.cmake

2.1 子包一览

3. fastrtps_cmake_module

3.1 作用

Historically ROS 2 用统一 CMake 模块查找 eProsima 组件。FindFastRTPS.cmake 封装：

1
2
3

find_package(fastcdr REQUIRED CONFIG)
find_package(fastrtps REQUIRED CONFIG)
# 设置 FastRTPS_INCLUDE_DIR, FastRTPS_LIBRARIES, FastCDR_LIBRARIES

注意：本仓库生成代码 直接使用 fastcdr（#include <fastcdr/Cdr.h>），不直接在模板里调用 FastRTPS API。FindFastRTPS 主要供 下游 RMW 与依赖链使用；generator 的 find_package(fastcdr REQUIRED CONFIG) 才是编译关键。

3.2 质量等级

QL 4（辅助模块），与两个 typesupport 包（QL 1）不同。

4. message_type_support_callbacks_t — 核心契约

定义于 rosidl_typesupport_fastrtps_cpp/message_type_support.h，C 与 C++ 生成代码共用：

1
2
3
4
5
6
7
8
9

typedef struct message_type_support_callbacks_t {
  const char * message_namespace_;
  const char * message_name_;

  bool (* cdr_serialize)(const void * untyped_ros_message, eprosima::fastcdr::Cdr & cdr);
  bool (* cdr_deserialize)(eprosima::fastcdr::Cdr & cdr, void * untyped_ros_message);
  uint32_t (* get_serialized_size)(const void *);
  size_t (* max_serialized_size)(char & bounds_info);
} message_type_support_callbacks_t;

4.1 四个回调的含义

4.2 bounds_info 与零拷贝优化

1
2
3

#define ROSIDL_TYPESUPPORT_FASTRTPS_UNBOUNDED_TYPE 0x00
#define ROSIDL_TYPESUPPORT_FASTRTPS_BOUNDED_TYPE   0x01
#define ROSIDL_TYPESUPPORT_FASTRTPS_PLAIN_TYPE     0x03

rmw_fastrtps_cpp::TypeSupport::set_members() 读取 max_serialized_size(bounds_info)：

• PLAIN：POD 型消息，内存布局与 CDR 一致 → 可 loan/sample 零拷贝 优化
• BOUNDED：有界（无有界 string/sequence 外的 unbounded）
• UNBOUNDED：含 unbounded string/sequence

1
2
3
4
5

// rmw_fastrtps_cpp/src/type_support_common.cpp
auto data_size = members->max_serialized_size(bounds_info);
max_size_bound_ = 0 != (bounds_info & ROSIDL_TYPESUPPORT_FASTRTPS_BOUNDED_TYPE);
is_plain_ = bounds_info == ROSIDL_TYPESUPPORT_FASTRTPS_PLAIN_TYPE;
m_typeSize = 4 + data_size;  // + encapsulation，4 字节对齐

空消息特殊处理：plain 且 size=0 时加 dummy byte。

4.3 service_type_support_callbacks_t

1
2
3
4
5
6

typedef struct service_type_support_callbacks_t {
  const char * service_namespace_;
  const char * service_name_;
  const rosidl_message_type_support_t * request_members_;
  const rosidl_message_type_support_t * response_members_;
} service_type_support_callbacks_t;

Service handle 的 data 指向此结构；RMW 分别对 Request/Response 消息 callbacks 创建 RequestTypeSupport / ResponseTypeSupport。

5. 代码生成（Empy 模板）

5.1 生成入口

C++（rosidl_typesupport_fastrtps_cpp/__init__.py）：

1
2
3
4
5
6

mapping = {
    'idl__rosidl_typesupport_fastrtps_cpp.hpp.em':
        'detail/%s__rosidl_typesupport_fastrtps_cpp.hpp',
    'idl__type_support.cpp.em':
        'detail/dds_fastrtps/%s__type_support.cpp',
}

C（rosidl_typesupport_fastrtps_c/__init__.py）：

1
2
3
4
5
6

mapping = {
    'idl__rosidl_typesupport_fastrtps_c.h.em':
        'detail/%s__rosidl_typesupport_fastrtps_c.h',
    'idl__type_support_c.cpp.em':
        'detail/%s__type_support_c.cpp',
}

5.2 CMake 扩展注册

rosidl_typesupport_fastrtps_cpp-extras.cmake.in：

1
2
3
4
5
6
7
8

if(NOT fastcdr_FOUND)
  message(STATUS "Could not find eProsima Fast CDR - skip rosidl_typesupport_fastrtps_cpp")
else()
  ament_register_extension(
    "rosidl_generate_idl_interfaces"
    "rosidl_typesupport_fastrtps_cpp"
    "rosidl_typesupport_fastrtps_cpp_generate_interfaces.cmake")
endif()

前置条件：

• C++：__rosidl_generator_cpp 必须先存在
• C：__rosidl_generator_c + rosidl_typesupport_fastrtps_cpp 包

ament index（构建时注册为可用插件）：

1
2
3
4

# rosidl_typesupport_fastrtps_cpp/CMakeLists.txt
ament_index_register_resource("rosidl_typesupport_cpp")
# rosidl_typesupport_fastrtps_c/CMakeLists.txt
ament_index_register_resource("rosidl_typesupport_c")

5.3 生成的 CMake Target

链接依赖：fastcdr、rmw::rmw、rosidl_runtime_*、librosidl_typesupport_fastrtps_cpp.so（C 包）。

6. C++ 生成模板详解（msg__type_support.cpp.em）

6.1 生成结构概览

对每条消息 MyMsg，生成：

1. 公开 CDR 函数（typesupport_fastrtps_cpp 命名空间）
   cdr_serialize / cdr_deserialize / get_serialized_size / max_serialized_size_MyMsg
2. 静态包装函数（type-erased，void*）
3. message_type_support_callbacks_t 静态实例
4. rosidl_message_type_support_t handle
5. C++ 模板特化 + extern “C” 导出符号

6.2 handle 组装

1
2
3
4
5
6
7
8
9
10
11
12
13

static message_type_support_callbacks_t MyMsg__callbacks = {
  "my_pkg::msg", "MyMsg",
  _MyMsg__cdr_serialize,
  _MyMsg__cdr_deserialize,
  _MyMsg__get_serialized_size,
  _MyMsg__max_serialized_size
};

static rosidl_message_type_support_t MyMsg__handle = {
  rosidl_typesupport_fastrtps_cpp::typesupport_identifier,
  &MyMsg__callbacks,
  get_message_typesupport_handle_function,
};

• identifier："rosidl_typesupport_fastrtps_cpp"
• func：rosidl_runtime_c 提供的链式查找；对 concrete handle，identifier 匹配时直接返回自身

导出符号（供分发层 dlsym）：

1
2

ROSIDL_TYPESUPPORT_INTERFACE__MESSAGE_SYMBOL_NAME(
  rosidl_typesupport_fastrtps_cpp, my_pkg, msg, MyMsg)()

6.3 字段序列化规则（模板逻辑摘要）

反序列化对称实现；bounded sequence 检查 size > maximum_size 抛 std::runtime_error。

6.4 max_serialized_size 与 plain 判定

模板递归计算 CDR alignment，累加 current_alignment：

• 基本类型按 sizeof + Cdr::alignment
• 嵌套类型调用 max_serialized_size_DependentType
• string 按 bounded 与否估算 upper bound
• 最后用 offsetof 比较 in-memory 布局与 CDR 大小，确认 is_plain

7. C 生成模板差异（msg__type_support_c.cpp.em）

C 侧操作 rosidl_generator_c 生成的 C struct：

C handle 示例：

1
2
3
4
5

static rosidl_message_type_support_t MyMsg__type_support = {
  rosidl_typesupport_fastrtps_c__identifier,
  &__callbacks_MyMsg,
  get_message_typesupport_handle_function,
};

依赖关系：C 包 <depend>rosidl_typesupport_fastrtps_cpp</depend>，因 callbacks 结构体定义在 C++ 包头中。

8. Service 与 Action

8.1 Service

srv__type_support.cpp.em：

1. 对 Request/Response 各调用一次 msg__type_support.cpp.em
2. 组装 service_type_support_callbacks_t，指向两个 message 的 fastrtps symbol：

1
2
3
4
5

static service_type_support_callbacks_t MySrv__callbacks = {
  "my_pkg::srv", "MySrv",
  ROSIDL_TYPESUPPORT_INTERFACE__MESSAGE_SYMBOL_NAME(..., MySrv_Request)(),
  ROSIDL_TYPESUPPORT_INTERFACE__MESSAGE_SYMBOL_NAME(..., MySrv_Response)(),
};

RMW 侧 RequestTypeSupport / ResponseTypeSupport 从 service callbacks 取出 request/response 的 message callbacks。

8.2 Action

无独立 action 模板；Action 的 Goal/Result/Feedback/SendGoal/GetResult/FeedbackMessage 作为 普通 message/service 在 IDL 展开后走同一套 msg/srv 模板（与 rosidl 工具链 Action 衍生类型一致）。

9. 运行时辅助库

9.1 librosidl_typesupport_fastrtps_cpp.so

编译产物（非 per-package）：

• identifier.cpp — typesupport_identifier = "rosidl_typesupport_fastrtps_cpp"
• wstring_conversion.cpp — u16 ↔ wstring

wstring 转换（FastCDR 使用 std::wstring，ROS 使用 char16_t/u16string）：

1
2
3
4
5

void u16string_to_wstring(const std::u16string & u16str, std::wstring & wstr) {
  wstr.resize(u16str.size());
  for (size_t i = 0; i < u16str.size(); ++i)
    wstr[i] = static_cast<wchar_t>(u16str[i]);
}

rmw_fastrtps_dynamic_cpp 在动态类型路径中也复用这些转换函数。

9.2 C 包运行时

C 包主要提供 generator + rosidl_typesupport_fastrtps_c__identifier；wstring 实现在 C++ 包中，C 侧通过 rosidl_typesupport_fastrtps_c/wstring_conversion.hpp 包装调用。

10. 与 rmw_fastrtps 的衔接

10.1 TypeSupport 包装

rmw_fastrtps_cpp/src/type_support_common.cpp 是 本仓库 callbacks 的直接消费者：

1
2
3
4
5
6
7
8
9
10
11

bool TypeSupport::serializeROSmessage(
  const void * ros_message, eprosima::fastcdr::Cdr & ser, const void * impl) const
{
  ser.serialize_encapsulation();
  if (has_data_) {
    auto callbacks = static_cast<const message_type_support_callbacks_t *>(impl);
    return callbacks->cdr_serialize(ros_message, ser);
  }
  ser << (uint8_t)0;  // empty message dummy
  return true;
}

创建 publisher 时（subscription.cpp 等）：

1
2

auto callbacks = static_cast<const message_type_support_callbacks_t *>(type_support->data);
MessageTypeSupport ts(callbacks);

type_support 来自 RMW，已通过 rosidl_typesupport_cpp 分发层解析到 fastrtps concrete handle。

10.2 rmw_fastrtps_cpp vs rmw_fastrtps_dynamic_cpp

两包均 build_depend 本仓库的 rosidl_typesupport_fastrtps_c/cpp。

11. 编译开关与环境变量

Humble 通过 rosidl_default_generators 默认拉入本插件；缺失时 ros2 bag/DDS 通信会在运行时 dlopen 失败。

12. 安装布局示例

以 std_msgs 为例：

1
2
3
4
5
6
7
8
9
10
11

install/std_msgs/lib/
├── libstd_msgs__rosidl_typesupport_fastrtps_cpp.so
└── libstd_msgs__rosidl_typesupport_fastrtps_c.so

install/std_msgs/include/std_msgs/std_msgs/
├── msg/detail/dds_fastrtps/string__type_support.cpp  # 仅 build 树
└── msg/detail/string__rosidl_typesupport_fastrtps_cpp.hpp

install/lib/
├── librosidl_typesupport_fastrtps_cpp.so   # 公共辅助库
└── librosidl_typesupport_fastrtps_c.so     # （若 C 包也建 runtime lib）

publish 热路径：per-package 的 __rosidl_typesupport_fastrtps_cpp 库。

13. 与 rosidl_typesupport 分发层的关系

回顾分发层加载逻辑（见 rosidl_typesupport源码详细分析.md）：

1. rosidl_typesupport_cpp handle 的 map 含 "rosidl_typesupport_fastrtps_cpp"
2. dlopen("libstd_msgs__rosidl_typesupport_fastrtps_cpp.so")
3. dlsym("rosidl_typesupport_fastrtps_cpp__get_message_type_support_handle__std_msgs__msg__String")
4. 返回 §6.2 中的 concrete handle（data → callbacks）

本仓库不负责 dispatch；只实现 map 中 被指向的目标库。

14. 序列图：CDR 序列化

15. 调试与常见问题

实用命令：

1
2
3
4
5
6
7
8

# 确认插件已注册
ls install/share/rosidl_typesupport_fastrtps_cpp/cmake

# 查看某消息 fastrtps 库
ls install/lib/lib*fastrtps*

# 查看生成 CDR 源（build 树）
ls build/std_msgs/rosidl_typesupport_fastrtps_cpp/std_msgs/msg/detail/dds_fastrtps/

16. 与 introspection typesupport 对比

同一消息 同时 生成两种插件库，由分发层按 identifier 选择。

17. 源码阅读顺序

1. 契约：message_type_support.h → service_type_support.h
2. RMW 消费方：rmw_fastrtps_cpp/src/type_support_common.cpp
3. C++ 生成模板：resource/msg__type_support.cpp.em（serialize 与 max_size 两段）
4. C 生成模板：resource/msg__type_support_c.cpp.em
5. Service：resource/srv__type_support.cpp.em
6. CMake 生成：rosidl_typesupport_fastrtps_cpp_generate_interfaces.cmake
7. 扩展注册：rosidl_typesupport_fastrtps_cpp-extras.cmake.in
8. 分发层衔接：rosidl_typesupport 仓库 type_support_dispatch.hpp
9. 辅助：wstring_conversion.cpp、FindFastRTPS.cmake

18. 小结

rosidl_typesupport_fastrtps 仓库实现 ROS 2 消息在 Fast-DDS RMW 下的 CDR 序列化 typesupport：

• rosidl_typesupport_fastrtps_cpp/c：Empy 生成 per-message 的 fastcdr 读写与 message_type_support_callbacks_t
• fastrtps_cmake_module：CMake 查找 eProsima 依赖
• rmw_fastrtps_cpp：读取 callbacks，封装 encapsulation，交给 Fast-DDS

理解 DDS 通信问题需串联 本仓库生成的 CDR 代码 与 rmw_fastrtps 的 TypeSupport 包装；理解 typesupport 加载失败则需同时查看 rosidl_typesupport 分发层 的 dlopen 逻辑。

rosidl_typesupport 源码详细分析

工作区路径：/home/cp/work2/ros2Learn/ros2_humble/src/ros2/rosidl_typesupport
版本：2.0.2（Humble），子包 2 个，许可证 Apache 2.0。

rosidl_typesupport 仓库实现 ROS 2 typesupport 分发层（dispatch layer）：为每个消息/服务/动作生成「中间 handle」，在运行时按 RMW 所需的 具体 typesupport identifier（如 rosidl_typesupport_fastrtps_cpp）动态加载对应共享库并返回真正的序列化实现。本仓库 不实现 DDS 线格式序列化——那是 rosidl_typesupport_fastrtps_*、rosidl_typesupport_introspection_* 等插件的职责。

范围说明：本仓库仅含 rosidl_typesupport_c 与 rosidl_typesupport_cpp。具体 RMW/DDS typesupport 在 rosidl_typesupport_fastrtps 仓库；introspection 在 rosidl 仓库的 rosidl_typesupport_introspection_* 包。

1. 总体认识

1.1 为什么需要 typesupport 分发层？

ROS 2 允许同一消息类型存在 多种 typesupport 实现：

用户代码和 RCL 通常持有 分发层 handle（identifier = rosidl_typesupport_cpp），在 publish/take 时 RMW 传入 自身需要的 identifier，分发层通过 dlopen 加载 lib{pkg}__{identifier}.so 并 dlsym 取得具体实现。

1.2 核心职责

1.3 在 ROS 2 栈中的位置

2. 仓库结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

rosidl_typesupport/
├── README.md
├── LICENSE
├── rosidl_typesupport_c/           # ★ C 分发层
│   ├── include/rosidl_typesupport_c/
│   │   ├── type_support_map.h      # 核心 map 结构
│   │   ├── message_type_support_dispatch.h
│   │   ├── service_type_support_dispatch.h
│   │   └── identifier.h
│   ├── src/
│   │   ├── identifier.c
│   │   ├── message_type_support_dispatch.cpp
│   │   ├── service_type_support_dispatch.cpp
│   │   └── type_support_dispatch.hpp   # dlopen 逻辑
│   ├── cmake/
│   │   ├── get_used_typesupports.cmake   # 发现可用插件
│   │   └── rosidl_typesupport_c_generate_interfaces.cmake
│   ├── resource/*.em               # 生成模板
│   └── rosidl_typesupport_c/__init__.py
└── rosidl_typesupport_cpp/         # ★ C++ 分发层
    ├── include/rosidl_typesupport_cpp/
    │   ├── message_type_support_dispatch.hpp
    │   ├── service_type_support_dispatch.hpp
    │   └── identifier.hpp
    ├── src/                        # 结构与 C 包对称
    ├── cmake/rosidl_typesupport_cpp_generate_interfaces.cmake
    └── resource/*.em

两包结构 高度对称：C 包提供 type_support_map_t 定义；C++ 包依赖 C 包并复用同一 map 结构。

3. 核心数据结构

3.1 rosidl_message_type_support_t

定义于 rosidl_runtime_c/message_type_support_struct.h（rosidl 仓库）：

1
2
3
4
5

struct rosidl_message_type_support_t {
  const char * typesupport_identifier;
  const void * data;
  rosidl_message_typesupport_handle_function func;
};

• identifier：本 handle 所属 typesupport 层
• data：具体 typesupport 私有数据，或指向 type_support_map_t
• func：按 identifier 查找/加载其他 typesupport 的回调

3.2 type_support_map_t

定义于 rosidl_typesupport_c/type_support_map.h：

1
2
3
4
5
6
7

typedef struct type_support_map_t {
  const size_t size;
  const char * package_name;
  const char * const * typesupport_identifier;  // 插件名数组
  const char * const * symbol_name;             // dlsym 符号名数组
  void ** data;                                 // 缓存已加载的 SharedLibrary*
} type_support_map_t;

运行时填充：data[i] 初始为 NULL；首次请求 identifier typesupport_identifier[i] 时，dlopen 加载库并缓存指针。

3.3 分发层 identifier

4. 运行时 dispatch 算法

实现于 src/type_support_dispatch.hpp（C/C++ 两包逻辑相同）。

4.1 get_typesupport_handle_function

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

template<typename TypeSupport>
const TypeSupport * get_typesupport_handle_function(
  const TypeSupport * handle, const char * identifier)
{
  // 1. 精确匹配：请求的 identifier 就是本 handle 的 identifier
  if (strcmp(handle->typesupport_identifier, identifier) == 0) {
    return handle;
  }

  // 2. 本 handle 是分发层（rosidl_typesupport_cpp/c）
  if (handle->typesupport_identifier == rosidl_typesupport_cpp::typesupport_identifier) {
    const type_support_map_t * map = static_cast<const type_support_map_t *>(handle->data);
    for (size_t i = 0; i < map->size; ++i) {
      if (strcmp(map->typesupport_identifier[i], identifier) != 0) continue;

      // 3. 懒加载共享库
      if (!map->data[i]) {
        // library_basename = "{package_name}__{identifier}"
        // 例: std_msgs__rosidl_typesupport_fastrtps_cpp
        lib = new rcpputils::SharedLibrary(
          rcpputils::get_platform_library_name(library_basename));
        map->data[i] = lib;
      }

      // 4. dlsym 取得具体 typesupport 入口函数
      sym = lib->get_symbol(map->symbol_name[i]);
      func = reinterpret_cast<const TypeSupport *(*)(void)>(sym);
      return func();  // 返回 concrete handle
    }
  }
  return nullptr;
}

库命名规则：{package_name}__{typesupport_identifier}
例如 std_msgs__rosidl_typesupport_fastrtps_cpp → libstd_msgs__rosidl_typesupport_fastrtps_cpp.so

符号命名规则（rosidl_typesupport_interface/macros.h）：

1

{typesupport_name}__get_message_type_support_handle__{package}__{subfolder}__{MessageName}

例：rosidl_typesupport_fastrtps_cpp__get_message_type_support_handle__std_msgs__msg__String

4.2 序列图

5. 编译期代码生成

5.1 CMake 扩展注册

rosidl_typesupport_cpp-extras.cmake.in：

1
2
3
4
5

get_used_typesupports(_typesupports "rosidl_typesupport_cpp")
ament_register_extension(
  "rosidl_generate_idl_interfaces"
  "rosidl_typesupport_cpp"
  "rosidl_typesupport_cpp_generate_interfaces.cmake")

在 rosidl_generate_interfaces() 执行 ament_execute_extensions("rosidl_generate_idl_interfaces") 时被调用。

前置依赖：必须先有 __rosidl_generator_cpp target（C 包则要求 __rosidl_generator_c）。

5.2 get_used_typesupports() — 发现可用插件

rosidl_typesupport_c/cmake/get_used_typesupports.cmake：

1. ament_index_get_resources(available_typesupports "rosidl_typesupport_cpp")
   读取所有向 ament index 注册了 rosidl_typesupport_cpp 资源的包（如 fastrtps、introspection）
2. 可选过滤：CMake 变量或环境变量 STATIC_ROSIDL_TYPESUPPORT_CPP（C 侧为 STATIC_ROSIDL_TYPESUPPORT_C），分号分隔插件名
3. 输出 typesupports 列表传给 generator

构建日志示例：

1

Using all available rosidl_typesupport_cpp: rosidl_typesupport_fastrtps_cpp;rosidl_typesupport_introspection_cpp

仅一个插件时标记为 single，生成器走 静态直连 优化路径（见 §5.4）。

5.3 生成命令

1
2
3
4
5
6
7
8

add_custom_command(
  OUTPUT ${_generated_sources}
  COMMAND Python3::Interpreter
  ARGS ${rosidl_typesupport_cpp_BIN}
       --generator-arguments-file "${generator_arguments_file}"
       --typesupports ${typesupports}
  ...
)

Python 入口 rosidl_typesupport_cpp/__init__.py：

1
2
3

def generate_cpp(generator_arguments_file, type_supports):
    mapping = {'idl__type_support.cpp.em': '%s__type_support.cpp'}
    return generate_files(..., additional_context={'type_supports': type_supports})

每个 IDL 文件生成一个 {msg_name}__type_support.cpp，内含该文件中所有 message/service/action 的分发代码。

5.4 两种生成模式

模式 A：多 typesupport（默认，动态 dispatch）

Empy 模板 msg__type_support.cpp.em 生成：

1
2
3
4
5
6
7
8
9
10
11
12
13

static const type_support_map_t String_message_typesupport_map = {
  2,  // size
  "std_msgs",
  &String_message_typesupport_ids.typesupport_identifier[0],
  &String_message_typesupport_symbol_names.symbol_name[0],
  &String_message_typesupport_data.data[0],
};

static const rosidl_message_type_support_t String_message_type_support_handle = {
  ::rosidl_typesupport_cpp::typesupport_identifier,
  &String_message_typesupport_map,
  ::rosidl_typesupport_cpp::get_message_typesupport_handle_function,
};

map 中 typesupport_identifier 数组在编译期填入，例如：

1
2

"rosidl_typesupport_fastrtps_cpp",
"rosidl_typesupport_introspection_cpp",

模式 B：单一 typesupport（静态优化）

当 get_used_typesupports 只返回一个插件时，生成器 跳过 map，直接转发：

1
2
3
4
5
6

template<>
const rosidl_message_type_support_t *
get_message_type_support_handle<std_msgs::msg::String>() {
  return ROSIDL_TYPESUPPORT_INTERFACE__MESSAGE_SYMBOL_NAME(
    rosidl_typesupport_fastrtps_cpp, std_msgs, msg, String)();
}

CMake 同时 静态链接 该 typesupport target：

1
2
3

if(NOT typesupports MATCHES ";")
  target_link_libraries(... PRIVATE ${target}__${typesupports})
endif()

限制：多 typesupport + BUILD_SHARED_LIBS=OFF 会 fatal error（无法静态链接多个插件）。

5.5 生成的 CMake Target

与 {pkg}__rosidl_typesupport_fastrtps_cpp 等 并列安装 于 lib/。

6. C 与 C++ 分发层差异

C++ 侧模板声明位于 rosidl_runtime_cpp/include/rosidl_typesupport_cpp/message_type_support.hpp：

1
2

template<typename T>
const rosidl_message_type_support_t * get_message_type_support_handle();

每个消息在生成的 __type_support.cpp 中 显式特化。

7. 与 rosidl 工具链的衔接

7.1 在 rosidl_generate_interfaces 中的顺序

1
2
3
4
5
6
7

rosidl_generator_c
  → rosidl_generator_cpp
    → rosidl_typesupport_c
      → rosidl_typesupport_cpp
        → rosidl_typesupport_introspection_c/cpp
        → rosidl_typesupport_fastrtps_c/cpp
        → rosidl_generator_py

introspection / fastrtps 的 CMake 同样注册 rosidl_generate_idl_interfaces，且通常依赖 generator 已生成的 struct 头文件。

7.2 ament index 注册链

具体 typesupport 插件在 自身 CMakeLists 中注册 index 资源：

1
2

# rosidl_typesupport_fastrtps_cpp/CMakeLists.txt
ament_index_register_resource("rosidl_typesupport_cpp")

get_used_typesupports() 据此发现插件。若某插件未安装，不会进入 map，对应 RMW 在运行时会加载失败。

7.3 rosidl_typesupport_c_packages 组

package.xml 中：

1

<group_depend>rosidl_typesupport_cpp_packages</group_depend>

Bloom 打包时确保二进制发行版包含常见 RMW typesupport 依赖；源码构建时由 workspace 中已 clone 的 fastrtps 等包满足。

8. 运行时调用路径示例

8.1 rclcpp publish

1
2
3
4
5
6
7
8
9
10

rclcpp::Publisher<std_msgs::msg::String>::publish(msg)
  → rosidl_typesupport_cpp::get_message_type_support_handle<std_msgs::msg::String>()
       返回 pkg 生成的 dispatch handle（identifier=rosidl_typesupport_cpp）
  → rcl_publish(..., ros_message, type_support)
  → rmw 内部调用 type_support->func(handle, rmw_typesupport_identifier)
       rmw_typesupport_identifier = "rosidl_typesupport_fastrtps_cpp"
  → get_message_typesupport_handle_function(...)
  → dlopen libstd_msgs__rosidl_typesupport_fastrtps_cpp.so
  → 返回 fastrtps concrete handle
  → Fast-DDS CDR 序列化 → 网络发送

8.2 Python / introspection

Python 绑定通常请求 rosidl_typesupport_introspection_c identifier，同一 dispatch 机制加载 libpkg__rosidl_typesupport_introspection_c.so，取得字段 layout 用于 C ↔ Python 转换。

9. 测试与质量

两包均为 Quality Level 1，含：

测试构造 mock type_support_map_t，用 rosidl_typesupport_cpp__test_type_support1/2 等假库验证加载逻辑；故意放置非共享库文件验证错误处理。

10. 配置与调优

10.1 限制编译期 typesupport 集合

减少 map 大小、缩短构建时间、缩小 install 体积：

1
2
3

# 仅保留 fastrtps（示例）
export STATIC_ROSIDL_TYPESUPPORT_CPP=rosidl_typesupport_fastrtps_cpp
colcon build --packages-select my_msgs

CMake 中等价：set(STATIC_ROSIDL_TYPESUPPORT_CPP "rosidl_typesupport_fastrtps_cpp")

10.2 静态链接注意

• 单一 typesupport：可静态链接，无 dlopen 开销
• 多 typesupport + 静态库模式：不支持（CMake fatal error）
• 默认 BUILD_SHARED_LIBS=ON 使用动态 dispatch

10.3 常见问题

11. 与关联仓库对比

记忆口诀：generator 造 数据 struct；typesupport 插件造 序列化/反射；rosidl_typesupport_cpp 造 路由表 把 RMW 请求转到正确插件。

12. 端到端库依赖图（单接口包）

以 std_msgs 为例，install/lib/ 中典型产物：

1
2
3
4
5
6
7
8

libstd_msgs__rosidl_generator_c.so          # C struct + functions
libstd_msgs__rosidl_generator_cpp.so        # 头文件（常为 INTERFACE）
libstd_msgs__rosidl_typesupport_c.so        # ★ C dispatch
libstd_msgs__rosidl_typesupport_cpp.so      # ★ C++ dispatch
libstd_msgs__rosidl_typesupport_fastrtps_c.so
libstd_msgs__rosidl_typesupport_fastrtps_cpp.so
libstd_msgs__rosidl_typesupport_introspection_c.so
libstd_msgs__rosidl_typesupport_introspection_cpp.so

运行时 rclcpp 主要链接/加载 __rosidl_typesupport_cpp；RMW 再经 dispatch 加载 __rosidl_typesupport_fastrtps_cpp。

13. 源码阅读顺序

1. 数据结构：rosidl_typesupport_c/type_support_map.h → rosidl_runtime_c/message_type_support_struct.h
2. dispatch 核心：rosidl_typesupport_cpp/src/type_support_dispatch.hpp
3. 对外 API：message_type_support_dispatch.hpp / identifier.hpp
4. 生成模板：resource/msg__type_support.cpp.em（多/单 typesupport 分支）
5. CMake：get_used_typesupports.cmake → rosidl_typesupport_cpp_generate_interfaces.cmake
6. 扩展注册：rosidl_typesupport_cpp-extras.cmake.in
7. 测试：test/test_message_type_support_dispatch.cpp
8. 下游：rclcpp 中 get_message_type_support_handle<T>() 调用链；rosidl_typesupport_fastrtps_cpp 中 concrete 实现

14. 小结

rosidl_typesupport 仓库的 2 个包是 ROS 2 类型系统中连接「接口包」与「多种 RMW/语言 typesupport 插件」的 枢纽：

• 编译期：扫描 ament index 中已注册插件，为每条消息生成 type_support_map 或静态直连代码，产出 lib{pkg}__rosidl_typesupport_{c,cpp}.so
• 运行期：通过 get_message_typesupport_handle_function 按 identifier dlopen lib{pkg}__{plugin}.so，实现 RMW、Python、工具链对同一消息类型的 插件化 访问

理解 publish 失败或 typesupport 符号缺失时，应同时检查 dispatch 库 与 具体插件库 是否都已正确生成并存在于 LD_LIBRARY_PATH / install lib/ 中。

rosidl 源码详细分析

工作区路径：/home/cp/work2/ros2Learn/ros2_humble/src/ros2/rosidl
版本：3.1.8（Humble），子包 12 个，许可证 Apache 2.0。

rosidl 是 ROS 2 接口定义语言（IDL）工具链的核心仓库：将 .msg / .srv / .action（或原生 .idl）解析为 AST，经 Empy 模板 生成 C/C++ 结构体与函数，并注册 typesupport 扩展点；运行时通过 rosidl_message_type_support_t 与 RMW/DDS 衔接。

范围说明：本仓库含 编译期 核心（adapter / parser / generator / runtime / introspection typesupport）。Python 生成器（rosidl_generator_py）、通用 typesupport 分发（rosidl_typesupport_cpp）、Fast-DDS typesupport（rosidl_typesupport_fastrtps_*）、默认生成器聚合（rosidl_default_generators）位于 独立仓库，见 §12。

1. 总体认识

1.1 核心职责

1.2 在 ROS 2 栈中的位置

1.3 端到端流水线

1
2
3
4
5
6
7
8
9
10
11

package.xml + CMakeLists.txt
  └── rosidl_generate_interfaces(${PROJECT_NAME} "msg/Foo.msg" DEPENDENCIES std_msgs)
        ├── [非 .idl] rosidl_adapter → 生成 build/.../msg/Foo.idl
        ├── rosidl_parser → AST（构建时由 generator 调用）
        └── ament_execute_extensions("rosidl_generate_idl_interfaces")
              ├── rosidl_generator_c        → lib...__rosidl_generator_c.so
              ├── rosidl_generator_cpp      → 头文件库 __rosidl_generator_cpp
              ├── rosidl_typesupport_introspection_c/cpp
              ├── [外部] rosidl_generator_py
              ├── [外部] rosidl_typesupport_cpp
              └── [外部] rosidl_typesupport_fastrtps_c/cpp

2. 仓库结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

rosidl/
├── rosidl_adapter/              # ★ .msg/.srv/.action → .idl (Python)
│   ├── rosidl_adapter/
│   │   ├── parser.py            # Legacy 格式解析（与 parser 包不同）
│   │   ├── msg/ srv/ action/    # convert_*_to_idl
│   │   └── resource/*.idl.em    # Empy 模板
│   └── cmake/rosidl_adapt_interfaces.cmake
├── rosidl_parser/               # ★ IDL 语法解析 (Lark)
│   ├── rosidl_parser/
│   │   ├── grammar.lark
│   │   ├── parser.py
│   │   └── definition.py        # AST 类型定义 (~765 行)
│   └── bin/idl2png
├── rosidl_cmake/                # ★ CMake 宏与 generate_files 工具
│   ├── cmake/rosidl_generate_interfaces.cmake
│   ├── cmake/rosidl_get_typesupport_target.cmake
│   └── rosidl_cmake/__init__.py # Empy 驱动 generate_files()
├── rosidl_generator_c/          # C struct + functions
│   ├── resource/*.em
│   └── rosidl_generator_c/__init__.py
├── rosidl_generator_cpp/        # C++ struct + builder + traits
│   ├── resource/*.em
│   └── rosidl_generator_cpp/__init__.py
├── rosidl_runtime_c/            # C 运行时类型与 type_support 结构
├── rosidl_runtime_cpp/          # C++ traits、bounded_vector
├── rosidl_typesupport_interface/# typesupport 符号宏
├── rosidl_typesupport_introspection_c/
├── rosidl_typesupport_introspection_cpp/
├── rosidl_typesupport_introspection_tests/
└── rosidl_cli/                  # rosidl 命令行

2.1 子包一览

3. rosidl_adapter：Legacy 格式 → IDL

3.1 入口

CMake 调用 rosidl_adapt_interfaces()，最终执行：

1
2

# rosidl_adapter/main.py
convert_to_idl(basepath, package_name, relative_path, output_dir)

按后缀分发：

3.2 Legacy 解析器（rosidl_adapter/parser.py）

与 rosidl_parser 独立：专门解析 ROS 1 风格 .msg 文本。

支持的 primitive 类型：

1
2
3

bool, byte, char, float32, float64,
int8/uint8, int16/uint16, int32/uint32, int64/uint64,
string, wstring, duration, time

语法元素：

• 注释：#
• 常量：NAME=123
• 数组：type[N] 固定长度，type[] / type[<=N] 动态/有界序列
• Service：以 --- 分隔 request/response
• Action：三段 --- 分隔 goal/result/feedback

命名校验：package/field 名小写+下划线；message 名 PascalCase（兼容 ROS 1 的宽松模式可选）。

3.3 类型映射（MSG → IDL）

1
2
3
4
5
6
7
8
9

# rosidl_adapter/msg/__init__.py
MSG_TYPE_TO_IDL = {
    'bool': 'boolean',
    'byte': 'octet',
    'char': 'uint8',
    'float32': 'float',
    'float64': 'double',
    # ...
}

3.4 IDL 模板（Empy）

msg.idl.em 将解析结果渲染为 OMG IDL 模块：

1
2
3
4
5
6
7
8
9
10
11

module test_msgs {
  module msg {
    struct Test {
      boolean bool_value;
      octet byte_value;
      uint8 char_value;
      float float32_value;
      // ...
    };
  };
};

注释通过 @verbatim 注解保留。输出编码为 iso-8859-1（兼容非 ASCII 注释）。

Service / Action 模板（srv.idl.em、action.idl.em）生成对应 module 结构；Action 在 adapter 阶段仅转换用户定义的三段，衍生类型（SendGoal/GetResult 等）由 rosidl_parser 的 Action 类在解析 IDL 后构建。

4. rosidl_parser：IDL → AST

4.1 解析器实现

• 语法引擎：Lark（grammar.lark）
• 入口：parse_idl_file(IdlLocator) → IdlFile(locator, content)
• 调试：idl2png 可将语法树导出为 PNG

1
2
3
4

# parser.py
_parser = Lark(grammar, start='specification', maybe_placeholders=False)
tree = _parser.parse(idl_string)
content = extract_content_from_ast(tree)

4.2 AST 类型体系（definition.py）

命名后缀常量（全栈统一）：

1
2
3
4
5
6
7
8

SERVICE_REQUEST_MESSAGE_SUFFIX = '_Request'
SERVICE_RESPONSE_MESSAGE_SUFFIX = '_Response'
ACTION_GOAL_SUFFIX = '_Goal'
ACTION_RESULT_SUFFIX = '_Result'
ACTION_FEEDBACK_SUFFIX = '_Feedback'
ACTION_GOAL_SERVICE_SUFFIX = '_SendGoal'
ACTION_RESULT_SERVICE_SUFFIX = '_GetResult'
ACTION_FEEDBACK_MESSAGE_SUFFIX = '_FeedbackMessage'

4.3 Action 衍生类型

用户 .action 文件只定义 goal/result/feedback 三段；Action 类自动构造：

隐式依赖：builtin_interfaces/msg/Time.idl、unique_identifier_msgs/msg/UUID.idl。

因此 action 包必须在 package.xml 中依赖 action_msgs（CMake 会检查）。

5. rosidl_cmake：构建编排

5.1 rosidl_generate_interfaces 宏

核心步骤（rosidl_generate_interfaces.cmake）：

1. 校验接口文件存在；支持 basepath:relative_path 元组
2. 分离 .idl 与 legacy 文件
3. 对 legacy 文件调用 rosidl_adapt_interfaces 生成 .idl
4. 对 .srv 额外在 build 目录生成 _Request.msg / _Response.msg（供 linter/索引）
5. 收集 DEPENDENCIES 中的 IDL 文件
6. 注册 ament index rosidl_interfaces
7. ament_execute_extensions("rosidl_generate_idl_interfaces") — 触发所有 generator/typesupport
8. 安装 .idl / .msg 到 share/${PROJECT_NAME}/

package.xml 要求：安装接口的包须声明：

1

<member_of_group>rosidl_interface_packages</member_of_group>

5.2 扩展点机制

各 generator 通过 ament_register_extension 注册：

1
2
3
4
5

# rosidl_generator_c/cmake/register_c.cmake
ament_register_extension(
  "rosidl_generate_idl_interfaces"
  "rosidl_generator_c"
  "rosidl_generator_c_generate_interfaces.cmake")

拓扑顺序：后注册的 extension 可声明对先生成 target 的依赖。例如 introspection 要求：

1
2
3

if(NOT TARGET ${target}__rosidl_generator_cpp)
  message(FATAL_ERROR "rosidl_generator_cpp must be executed before introspection...")
endif()

典型顺序：generator_c → generator_cpp → typesupport_*（introspection、fastrtps、cpp、py）。

5.3 generate_files() — 共享生成框架

rosidl_cmake/__init__.py 中：

1. 读取 JSON generator arguments（idl_tuples、template_dir、output_dir）
2. 对每个 IDL：parse_idl_file(locator) 得 AST
3. 用 Empy 渲染模板映射表
4. 增量构建：比较 template/idl 与已有输出 mtime

C 与 C++ generator 仅 mapping 表 不同：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# rosidl_generator_c
mapping = {
    'idl.h.em': '%s.h',
    'idl__struct.h.em': 'detail/%s__struct.h',
    'idl__functions.c.em': 'detail/%s__functions.c',
    ...
}

# rosidl_generator_cpp
mapping = {
    'idl.hpp.em': '%s.hpp',
    'idl__struct.hpp.em': 'detail/%s__struct.hpp',
    'idl__builder.hpp.em': 'detail/%s__builder.hpp',
    'idl__traits.hpp.em': 'detail/%s__traits.hpp',
    ...
}

5.4 rosidl_get_typesupport_target

供同包内其他 target 依赖生成的 typesupport 库：

1
2
3

rosidl_get_typesupport_target(cpp_typesupport_target
  "${PROJECT_NAME}__rosidl_typesupport_cpp" "rosidl_typesupport_cpp")
target_link_libraries(my_node ${cpp_typesupport_target})

6. rosidl_generator_c / rosidl_generator_cpp

6.1 生成产物（以 std_msgs/msg/String 为例）

C 侧（rosidl_generator_c/）：

C++ 侧（rosidl_generator_cpp/）：

6.2 类型映射

IDL → C（BASIC_IDL_TYPES_TO_C）：

• boolean → bool
• octet → uint8_t
• char → signed char
• wchar → uint16_t

IDL → C++（MSG_TYPE_TO_CPP）：

• 基本类型 → uint32_t 等
• string → std::basic_string<char, ...>（allocator 模板参数）
• 嵌套类型 → pkg::msg::Type_<ContainerAllocator>
• 固定数组 → std::array<T, N>
• 动态序列 → std::vector<T, Allocator>

6.3 生成的 CMake Target

每个 interface package 产生多个库 target，后缀模式：

7. rosidl_runtime_c / rosidl_runtime_cpp

7.1 C 运行时

字符串（string.h）：

1
2
3
4
5

typedef struct rosidl_runtime_c__String {
  char * data;
  size_t size;      // 不含 '\0'
  size_t capacity;
} rosidl_runtime_c__String;

宽字符串：u16string.h
动态数组：primitives_sequence.h + *_functions.h
有界序列：sequence_bound.h、string_bound.h

Type support 结构（message_type_support_struct.h）：

1
2
3
4
5

struct rosidl_message_type_support_t {
  const char * typesupport_identifier;
  const void * data;
  rosidl_message_typesupport_handle_function func;
};

• typesupport_identifier：如 "rosidl_typesupport_introspection_cpp"
• func：按 identifier 链式查找其他 typesupport 的 handle
• ROSIDL_GET_MSG_TYPE_SUPPORT(Pkg, msg, MsgName)：获取默认 C typesupport 符号

类似结构存在于 service_type_support_struct.h、action_type_support_struct.h。

消息初始化（message_initialization.h）：ROSIDL_RUNTIME_C_MSG_INIT_ALL / ZERO / DEFAULTS_ONLY 等策略。

7.2 C++ 运行时

traits（traits.hpp）提供通用模板与工具函数：

• rosidl_generator_traits::value_to_yaml() — 各类型 YAML 序列化
• has_fixed_size<T> / has_bounded_size<T> — 类型属性 trait
• is_message<T> / is_service_request<T> / is_action_goal<T> — 类型分类（由 generator 特化）

bounded_vector.hpp：有界动态数组的 C++ 容器实现。

message_initialization.hpp：C++ 侧对应初始化枚举。

8. Typesupport 体系

8.1 接口层（rosidl_typesupport_interface）

统一 符号命名，避免各 typesupport 插件冲突：

1
2
3
4

#define ROSIDL_TYPESUPPORT_INTERFACE__MESSAGE_SYMBOL_NAME( \
    typesupport_name, package_name, interface_type, message_name) \
  typesupport_name ## __get_message_type_support_handle ## __ \
  package_name ## __ ## interface_type ## __ ## message_name

示例符号：rosidl_typesupport_introspection_cpp__get_message_type_support_handle__std_msgs__msg__String

8.2 Introspection Typesupport

用途：运行时反射消息字段——ros2 topic echo、rclpy、参数转换、调试工具。

核心结构（message_introspection.hpp）：

1
2
3
4
5
6
7
8
9
10
11
12

typedef struct MessageMember_s {
  const char * name_;
  uint8_t type_id_;           // ROS_TYPE_FLOAT, ROS_TYPE_MESSAGE, ...
  size_t string_upper_bound_;
  const rosidl_message_type_support_t * members_;  // 嵌套消息
  bool is_array_;
  size_t array_size_;
  bool is_upper_bound_;
  uint32_t offset_;           // 字段在 struct 内偏移
  const void * default_value_;
  // size/get/fetch/assign/resize 函数指针...
} MessageMember;

Identifier（identifier.cpp）：

1

const char * typesupport_identifier = "rosidl_typesupport_introspection_cpp";

Generator 为每个消息生成 MessageMembers 静态表 + get_message_type_support_handle() 导出函数。

8.3 Typesupport 链与 RMW

运行时 publish 路径（简化）：

1
2
3
4
5

rclcpp::Publisher::publish(msg)
  → rosidl_typesupport_cpp::get_message_type_support_handle<Message>()
  → 按 rmw 选择的 typesupport_identifier 查找
  → rosidl_typesupport_fastrtps_cpp（DDS CDR 序列化）
  → rmw_publish

Introspection typesupport 不参与 DDS 线格式序列化，但 Python 层需要它把 C struct 转为 Python 对象。

9. rosidl_cli

独立于 colcon 的 命令行工具（rosidl_cli/cli.py）：

1
2

rosidl generate ...   # 调用已注册 generator 扩展
rosidl translate ...  # 格式转换（如 msg → idl）

通过 rosidl_cli/extensions.py 与 entry_points 可扩展子命令；主要用于工具开发/debug，普通接口包构建走 CMake 路径。

10. 完整示例：从 .msg 到可链接库

10.1 作者侧

my_msgs/msg/Velocity.msg：

1
2

float64 linear
float64 angular

CMakeLists.txt：

1
2
3
4
5
6

find_package(rosidl_default_generators REQUIRED)
rosidl_generate_interfaces(${PROJECT_NAME}
  "msg/Velocity.msg"
)
ament_export_dependencies(rosidl_default_runtime)
ament_package()

package.xml：

1
2
3

<buildtool_depend>rosidl_default_generators</buildtool_depend>
<exec_depend>rosidl_default_runtime</exec_depend>
<member_of_group>rosidl_interface_packages</member_of_group>

10.2 构建时发生的事

10.3 安装布局

1
2
3
4
5
6
7
8
9
10
11

install/my_msgs/
├── share/my_msgs/
│   ├── msg/Velocity.msg
│   ├── msg/Velocity.idl
│   └── cmake/...               # exported targets
├── include/my_msgs/my_msgs/
│   └── msg/velocity.hpp
└── lib/
    ├── libmy_msgs__rosidl_generator_c.so
    ├── libmy_msgs__rosidl_typesupport_introspection_c.so
    └── libmy_msgs__rosidl_typesupport_fastrtps_cpp.so

11. Service 与 Action 的处理差异

CMake 对 .srv 还会在 build 目录拆分出 _Request.msg / _Response.msg，便于 rosidl_interfaces index 与 linter。

12. 关联仓库（非本目录）

find_package(rosidl_default_generators) 会拉入上述外部 generator，使 rosidl_generate_interfaces 一次触发完整工具链。

13. 与 ROS 1 genmsg 对比

14. 调试与常见问题

实用命令：

1
2
3
4
5
6
7
8

# 查看某包安装了哪些接口
cat install/share/my_msgs/rosidl_interfaces

# 单独转换 msg → idl（debug）
rosidl translate msg my_msgs/msg/Velocity.msg --output-idl ...

# 查看生成头文件
ls build/my_msgs/rosidl_generator_cpp/my_msgs/msg/

15. 源码阅读顺序

1. 走通样例：手写最小 msg 包，colcon build 后对照 build/ 与 install/ 生成物
2. 适配层：rosidl_adapter/parser.py → msg/__init__.py → resource/msg.idl.em
3. IDL AST：rosidl_parser/definition.py → parser.py → grammar.lark
4. CMake 编排：rosidl_generate_interfaces.cmake → register_c.cmake
5. 生成框架：rosidl_cmake/__init__.py 的 generate_files()
6. C 生成：rosidl_generator_c/__init__.py + resource/idl__struct.h.em
7. C++ 生成：rosidl_generator_cpp/__init__.py + __traits.hpp.em
8. 运行时：message_type_support_struct.h → traits.hpp
9. Introspection：message_introspection.hpp → rosidl_typesupport_introspection_cpp/resource/msg__type_support.cpp.em
10. 外部衔接：rosidl_typesupport_cpp（另一仓库）→ rmw_fastrtps

16. 小结

rosidl 目录实现 ROS 2 强类型接口的编译期核心：rosidl_adapter 兼容 Legacy 格式，rosidl_parser 提供标准 IDL AST，rosidl_cmake 通过 ament 扩展点 编排多 generator/typesupport 并行生成，rosidl_runtime_* 定义运行时公共类型与 type_support 结构，rosidl_typesupport_introspection_* 提供字段反射能力。

理解「.msg 如何变成 DDS 线上的字节」需串联 本仓库生成链路 与 外部 typesupport_fastrtps + rmw 两段；调试接口问题时，从 rosidl_generate_interfaces 的 build log 与生成的 detail/*__struct.hpp 入手最为直接。

rpyutils 源码详细分析

工作区路径：/home/cp/work2/ros2Learn/ros2_humble/src/ros2/rpyutils
子包数量：1

1. 定位

rpyutils 目录含 1 个 ROS 2 包，工作区路径见下。

2. 子包列表

3. 在 ROS 2 Humble 栈中的关系

见 ros2总览.md 分层图。

4. 推荐阅读顺序

1. 阅读各子包 package.xml 2. 入口源码 3. 下游依赖方

5. 小结

rpyutils 为单包仓库，提供 rpyutils 功能。

rviz 源码详细分析

工作区路径：/home/cp/work2/ros2Learn/ros2_humble/src/ros2/rviz
版本：11.2.26（Humble），子包 8 个，许可证 BSD 3-Clause（Willow Garage / OSRF）。

rviz 仓库实现 ROS 2 的 3D 可视化工具 rviz2：Qt 图形界面 + Ogre3D 渲染引擎 + pluginlib 插件体系（Display / Tool / Panel / ViewController / FrameTransformer）。用户通过订阅 ROS 话题、查询坐标变换，在 3D 场景中绘制激光、点云、机器人模型、TF 等。

范围说明：本仓库为 rviz2 核心；ROS 1 版 rviz 在 ros-visualization/rviz。Humble 尚未移植 Stereo 等少数 ROS 1 功能（见 README）。

1. 总体认识

1.1 核心职责

1.2 在 ROS 2 栈中的位置

1.3 主循环（一帧）

VisualizationManager::onUpdate()（定时器驱动，约 30Hz）：

1
2
3
4
5
6
7

1. executor_->spin_some(10ms)     // 处理 ROS 回调
2. frame_manager_->update()       // 坐标系
3. root_display_group_->update()  // 各 Display 更新 Ogre 对象
4. view_manager_->update()        // 相机/视角
5. selection_manager_->update()
6. current_tool_->update()
7. ogre_root_->renderOneFrame()    // Ogre 渲染（限帧 ≥10ms）

2. 仓库结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

rviz/
├── README.md
├── docs/
│   ├── FEATURES.md
│   ├── plugin_development.md     # ★ 插件开发指南
│   └── migration_guide.md
├── rviz2/                        # 可执行 (~180 行)
│   └── src/main.cpp
├── rviz_common/                  # ★ 框架核心 (~34100 行 C++)
│   ├── include/rviz_common/
│   │   ├── visualization_manager.hpp
│   │   ├── display.hpp / ros_topic_display.hpp
│   │   ├── message_filter_display.hpp
│   │   ├── tool.hpp / panel.hpp / view_controller.hpp
│   │   ├── display_context.hpp
│   │   ├── properties/           # Qt 属性树
│   │   ├── factory/pluginlib_factory.hpp
│   │   ├── transformation/
│   │   └── ros_integration/
│   └── src/rviz_common/
├── rviz_rendering/               # Ogre 封装 (~13400 行)
│   ├── render_system.hpp
│   └── objects/ point_cloud, shape, grid, ...
├── rviz_default_plugins/         # 内置插件 (~51300 行)
│   ├── displays/ laser_scan, image, marker, ...
│   ├── tools/ move_camera, select, ...
│   ├── view_controllers/
│   ├── panels/
│   └── plugins_description.xml
├── rviz_ogre_vendor/
├── rviz_assimp_vendor/
├── rviz_rendering_tests/
└── rviz_visual_testing_framework/

2.1 子包一览