如果您需要从 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_goldensGN 参数重新构建: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 的头文件。它们是源路径,而不是标签,因此拥有它们的文件包无需导出它们。