feat(ostool): expose prepared runtime board APIs

[ZR233]

问题

外部调用者在使用 cargo_build 拿到构建产物后，如果需要先对 ELF 做额外处理，再交给 QEMU、U-Boot 或 board runner 使用，目前缺少明确的公开 API。尤其是 board 路径只能通过构造一个 Custom build config 来导入已处理的 ELF，这会让调用方伪造 build_cmd，语义不清晰。

修改

• 新增 build::RuntimeArtifactInput，用于描述已经构建好的 ELF、是否生成 BIN、可选 Cargo artifact 目录以及是否 strip ELF。
• 新增 build::prepare_runtime_artifact(...)，把调用方已经处理好的 ELF 重新应用到 invocation 的 runtime artifacts 中。
• 将 board::run_prepared_board(...) 暴露为 public API，用于直接运行已经准备好的 runtime artifacts。
• 更新 public API trybuild 覆盖，确保新增 API 对外可用。
• 增加单元测试，验证 prepare_runtime_artifact 会记录 ELF、Cargo artifact 目录和 runtime artifact 状态。

设计逻辑

cargo_build 负责构建并返回 Cargo 报告的产物路径；调用者可以在该路径上做额外处理，然后通过 prepare_runtime_artifact 显式刷新 ostool 的 runtime artifact 状态。之后 prepared runner 可以直接消费这些 artifacts。这样避免调用方为了复用 board 运行流程而伪造 Custom { build_cmd: "true", ... }。

验证

• cargo fmt --check
• cargo clippy -p ostool --all-targets -- -D warnings
• cargo test -p ostool

此外，在下游 axbuild 中临时使用本地 path patch 验证过：

• cargo xtask clippy --package axbuild
• cargo test -p axbuild starry
• Starry 代表性 QEMU 用例单测全部通过

[mai-team-app]

审查总结

本次 PR 为 ostool 暴露了三个公开 API，使外部调用者能够在 cargo_build 之后对 ELF 做额外处理，再交给 QEMU/U-Boot/board runner 使用，无需伪造 Custom build config。

变更内容

文件	变更
ostool/src/build/mod.rs	新增 RuntimeArtifactInput 结构体（builder 模式）、prepare_runtime_artifact() 公开函数及对应单元测试
ostool/src/board/mod.rs	run_prepared_board 从 pub(crate) 提升为 pub，移除 scope 参数改为内部获取，添加文档注释
ostool/tests/ui/pass_module_level_apis.rs	更新 trybuild UI 测试覆盖新增 API

代码质量

• ✅ Rust 惯用法：RuntimeArtifactInput 采用经典的 builder 模式（new → with_cargo_artifact_dir → strip_elf），API 设计清晰。
• ✅ 文档注释：新增公开函数和结构体均附有 /// 文档注释，说明了使用场景。
• ✅ 测试覆盖：新增单元测试 prepare_runtime_artifact_records_external_artifact_state 验证了 elf、cargo_artifact_dir、runtime_arch 等状态记录；trybuild UI 测试覆盖了新增 API 的公开性。
• ✅ 签名简化：run_prepared_board 移除 scope 参数改为内部调用 invocation.variable_scope()，调用方代码更简洁，且不会破坏外部使用（原为 pub(crate)）。
• ✅ 一致性：prepare_runtime_artifact 内部复用了 prepare_runtime_artifact_outputs 和 RuntimeArtifactOptions，与 apply_cargo_build_outcome 路径保持一致。

验证结果

• cargo fmt --check ✅
• cargo clippy -p ostool --all-targets -- -D warnings ✅（无警告）
• cargo test -p ostool ✅（233 个测试全部通过，含 trybuild UI 测试和 doctest）

结论

代码质量好，API 设计合理，测试充分。建议合并。

Powered by mimo-v2.5-pro