使用 bindgen 集成 C/C++

如果您需要从 Rust 调用某些 C 或 C++ API,可以使用 bindgen,它会从 C 和 C++ 头文件生成 Rust 代码。如需查看更多文档,请参阅 bindgen 用户指南。

生成 Rust 绑定

Fuchsia 提供了 rustc_bindgen_golden GN 模板,用于从 C/C++ 头文件生成 Rust 绑定,并确保这些绑定保持最新状态。此模板会在构建期间运行 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 失败消息中提供的 cp 命令,将生成的文件复制到已签入的文件上。
  • 使用设置为 true 的 update_goldens GN 参数重新构建:

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

    构建完成并更新文件后,将 update_goldens 实参还原为 false(或将其移除),以确保将来能捕获不匹配的情况。

在 Bazel 中

BUILD.bazel 文件可以使用 //build/bazel/rules/rust:rustc_bindgen.bzl 中的 rustc_bindgen_golden() 宏。其属性与 GN 模板的参数同名,bazel2gn 会将其转换为 GN 模板。将该目标添加到用于编译签入文件的 rustc_library() 的 validations 属性中:

load("//build/bazel/rules/rust:rustc_bindgen.bzl", "rustc_bindgen_golden")
load("//build/bazel/rules/rust:rustc_library.bzl", "rustc_library")

rustc_bindgen_golden(
    name = "my_bindings_golden",
    checked_in_source = "src/bindings.rs",
    headers = ["//sdk/lib/foo/include/lib/foo/foo.h"],
    notice_year = 2026,
    deps = ["//sdk/lib/foo"],
)

rustc_library(
    name = "my_library",
    srcs = [
        "src/bindings.rs",
        "src/lib.rs",
    ],
    edition = "2024",
    validations = [":my_bindings_golden"],
)

与 GN 不同,headers 必须是 deps 的头文件。它们是源路径,而不是标签,因此拥有它们的文件包无需导出它们。