rqt_srv/
├── plugin.xml          # Services → rqt_srv.services.Services
└── src/rqt_srv/
    ├── main.py
    └── services.py

rqt_topic/
├── plugin.xml          # TopicPlugin → rqt_topic.topic.Topic
├── src/rqt_topic/
│   ├── main.py
│   └── topic.py        # Plugin 主类 Topic
└── test/

rqt/
├── rqt/              # meta，聚合依赖
├── rqt_gui/          # ros2 run rqt_gui rqt_gui
├── rqt_gui_py/       # Python 插件 Provider
├── rqt_gui_cpp/      # C++ 插件 Provider
└── rqt_py_common/    # Topic/Node 等 GUI 工具

class Main(Base):
    def __init__(self, filename=None, settings_filename='rqt_gui'):
        qtgui_path = get_package_path('qt_gui')
        super(Main, self).__init__(qtgui_path, ...)

    def main(self, argv=None, standalone=None, ...):
        argv = rclpy.utilities.remove_ros_args(args=argv)
        return super(Main, self).main(argv, standalone=standalone, ...)

rqt_gui
  ├── qt_gui
  ├── python_qt_binding
  ├── rclpy
  └── rqt_gui_py / rqt_gui_cpp

tango_icons_vendor/
├── resource/          # Tango 图标 PNG/SVG 资源
├── CMakeLists.txt     # install 资源到 share
└── package.xml

qt_gui (icon_loader.py) → tango_icons_vendor (share 路径)

B * create() const
{
  return new C;
}

typedef std::map<ClassName, impl::AbstractMetaObjectBase *> FactoryMap;
typedef std::map<BaseClassName, FactoryMap> BaseToFactoryMapMap;

#define CLASS_LOADER_REGISTER_CLASS_INTERNAL_WITH_MESSAGE(Derived, Base, UniqueID, Message) \
  namespace \
  { \
  struct ProxyExec ## UniqueID \
  { \
    ProxyExec ## UniqueID() \
    { \
      class_loader::impl::registerPlugin<_derived, _base>(#Derived, #Base); \
    } \
  }; \
  static ProxyExec ## UniqueID g_register_plugin_ ## UniqueID; \
  }  // namespace

CLASS_LOADER_REGISTER_CLASS(Dog, Base)
CLASS_LOADER_REGISTER_CLASS(Cat, Base)
CLASS_LOADER_REGISTER_CLASS(Duck, Base)
CLASS_LOADER_REGISTER_CLASS(Cow, Base)
CLASS_LOADER_REGISTER_CLASS(Sheep, Base)

setCurrentlyActiveClassLoader(loader);
setCurrentlyLoadingLibraryName(library_path);

if (!isLibraryLoaded()) {
  loadLibrary();
}
Base * obj = class_loader::impl::createInstance<Base>(derived_class_name, this);
// ...
if (managed) {
  ++plugin_ref_count_;
}

loadLibrary(path, loader)
  ├─ 若 isLibraryLoadedByAnybody(path)
  │     └─ addClassLoaderOwnerForAllExistingMetaObjectsForLibrary
  ├─ 否则
  │     ├─ setCurrentlyActiveClassLoader(loader)
  │     ├─ SharedLibrary(path)  → dlopen，触发静态注册
  │     └─ 加入 LoadedLibraryVector
  └─ Graveyard 处理
        ├─ 无新 MetaObject → revivePreviouslyCreateMetaobjectsFromGraveyard
        └─ 有新 MetaObject → purgeGraveyardOfMetaobjects(delete=true)

unloadLibrary(path, loader)
  ├─ 若 hasANonPurePluginLibraryBeenOpened() → 拒绝卸载（全局锁死）
  ├─ destroyMetaObjectsForLibrary → 从 FactoryMap 移除，移入 graveyard
  ├─ 若无任何 MetaObject 仍关联该库
  │     ├─ SharedLibrary::unload_library()
  │     └─ 从 LoadedLibraryVector 移除
  └─ 否则保留 .so（其他 ClassLoader 仍在用）

class_loader
  ├── rcpputils::SharedLibrary   (dlopen 封装)
  ├── console_bridge             (日志 CONSOLE_BRIDGE_logDebug)
  └── ament_cmake / ament_cmake_ros

应用 (rviz / nav2 / ...)
    ↓
pluginlib::ClassLoader<T>     ← plugin.xml + ament_index 解析
    ↓
class_loader::MultiLibraryClassLoader
    ↓
class_loader::ClassLoader + dlopen

#define PLUGINLIB_EXPORT_CLASS(class_type, base_class_type) \
  CLASS_LOADER_REGISTER_CLASS(class_type, base_class_type)

#define RCLCPP_COMPONENTS_REGISTER_NODE(NodeClass) \
  CLASS_LOADER_REGISTER_CLASS( \
    rclcpp_components::NodeFactoryTemplate<NodeClass>, \
    rclcpp_components::NodeFactory)

class_loader/
├── include/class_loader/
│   ├── class_loader.hpp              # 用户主 API
│   ├── multi_library_class_loader.hpp
│   ├── class_loader_core.hpp         # impl 命名空间 + 模板
│   ├── meta_object.hpp               # MetaObject 工厂
│   ├── register_macro.hpp            # CLASS_LOADER_REGISTER_CLASS
│   ├── exceptions.hpp
│   └── visibility_control.hpp        # Windows DLL 导出
├── src/
│   ├── class_loader.cpp              # ClassLoader 方法
│   ├── class_loader_core.cpp         # 全局状态 + load/unload
│   ├── meta_object.cpp               # MetaObject 基类实现
│   └── multi_library_class_loader.cpp
├── cmake/class_loader_hide_library_symbols.cmake
├── class_loader-extras.cmake         # 供插件 CMake 调用 hide symbols
└── test/                             # Dog/Cat 等插件单元测试

kdl_parser/
├── kdl_parser/                    # C++ 库（ament_cmake）
│   ├── include/kdl_parser/
│   │   ├── kdl_parser.hpp         # 公开 API（3 个函数）
│   │   └── visibility_control.hpp
│   ├── src/
│   │   ├── kdl_parser.cpp         # 核心转换逻辑（~210 行）
│   │   └── check_kdl_parser.cpp   # 命令行调试工具
│   └── test/                      # gtest + PR2/r2d2 URDF
├── kdl_parser_py/                 # Python 包
│   └── kdl_parser_py/urdf.py      # 与 C++ 平行的转换逻辑
└── README.md

KDL_PARSER_PUBLIC
bool treeFromFile(const std::string & file, KDL::Tree & tree);

KDL_PARSER_PUBLIC
bool treeFromString(const std::string & xml, KDL::Tree & tree);

KDL_PARSER_PUBLIC
bool treeFromUrdfModel(const urdf::ModelInterface & robot_model, KDL::Tree & tree);

treeFromUrdfModel
  ├─ tree = KDL::Tree(root_link_name)     # 仅设根名，根 link 不建 segment
  ├─ 警告：根 link 有 inertia（KDL 不支持）
  └─ 对每个 root 的子 link 递归 addChildrenToTree
        ├─ toKdl(inertial) → RigidBodyInertia
        ├─ toKdl(parent_joint) → KDL::Joint
        ├─ Segment(link_name, joint, origin, inertia)
        └─ tree.addSegment(segment, parent_link_name)

KDL::Joint toKdl(urdf::JointSharedPtr jnt)
{
  KDL::Frame F_parent_jnt = toKdl(jnt->parent_to_joint_origin_transform);
  // ...
  case urdf::Joint::REVOLUTE: {
      KDL::Vector axis = toKdl(jnt->axis);
      return KDL::Joint(jnt->name, F_parent_jnt.p, F_parent_jnt.M * axis, KDL::Joint::RotAxis);
    }

// URDF 惯性矩阵在 inertial 参考系；KDL 要求在 link 参考系
KDL::RotationalInertia urdf_inertia = ...;
// 用 RigidBodyInertia 运算符 workaround 做旋转
KDL::RigidBodyInertia kdl_inertia_wrt_com_workaround =
  origin.M * KDL::RigidBodyInertia(0, KDL::Vector::Zero(), urdf_inertia);
KDL::RotationalInertia kdl_inertia_wrt_com =
  kdl_inertia_wrt_com_workaround.getRotationalInertia();
return KDL::RigidBodyInertia(kdl_mass, kdl_com, kdl_inertia_wrt_com);

<link name="dummy_link"/>
...
<joint name="dummy_to_base" type="fixed">
  <parent link="dummy_link"/>
  <child link="base_link"/>
</joint>

type_map = {
        'fixed': fixed,
        'revolute': rotational,
        'continuous': rotational,
        'prismatic': translational,
        'floating': fixed,
        'planar': fixed,
        'unknown': fixed,
        }

add_library(${PROJECT_NAME} src/kdl_parser.cpp)
target_link_libraries(${PROJECT_NAME} PUBLIC
  orocos-kdl
  urdfdom_headers::urdfdom_headers)
target_link_libraries(${PROJECT_NAME} PRIVATE
  rcutils::rcutils
  urdf::urdf)

KDL::Tree RobotStatePublisher::parseURDF(const std::string & urdf_xml, urdf::Model & model)
{
  if (!model.initString(urdf_xml)) {
    throw std::runtime_error("Unable to initialize urdf::model from robot description");
  }
  KDL::Tree tree;
  if (!kdl_parser::treeFromUrdfModel(model, tree)) {
    throw std::runtime_error("Failed to extract kdl tree from robot description");
  }
  return tree;
}

pluginlib/
├── pluginlib/                         # C++ 核心（header-only INTERFACE 库）
│   ├── include/pluginlib/
│   │   ├── class_loader.hpp           # 模板 ClassLoader API
│   │   ├── class_loader_imp.hpp       # 实现（~850 行，被 include）
│   │   ├── class_loader_base.hpp      # 非模板管理接口
│   │   ├── class_desc.hpp             # 插件元数据
│   │   ├── class_list_macros.hpp      # PLUGINLIB_EXPORT_CLASS
│   │   ├── exceptions.hpp
│   │   └── impl/split.hpp
│   ├── src/list_plugins.cpp           # CLI 列出插件
│   ├── cmake/                         # 构建/注册宏
│   └── test/
└── ros2plugin/                        # ros2 CLI 插件（Python）
    └── ros2plugin/verb/list.py        # ros2 plugin list

#define PLUGINLIB_EXPORT_CLASS(class_type, base_class_type) \
  CLASS_LOADER_REGISTER_CLASS(class_type, base_class_type)

<plugin_category>__pluginlib__plugin

<library path="test_plugins">
  <class name="test_pluginlib/foo" type="test_plugins::Foo" base_class_type="test_base::Fubar">
    <description>This is a foo plugin.</description>
  </class>
  ...
</library>

PLUGINLIB_EXPORT_CLASS(test_plugins::Foo, test_base::Fubar)
PLUGINLIB_EXPORT_CLASS(test_plugins::Bar, test_base::Fubar)

ClassLoader<T>::ClassLoader(
  std::string package,
  std::string base_class,
  std::string attrib_name,
  std::vector<std::string> plugin_xml_paths)
: ...
  lowlevel_class_loader_(false)  // 非 on-demand，库由 pluginlib 显式 load/unload
{
  ament_index_cpp::get_package_prefix(package_);  // 校验 package 存在
  if (plugin_xml_paths_.empty()) {
    plugin_xml_paths_ = getPluginXmlPaths(package_, attrib_name_);
  }
  classes_available_ = determineAvailableClasses(plugin_xml_paths_);
}

std::string resource_name = package + "__pluginlib__" + attrib_name;
auto plugin_packages_with_prefixes = ament_index_cpp::get_resources(resource_name);
// 每个导出插件的包：prefix + "/" + 相对路径

classes_available.insert(std::pair<std::string, ClassDesc>(lookup_name,
  ClassDesc(lookup_name, derived_class, base_class_type, package_name, description_str,
  library_path, xml_file)));

createUniqueInstance(lookup_name)
  → loadLibraryForClass(lookup_name)
      → getClassLibraryPath(lookup_name)   # 搜索 lib/ lib64/ bin/ ...
      → lowlevel_class_loader_.loadLibrary(path)
  → lowlevel_class_loader_.createUniqueInstance<T>(getClassType(lookup_name))
      # getClassType 返回 XML 中的 type，即 C++ 类名

pluginlib::ClassLoader<void> cl(argv[1], argv[2]);
for (const auto & declared : cl.getDeclaredClasses()) {
  std::cout << declared << std::endl;
}

PluginlibFactory(const QString & package, const QString & base_class_type)
{
  class_loader_ = new pluginlib::ClassLoader<Type>(
    package.toStdString(), base_class_type.toStdString());
}

pluginlib (INTERFACE)
  ├── class_loader
  ├── ament_index_cpp      # 发现 plugin XML
  ├── tinyxml2             # 解析 XML
  ├── rcpputils            # 文件系统、库名
  └── rcutils              # 日志

resource_retriever/
├── resource_retriever/              # 主包（C++ 库 + Python 模块）
│   ├── include/resource_retriever/
│   │   ├── retriever.hpp            # 公共 API
│   │   └── visibility_control.hpp   # 符号导出宏
│   ├── src/
│   │   ├── retriever.cpp            # C++ 实现（~145 行）
│   │   └── resource_retriever/
│   │       └── __init__.py          # Python API
│   ├── test/
│   │   ├── test.cpp                 # gtest
│   │   ├── test.py                  # pytest
│   │   └── test.txt                 # 测试用 package 资源
│   └── CMakeLists.txt
└── libcurl_vendor/                  # libcurl 依赖封装（vendor 或系统库）
    ├── CMakeLists.txt
    ├── libcurl_vendor-extras.cmake.in
    └── env_hook/                    # LD_LIBRARY_PATH / PATH 钩子

struct MemoryResource
{
  MemoryResource()
  : size(0)
  {
  }

  std::shared_ptr<uint8_t> data;
  size_t size;
};

class RESOURCE_RETRIEVER_PUBLIC Retriever
{
public:
  Retriever();
  ~Retriever();
  MemoryResource get(const std::string & url);
private:
  Retriever(const Retriever & ret) = delete;
  CURL * curl_handle_;
};

def get_filename(url, use_protocol=True):
    # package:// → file:// 或纯路径
    ...

def get(url):
    filename = get_filename(url)
    try:
        return urlopen(filename).read()
    except URLError:
        raise Exception('Invalid URL: {}'.format(filename))

class CURLStaticInit
{
public:
  CURLStaticInit()
  {
    CURLcode ret = curl_global_init(CURL_GLOBAL_ALL);
    ...
  }
  ~CURLStaticInit()
  {
    if (initialized_) {
      curl_global_cleanup();
    }
  }
};
static CURLStaticInit g_curl_init;

MemoryResource Retriever::get(const std::string & url)
{
  std::string mod_url = url;
  if (url.find("package://") == 0) {
    mod_url.erase(0, strlen("package://"));
    size_t pos = mod_url.find("/");
    ...
    std::string package = mod_url.substr(0, pos);
    ...
    package_path = ament_index_cpp::get_package_share_directory(package);
    mod_url = "file://" + package_path + mod_url;
  }

package://<package_name>/<relative_path>
         ↓
file://<share_dir>/<relative_path>

package://resource_retriever/test/test.txt
  → file:///opt/ros/humble/share/resource_retriever/test/test.txt

curl_easy_setopt(curl_handle_, CURLOPT_URL, mod_url.c_str());
curl_easy_setopt(curl_handle_, CURLOPT_WRITEFUNCTION, curlWriteFunc);
...
CURLcode ret = curl_easy_perform(curl_handle_);
if (ret != 0) {
  throw Exception(mod_url, error_buffer);
} else if (!buf.v.empty()) {
  res.size = buf.v.size();
  res.data.reset(new uint8_t[res.size], std::default_delete<uint8_t[]>());
  memcpy(res.data.get(), &buf.v[0], res.size);
}

find_package(CURL QUIET)

if(FORCE_BUILD_VENDOR_PKG OR NOT CURL_FOUND)
  build_libcurl()   # ExternalProject 下载 curl-7.81.0
  ament_environment_hooks(...)  # 设置 LD_LIBRARY_PATH / PATH
  set(CURL_FOUND FALSE)
endif()

resource_retriever::MemoryResource getResource(const std::string & resource_path)
{
  resource_retriever::Retriever retriever;
  ...
  try {
    res = retriever.get(resource_path);
  } catch (resource_retriever::Exception & e) {
    RVIZ_COMMON_LOG_DEBUG(e.what());
    return resource_retriever::MemoryResource();
  }
  return res;
}

Ogre::MeshPtr loadMeshFromResource(const std::string & resource_path)
{
  ...
  auto res = getResource(resource_path);
  // .mesh → Ogre MeshSerializer
  // .stl  → STLLoader
  // 其他  → AssimpLoader（dae/obj 等）
}

Assimp::IOStream * Open(const char * file, const char * mode = "rb") override
{
  resource_retriever::MemoryResource res;
  try {
    res = retriever_.get(file);
  } catch (const resource_retriever::Exception & e) {
    return nullptr;
  }
  return new ResourceIOStream(res);
}

void RobotLink::loadMaterialFromTexture(...)
{
  std::string filename = visual->material->texture_filename;
  resource_retriever::Retriever retriever;
  res = retriever.get(filename);  // 可为 package:// 或 http://
  ...
  Ogre::TextureManager::getSingleton().loadImage(...);
}

# Texture resource is a special URI ... acceptable to resource retriever
string texture_resource
...
# mesh_resource uses resource retriever to load a mesh.
string mesh_resource

URDF: package://my_robot/meshes/base.dae
  ↓ robot_state_publisher / rviz 读取
  ↓ resource_retriever::Retriever::get()
  ↓ ament_index: my_robot → /install/my_robot/share/my_robot
  ↓ file:///install/my_robot/share/my_robot/meshes/base.dae
  ↓ libcurl 读入 MemoryResource
  ↓ AssimpLoader::ResourceIOSystem::Open()
  ↓ 解析 dae + 相对路径纹理 package://my_robot/textures/...
  ↓ Ogre::Mesh → rviz 渲染

add_library(${PROJECT_NAME} src/retriever.cpp)
ament_target_dependencies(${PROJECT_NAME}
  ament_index_cpp
  libcurl_vendor
)
ament_python_install_package(${PROJECT_NAME} ...)
ament_export_targets(${PROJECT_NAME} HAS_LIBRARY_TARGET)

resource_retriever
  ├── ament_index_cpp / ament_index_python
  └── libcurl_vendor → libcurl

package://foo/bar/baz.stl
              │    └─ 相对 share 的路径
              └─ ament_index_cpp::get_package_share_directory("foo")
                    → $AMENT_PREFIX_PATH/.../share/foo

robot_state_publisher/
├── include/robot_state_publisher/
│   └── robot_state_publisher.hpp    # RobotStatePublisher 类声明
├── src/
│   └── robot_state_publisher.cpp      # 全部实现（~428 行）
├── launch/                            # URDF/xacro 加载示例（8 个 launch 文件）
├── urdf/                              # 示例 URDF
├── test/                              # launch_testing + gtest 集成测试
├── CMakeLists.txt
├── package.xml
└── README.md

class SegmentPair final
{
public:
  explicit SegmentPair(
    const KDL::Segment & p_segment,
    const std::string & p_root,
    const std::string & p_tip)
  : segment(p_segment), root(p_root), tip(p_tip) {}

  KDL::Segment segment;
  std::string root;  ///< 父 link 名
  std::string tip;   ///< 子 link 名
};

RobotStatePublisher::RobotStatePublisher(const rclcpp::NodeOptions & options)
: rclcpp::Node("robot_state_publisher", options)
{
  std::string urdf_xml = this->declare_parameter("robot_description", std::string(""));
  // 空则尝试从命令行读 URDF 文件（已废弃）
  ...
  double publish_freq = this->declare_parameter("publish_frequency", 20.0);
  this->declare_parameter("frame_prefix", "");
  this->declare_parameter("ignore_timestamp", false);

  tf_broadcaster_ = std::make_unique<tf2_ros::TransformBroadcaster>(this);
  static_tf_broadcaster_ = std::make_unique<tf2_ros::StaticTransformBroadcaster>(this);

  description_pub_ = this->create_publisher<std_msgs::msg::String>(
    "robot_description", rclcpp::QoS(1).transient_local());

  setupURDF(urdf_xml);

  joint_state_sub_ = this->create_subscription<sensor_msgs::msg::JointState>(
    "joint_states", rclcpp::SensorDataQoS(), ...);

  publishFixedTransforms();
  // 参数回调
  param_cb_ = add_on_set_parameters_callback(...);
  parameter_subscription_ = rclcpp::AsyncParametersClient::on_parameter_event(...);
}

KDL::Tree RobotStatePublisher::parseURDF(const std::string & urdf_xml, urdf::Model & model)
{
  if (!model.initString(urdf_xml)) {
    throw std::runtime_error("Unable to initialize urdf::model from robot description");
  }
  KDL::Tree tree;
  if (!kdl_parser::treeFromUrdfModel(model, tree)) {
    throw std::runtime_error("Failed to extract kdl tree from robot description");
  }
  return tree;
}

void RobotStatePublisher::setupURDF(const std::string & urdf_xml)
{
  urdf::Model model;
  KDL::Tree tree = parseURDF(urdf_xml, model);

  // 构建 mimic 映射（显式拷贝 JointMimic，避免悬空引用）
  mimic_.clear();
  for (...) {
    if (i.second->mimic) {
      auto jm = std::make_shared<urdf::JointMimic>();
      jm->offset = i.second->mimic->offset;
      jm->multiplier = i.second->mimic->multiplier;
      jm->joint_name = i.second->mimic->joint_name;
      mimic_[i.first] = jm;
    }
  }

  segments_.clear();
  segments_fixed_.clear();
  addChildren(model, tree.getRootSegment());

  // 发布 URDF 到 /robot_description
  description_pub_->publish(...);
}

void RobotStatePublisher::addChildren(...)
{
  const std::string & root = GetTreeElementSegment(segment->second).getName();
  for (children ...) {
    const KDL::Segment & child = GetTreeElementSegment(children[i]->second);
    SegmentPair s(..., root, child.getName());
    if (child.getJoint().getType() == KDL::Joint::None) {
      if (model.getJoint(...) && ...->type == urdf::Joint::FLOATING) {
        // 浮动关节：不加入任何 map
      } else {
        segments_fixed_.insert(...);  // 固定关节 → tf_static
      }
    } else {
      segments_.insert(...);  // 可动关节 → /tf
    }
    addChildren(model, children[i]);
  }
}

geometry_msgs::msg::TransformStamped kdlToTransform(const KDL::Frame & k)
{
  geometry_msgs::msg::TransformStamped t;
  t.transform.translation.x = k.p.x();
  ...
  k.M.GetQuaternion(t.transform.rotation.x, ...);
  return t;
}

void RobotStatePublisher::publishTransforms(
  const std::map<std::string, double> & joint_positions,
  const builtin_interfaces::msg::Time & time)
{
  std::string frame_prefix = get_parameter("frame_prefix").get_value<std::string>();
  for (const auto & jnt : joint_positions) {
    auto seg = segments_.find(jnt.first);
    if (seg != segments_.end()) {
      geometry_msgs::msg::TransformStamped tf_transform =
        kdlToTransform(seg->second.segment.pose(jnt.second));
      tf_transform.header.stamp = time;
      tf_transform.header.frame_id = frame_prefix + seg->second.root;
      tf_transform.child_frame_id = frame_prefix + seg->second.tip;
      tf_transforms.push_back(tf_transform);
    }
  }
  tf_broadcaster_->sendTransform(tf_transforms);
}

joint1 转 π 弧度 → link1→link2 的 TF translation.x ≈ 5.0

void RobotStatePublisher::publishFixedTransforms()
{
  for (const auto & seg : segments_fixed_) {
    geometry_msgs::msg::TransformStamped tf_transform =
      kdlToTransform(seg.second.segment.pose(0));  // q=0
    tf_transform.header.stamp = now;
    ...
  }
  static_tf_broadcaster_->sendTransform(tf_transforms);
}

void RobotStatePublisher::callbackJointState(...)
{
  // 1. 校验 name.size == position.size
  // 2. 检测时间回退（bag 回放）→ 清空 last_publish_time_
  // 3. 节流判断
  // 4. 构建 joint_positions map
  // 5. 处理 mimic 关节
  // 6. publishTransforms
  // 7. 更新 last_publish_time_
}

for (const auto & i : mimic_) {
  if (joint_positions.find(i.second->joint_name) != joint_positions.end()) {
    double pos = joint_positions[i.second->joint_name] * i.second->multiplier +
      i.second->offset;
    joint_positions.insert(std::make_pair(i.first, pos));
  }
}

rclcpp::Time current_time(state->header.stamp);
double publish_freq = this->get_parameter("publish_frequency").get_value<double>();
std::chrono::milliseconds publish_interval_ms =
  std::chrono::milliseconds(static_cast<uint64_t>(1000.0 / publish_freq));
rclcpp::Time max_publish_time = last_published + rclcpp::Duration(publish_interval_ms);
if (get_parameter("ignore_timestamp").get_value<bool>() ||
    current_time.nanoseconds() >= max_publish_time.nanoseconds())

rcl_interfaces::msg::SetParametersResult RobotStatePublisher::parameterUpdate(...)
{
  if (parameter.get_name() == "robot_description") {
    if (new_urdf.empty()) { result.successful = false; ... }
    try { parseURDF(new_urdf, dummy_model); } catch (...) { result.successful = false; }
  }
  ...
}

void RobotStatePublisher::onParameterEvent(...)
{
  if (event->node != this->get_fully_qualified_name()) return;
  // 过滤 robot_description CHANGED
  setupURDF(it.second->value.string_value);
  publishFixedTransforms();
}

rclcpp_components_register_node(${PROJECT_NAME}_node
  PLUGIN "robot_state_publisher::RobotStatePublisher"
  EXECUTABLE robot_state_publisher)

robot_state_publisher
  ├── urdf              # URDF 解析 (urdf::Model)
  ├── kdl_parser        # URDF → KDL::Tree
  ├── orocos_kdl        # KDL::Segment::pose()
  ├── tf2_ros           # TransformBroadcaster / StaticTransformBroadcaster
  ├── rclcpp            # Node、参数、订阅
  ├── rclcpp_components # 组件注册
  ├── sensor_msgs       # JointState
  ├── geometry_msgs     # TransformStamped
  └── std_msgs          # robot_description

launch 读取 robot.urdf / xacro
  ↓ 设置 robot_description 参数
robot_state_publisher 启动
  ↓ urdf::Model + kdl_parser → KDL::Tree
  ↓ addChildren → segments_ / segments_fixed_
  ↓ publishFixedTransforms() → /tf_static
  ↓ publish robot_description (transient_local)

joint_state_publisher / controller
  ↓ /joint_states {name, position}
callbackJointState
  ↓ mimic 计算
  ↓ segment.pose(q) → TransformStamped
  ↓ /tf

rviz / MoveIt / nav2
  ↓ tf2 Buffer 查询 link 位姿

ros_environment/
├── CMakeLists.txt              # 唯一“逻辑”文件：定义变量 + 注册 hooks
├── package.xml
├── LICENSE
└── env-hooks/                  # 环境钩子模板（.in → configure_file 展开）
    ├── 0.ros_distro_check.sh.in    # 发行版混用警告（仅 Unix）
    ├── 1.ros_distro.{sh,dsv,bat}.in
    ├── 1.ros_version.{sh,dsv,bat}.in
    ├── 1.ros_python_version.{sh,dsv,bat}.in
    └── 1.ros_localhost_only.{sh,dsv,bat}.in

cmake_minimum_required(VERSION 3.5)
project(ros_environment NONE)
find_package(ament_cmake_core REQUIRED)

set(ROS_LOCALHOST_ONLY "0")
set(ROS_VERSION "2")
set(ROS_PYTHON_VERSION "3")

# allow overriding the distro name
if(DEFINED ENV{ROS_DISTRO_OVERRIDE})
  set(ROS_DISTRO $ENV{ROS_DISTRO_OVERRIDE})
else()
  set(ROS_DISTRO "humble")
endif()

set(
  hooks
  "1.ros_distro"
  "1.ros_localhost_only"
  "1.ros_python_version"
  "1.ros_version"
)
set(shells "dsv")
if(CMAKE_HOST_UNIX)
  list(APPEND shells "sh")
else()
  list(APPEND shells "bat")
endif()
foreach(hook ${hooks})
  foreach(shell ${shells})
    ament_environment_hooks(
      "${CMAKE_CURRENT_SOURCE_DIR}/env-hooks/${hook}.${shell}.in")
  endforeach()
endforeach()
if(CMAKE_HOST_UNIX)
  ament_environment_hooks(
    "${CMAKE_CURRENT_SOURCE_DIR}/env-hooks/0.ros_distro_check.sh.in")
endif()

ament_package()

# generated from ros_environment/env-hooks/1.ros_distro.sh.in

export ROS_DISTRO=@ROS_DISTRO@

set;ROS_DISTRO;@ROS_DISTRO@

# generated from ros_environment/env-hooks/0.ros_distro.sh.in

if [ -n "$ROS_DISTRO" -a "$ROS_DISTRO" != "@ROS_DISTRO@" ]; then
  echo "ROS_DISTRO was set to '$ROS_DISTRO' before. Please make sure that the environment does not mix paths from different distributions." >&2
fi

if os.environ['ROS_DISTRO'] <= 'humble':
    import rosidl_cmake as rosidl_pycommon
else:
    import rosidl_pycommon

set;ROS_VERSION;@ROS_VERSION@

set;ROS_PYTHON_VERSION;@ROS_PYTHON_VERSION@

set-if-unset;ROS_LOCALHOST_ONLY;@ROS_LOCALHOST_ONLY@

REM generated from ros_environment/env-hooks/1.ros_localhost_only.bat.in

if "%ROS_LOCALHOST_ONLY%" == "" (
  set ROS_LOCALHOST_ONLY=@ROS_LOCALHOST_ONLY@
)

# generated from ros_environment/env-hooks/1.ros_localhost_only.sh.in

if [ -n "$ROS_LOCALHOST_ONLY" ]; then
  export ROS_LOCALHOST_ONLY=@ROS_LOCALHOST_ONLY@
fi

rcl_ret_t
rcl_get_localhost_only(rmw_localhost_only_t * localhost_only)
{
  ...
  get_env_error_str = rcutils_get_env(RCL_LOCALHOST_ENV_VAR, &ros_local_host_env_val);
  ...
  *localhost_only = (ros_local_host_env_val != NULL &&
    strcmp(ros_local_host_env_val, "1") == 0) ?
    RMW_LOCALHOST_ONLY_ENABLED : RMW_LOCALHOST_ONLY_DISABLED;
  return RCL_RET_OK;
}

def _set_if_unset(name, value):
    global env_state
    line = FORMAT_STR_SET_ENV_VAR.format_map(
        {'name': name, 'value': value})
    if env_state.get(name, os.environ.get(name)):
        line = FORMAT_STR_COMMENT_LINE.format_map({'comment': line})
    return [line]

install/ros_environment/share/ros_environment/
├── environment/
│   ├── 0.ros_distro_check.sh
│   ├── 1.ros_distro.sh / .dsv / .bat
│   ├── 1.ros_version.sh / .dsv / .bat
│   ├── 1.ros_python_version.sh / .dsv / .bat
│   └── 1.ros_localhost_only.sh / .dsv / .bat
├── local_setup.dsv          # 本包 hook 索引
└── package.dsv              # 指向 local_setup.*

ros_environment
  └── ament_cmake_core    # 仅需 CMake 基础设施