构建系统支持通过 rust_bindgen 模块类型生成 bindgen 绑定。Bindgen 为 C 库提供 Rust FFI 绑定（具有一些有限的 C++ 支持，这需要设置 cppstd 属性）。

rust_bindgen 的基本用法

下面展示了如何定义一个使用 bindgen 的模块，以及如何将该模块用作 crate。如果您需要通过 include!() 宏使用 bindgen 绑定（例如用于外部代码），请参阅源代码生成器页面。

要从 Rust 调用的 C 库示例

以下示例 C 库定义了一个结构体和函数，供 Rust 使用。

external/rust/libbuzz/libbuzz.h

typedef struct foo {
    int x;
} foo;

void fizz(int i, foo* cs);

external/rust/libbuzz/libbuzz.c

#include <stdio.h>
#include "libbuzz.h"

void fizz(int i, foo* my_foo){
    printf("hello from c! i = %i, my_foo->x = %i\n", i, my_foo->x);
}

定义 rust_bindgen 模块

定义一个封装容器标头 external/rust/libbuzz/libbuzz_wrapper.h，其中包含所有相关的标头

// Include headers that are required for generating bindings in a wrapper header.
#include "libbuzz.h"

将 Android.bp 文件定义为 external/rust/libbuzz/Android.bp

cc_library {
    name: "libbuzz",
    srcs: ["libbuzz.c"],
}

rust_bindgen {
     name: "libbuzz_bindgen",

     // Crate name that's used to generate the rust_library variants.
     crate_name: "buzz_bindgen",

     // Path to the wrapper source file.
     wrapper_src: "libbuzz_wrapper.h",

     // 'source_stem' controls the output filename.
     // This is the filename that's used in an include! macro.
     //
     // In this case, we just use "bindings", which produces
     // "bindings.rs".
     source_stem: "bindings",

     // Bindgen-specific flags and options to customize the bindings.
     // See the bindgen manual for more information.
     bindgen_flags: ["--verbose"],

     // Clang flags to be used when generating the bindings.
     cflags: ["-DSOME_FLAG"],

     // Shared, static, and header libraries which export the necessary
     // include directories must be specified.
     //
     // These libraries will also be included in the crate if static,
     // or propagated to dependents if shared.
     // static_libs: ["libbuzz"]
     // header_libs: ["libbuzz"]
     shared_libs: ["libbuzz"],
}

要详细了解如何使用 bindgen 标志，请参阅 bindgen 手册中关于自定义生成的绑定的部分。

如果您使用本部分定义了一个 rust_bindgen 模块作为使用 include!() 宏的先决条件，请返回到“源代码生成器”页面上的先决条件。否则，请继续阅读下一部分。

将绑定用作 crate

使用以下内容创建 external/rust/hello_bindgen/Android.bp

rust_binary {
   name: "hello_bindgen",
   srcs: ["main.rs"],

   // Add the rust_bindgen module as if it were a rust_library dependency.
   rustlibs: ["libbuzz_bindgen"],
}

使用以下内容创建 external/rust/hello_bindgen/src/main.rs

//! Example crate for testing bindgen bindings

fn main() {
    let mut x = buzz_bindgen::foo { x: 2 };
    unsafe { buzz_bindgen::fizz(1, &mut x as *mut buzz_bindgen::foo) }
}

最后，调用 m hello_bindgen 以构建二进制文件。

测试 Bindgen 绑定

Bindgen 绑定通常包含许多生成的布局测试，以防止内存布局不匹配。AOSP 建议您为这些测试定义一个测试模块，并使这些测试作为项目正常测试套件的一部分运行。

可以通过在 external/rust/hello_bindgen/Android.bp 中定义 rust_test 模块来轻松生成这些测试的测试二进制文件

rust_test {
    name: "bindings_test",
    srcs: [
        ":libbuzz_bindgen",
    ],
    crate_name: "buzz_bindings_test",
    test_suites: ["general-tests"],
    auto_gen_config: true,

    // Be sure to disable lints as the generated source
    // is not guaranteed to be lint-free.
    clippy_lints: "none",
    lints: "none",
}

可见性和链接

生成的绑定通常非常小，因为它们由类型定义、函数签名和相关常量组成。因此，动态链接这些库通常是浪费的。我们已禁用这些模块的动态链接，以便通过 rustlibs 使用它们将自动选择静态变体。

默认情况下，rust_bindgen 模块的 visibility 属性为 [":__subpackages__"]，这将仅允许同一 Android.bp 文件或目录层次结构中位于其下方的模块看到它。这有两个目的

• 它可以阻止在树中的其他位置使用原始 C 绑定。
• 它可以避免静态和动态链接混合导致的菱形链接问题。

通常，您应该围绕您在与绑定相同的目录树中添加的生成模块提供一个安全封装容器库，供其他开发者使用。如果这对您的用例不起作用，您可以向 visibility 添加其他软件包。添加其他可见性范围时，请注意不要添加将来可能链接到同一进程中的两个范围，因为这可能会导致链接失败。

值得注意的 rust_bindgen 属性

下面定义的属性是对适用于所有模块的重要通用属性的补充。这些属性对于 Rust bindgen 模块尤其重要，或者表现出 rust_bindgen 模块类型特有的独特行为。

stem、name、crate_name

rust_bindgen 生成库变体，因此它们与 rust_library 模块在 stem、name 和 crate_name 属性方面具有相同的要求。有关参考，请参阅值得注意的 Rust 库属性。

wrapper_src

这是封装容器标头文件的相对路径，其中包含这些绑定所需的标头。文件扩展名决定了如何解释标头，并决定了默认情况下使用哪个 -std 标志。除非扩展名为 .hh 或 .hpp，否则这被假定为 C 标头。如果您的 C++ 标头必须具有其他扩展名，请设置 cpp_std 属性以覆盖假定文件为 C 文件的默认行为。

source_stem

这是生成的源文件的文件名。即使您将绑定用作 crate，也必须定义此字段，因为 stem 属性仅控制生成的库变体的输出文件名。如果模块依赖于多个源生成器（例如 bindgen 和 protobuf）作为源代码，而不是通过 rustlibs 作为 crate，您必须确保作为该模块依赖项的所有源生成器都具有唯一的 source_stem 值。依赖模块从 srcs 中定义的所有 SourceProvider 依赖项复制源代码到公共 OUT_DIR 目录，因此 source_stem 中的冲突将导致生成的源文件在 OUT_DIR 目录中被覆盖。

c_std

这是一个字符串，表示要使用的 C 标准版本。有效值如下所示

• 特定版本，例如 "gnu11"。
• "experimental"，这是构建系统在 build/soong/cc/config/global.go 中定义的值，可能会在可用时使用草案版本（如 C++1z）。
• 未设置或 ""，表示应使用构建系统默认值。

如果设置了此项，则会忽略文件扩展名，并且标头被假定为 C 标头。这不能与 cpp_std 同时设置。

cpp_std

cpp_std 是一个字符串，表示要使用的 C 标准版本。有效值

• 特定版本，例如 "gnu++11"
• "experimental"，这是构建系统在 build/soong/cc/config/global.go 中定义的值，可能会在可用时使用草案版本（如 C++1z）。
• 未设置或 ""，表示应使用构建系统默认值。

如果设置了此项，则会忽略文件扩展名，并且标头被假定为 C++ 标头。这不能与 c_std 同时设置。

cflags

cflags 提供了解释标头所需的 Clang 标志的字符串列表。

custom_bindgen

对于高级用例，bindgen 可以用作库，提供可以作为自定义 Rust 二进制文件一部分进行操作的 API。custom_bindgen 字段采用 rust_binary_host 模块的模块名称，该模块使用 bindgen API 而不是普通的 bindgen 二进制文件。

此自定义二进制文件必须以类似于 bindgen 的方式接收参数，例如

$ my_bindgen [flags] wrapper_header.h -o [output_path] -- [clang flags]

大部分工作由 bindgen 库本身处理。要查看此用法的示例，请访问external/rust/crates/libsqlite3-sys/android/build.rs。

此外，完整的库属性集可用于控制库的编译，尽管这些属性很少需要定义或更改。

handle_static_inline 和 static_inline_library

这两个属性旨在一起使用，并允许为静态内联函数生成封装容器，这些封装容器可以包含在导出的 bindgen 绑定中。

要使用它们，请设置 handle_static_inline: true 并将 static_inline_library 设置为相应的 cc_library_static，后者将 rust_bindgen 模块定义为源代码输入。

用法示例

    rust_bindgen {
        name: "libbindgen",
        wrapper_src: "src/any.h",
        crate_name: "bindgen",
        stem: "libbindgen",
        source_stem: "bindings",

        // Produce bindings for static inline fucntions
        handle_static_inline: true,
        static_inline_library: "libbindgen_staticfns"
    }

    cc_library_static {
        name: "libbindgen_staticfns",

        // This is the rust_bindgen module defined above
        srcs: [":libbindgen"],

        // The include path to the header file in the generated c file is
        // relative to build top.
        include_dirs: ["."],
    }