建構系統支援透過 rust_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 旗標，請參閱「繫結產生手冊」一節 「自訂產生的繫結」一節。

如果您使用本節定義 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 繫結。
• 避免混合靜態和動態連結發生鑽石連結問題。

通常，您應在與綁定項目相同的目錄樹狀結構中，為產生的模組提供安全的包裝函式程式庫，以供其他開發人員使用。如果這對您的用途不利，您可以將其他套件新增至瀏覽權限。新增其他瀏覽範圍時，請注意不要新增兩個日後可能會連結至相同程序的範圍，否則連結可能會失敗。

值得注意的 rust_bindgen 屬性

除了適用於所有模組的重要通用屬性以外，下方定義的屬性也適用於所有模組。這些對 Rust 而言特別重要 bindgen 模組，或呈現 rust_bindgen 模組類型特有的行為。

stem、name、crate_name

rust_bindgen 會產生程式庫變化版本，因此這些變化版本會與 rust_library 模組共用 stem、name 和 crate_name 屬性的相同需求。如需參考資料，請參閱「值得注意的 Rust 程式庫屬性」。

wrap_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_標準

這是一個字串，代表要使用的 C-standard 版本。有效值 ：

• 特定版本，例如 "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 提供了正確解讀 標題。

custom_bindgen

如果是進階用途，bindgen 可做為程式庫使用， 且可做為自訂 Rust 二進位檔的一部分進行操作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

這兩項屬性必須搭配使用 靜態內嵌函式 (可納入匯出項目) 的包裝函式 繫結機制繫結

如要使用這些功能，請將 handle_static_inline: true 設為 static_inline_library 將 rust_bindgen 模組定義為對應的 cc_library_static 輸入來源名稱

使用範例：

    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: ["."],
    }