附属文件生成

本章解释 Roplat 的 two-pass 机制和双本地后端。

为什么需要 two-pass

build.rs 执行早于过程宏完整展开，构建脚本不能直接读取宏结果。

因此采用两阶段：

1. Pass 1: Extraction

2. 子进程 cargo check

3. 宏在 ROPLAT_PHASE=EXTRACT 下写出 manifest

4. Pass 2: Generation

5. roplat_build 读取 manifest

6. 生成节点/消息/桥接文件

7. Native Build

8. 根据配置选择 cc 或 cmake

9. 编译 C++ 桥接和附加本地源

清单类型

1. msg：透明消息
2. opaque：不透明数据
3. node：多语言节点

当前生成规则

1. 节点

2. 系统文件可覆盖

3. 用户文件首次生成后不覆盖

4. 透明消息

5. 生成系统管理文件（默认 C 头文件）

6. 不透明数据

7. 默认只生成目标语言用户文件

8. Rust 侧仅保留类型标记

双本地后端

roplat_build 提供统一配置入口，后端可切换：

1. cc

2. 轻量、依赖少

3. 适合简单桥接

4. cmake

5. 适合复杂 C++ 依赖

6. 可配合 find_package 接入 Eigen/OpenCV 等

build.rs 典型写法

use roplat_build::{BuildOrchestrator, NativeBackend, NativeBuildConfig};

fn main() {
  if std::env::var("ROPLAT_PHASE").as_deref() == Ok("EXTRACT") {
    return;
  }

  let backend = NativeBackend::from_env("ROPLAT_NATIVE_BACKEND")
    .unwrap_or(NativeBackend::Cc);

  let native = NativeBuildConfig::new()
    .backend(backend)
    .library_name("roplat_nodes_cpp")
    .include_dir("cpp/src");

  BuildOrchestrator::new()
    .native_build(native)
    .build()
    .expect("Code generation failed");
}

建议

1. 新人默认先用 cc 跑通链路。
2. 确认业务需要后再迁移 cmake。
3. 每次改动后执行 cargo clippy --workspace --all-targets -- -D warnings。