使用 bindgen 集成 C/C++

如果您需要从 Rust 调用某些 C 或 C++ API，可以使用 bindgen，该工具可根据 C 和 C++ 标头生成 Rust 代码。如需了解更多文档，请参阅 bindgen 用户指南。

生成 Rust 绑定

Fuchsia 提供 rustc_bindgen_golden GN 模板，用于从 C/C++ 标头生成 Rust 绑定，并确保这些绑定始终保持最新状态。此模板在 build 期间运行 bindgen，并将输出与已签入的“黄金”文件进行比较。

1. 定义 GN 目标

导入模板并在 BUILD.gn 中定义 rustc_bindgen_golden 目标。

例如，请参阅 //src/lib/usb_rs/BUILD.gn：

import("//build/rust/rustc_bindgen.gni")

rustc_bindgen_golden("my_bindings_golden") {
  header = "my_header.h"
  checked_in_source = "src/bindings.rs"

  # Optional: configure bindgen behavior
  # e.g., allowlist, denylist, raw_lines, etc.
  # see //build/rust/rustc_bindgen.gni for all options
}

2. 配置 Rust 目标

您必须将黄金目标添加到使用绑定的 Rust 目标的 validations 参数中，以确保检查在构建过程中运行：

rustc_library("my_library") {
  edition = "2024"
  sources = [
    "src/lib.rs",
    "src/bindings.rs",
  ]
  # ...

  validations = [ ":my_bindings_golden" ]
}

在 Rust 代码中，您随后可以使用生成的绑定（例如 mod bindings;）。

3. 更新已签入的绑定

如果 C 标头发生更改，构建将会失败，因为生成的绑定将不再与已签入的文件匹配。build 输出将显示 diff（差异比较）以及有关如何更新文件的说明。

如需更新已签入的文件，您可以执行以下任一操作：

• 使用 build 失败消息中提供的 cp 命令，将生成的文件复制到已签入的文件上。

• 使用 update_goldens GN 实参设置为 true 的方式重新构建：

  fx set ... --args=update_goldens=true
  fx build
  

  在 build 完成并更新文件后，将 update_goldens 实参恢复为 false（或将其移除），以确保捕获未来的不匹配情况。