Android Rust 模組

一般原則是，rust_* 模組定義必須緊密遵循 cc_* 的使用方式和預期。以下是 Rust 二進位檔模組定義範例：

rust_binary {
    name: "hello_rust",
    crate_name: "hello_rust",
    srcs: ["src/hello_rust.rs"],
    host_supported: true,
}

本頁面將介紹 rust_* 模組最常見的屬性。如要進一步瞭解特定模組類型和模組定義範例，請參閱「二進位模組」、「程式庫模組」或「測試模組」。

基本模組類型

類型定義瞭解詳情
rust_binaryRust 二進位檔 「Binary Modules」頁面
rust_library產生 Rust 程式庫，並提供 rlib 和 dylib 變化版本。 rust_library，Library Modules 頁面。
rust_ffi產生 Rust C 程式庫，可供 cc 模組使用，並提供靜態和共用變化版本。 rust_ffi，Library Modules 頁面
rust_proc_macro產生 proc-macro Rust 程式庫。(這些類似於編譯器外掛程式)。 rust_proc_macro，程式庫模組頁面
rust_test產生使用標準 Rust 測試輔助工具的 Rust 測試二進位檔。 「Test Modules」頁面
rust_fuzz利用 libfuzzer 產生 Rust 模糊二進位檔。 rust_fuzz 模組範例
rust_protobuf產生來源並產生 Rust 程式庫，為特定 protobuf 提供介面。 「Protobuf 模組」和「來源產生器」頁面
rust_bindgen產生來源並產生 Rust 程式庫，其中包含 Rust 與 C 程式庫的繫結。 Bindgen 繫結模組和來源產生器頁面

重要常用屬性

這些屬性適用於所有 Android Rust 模組。與個別 Rust 模組相關聯的任何額外 (專屬) 屬性，都會列在該模組的頁面中。

name

name 是模組的名稱。如同其他 Soong 模組，此值在大多數 Android.bp 模組類型中不得重複。根據預設，系統會使用 name 做為輸出檔案名稱。如果輸出檔案名稱必須與模組名稱不同，請使用 stem 屬性定義輸出檔案名稱。

莖

stem (選用) 可直接控管輸出檔案名稱 (不含檔案副檔名和其他後置字串)。舉例來說，根值為 libfoo 的 rust_library_rlib 程式庫會產生 libfoo.rlib 檔案。如果您未為 stem 屬性提供值，輸出檔案名稱會預設採用模組名稱。

如果無法將模組名稱設為所需的輸出檔案名稱，請使用 stem 函式。舉例來說，log crate 的 rust_library 名稱為 liblog_rust，因為 liblog cc_library 已存在。在這種情況下，使用 stem 屬性可確保輸出檔案的名稱為 liblog.*，而非 liblog_rust.*。

srcs

srcs 包含單一來源檔案，代表模組的進入點 (通常是 main.rs 或 lib.rs)。rustc 會處理解析和探索編譯所需的所有其他來源檔案，這些檔案會在產生的 deps 檔案中列舉。

請盡可能避免在平台程式碼中使用這項功能。詳情請參閱來源產生器。

crate_name

crate_name 會透過 rustc --crate_name 標記設定 Crate 名稱中繼資料。對於產生程式庫的模組，此值必須與來源中使用的預期 Crate 名稱相符。舉例來說，如果模組 libfoo_bar 在來源中以 extern crate foo_bar 的形式參照，則此 必須為 crate_name: "foo_bar"。

此屬性適用於所有 rust_* 模組，但對於產生 Rust 程式庫 (例如 rust_library rust_ffi、rust_bindgen、rust_protobuf 和 rust_proc_macro) 的模組而言，這是必要的。這些模組會針對 crate_name 和輸出檔案名稱之間的關係，強制執行 rustc 需求。詳情請參閱「程式庫模組」一節。

Lint

根據預設，rustc linter 會針對所有模組類型執行 (來源產生器除外)。系統會定義並使用部分 Lint 集來驗證模組來源。此類 lint 集合的可能值如下：

  • default 預設的 lint 組合，視模組位置而定
  • android 適用於所有 Android 平台程式碼的嚴格 lint 設定
  • vendor 套用至供應商程式的鬆散 lint 組合
  • none 可用來略過所有 Lint 警告和錯誤

clippy_lints

根據預設，除了來源產生器之外，所有模組類型都會執行 clippy 檢查器。定義了幾組用於驗證模組來源的 Lint。以下是一些可能的值：

  • default 預設的 lint 組合，視模組位置而定
  • android 適用於所有 Android 平台程式碼的嚴格 lint 設定
  • vendor 套用至供應商程式的鬆散 lint 組合
  • none 可用來略過所有 Lint 警告和錯誤

刊物

edition 會定義用於編譯此程式碼的 Rust 版本。這與 C 和 C++ 的 std 版本相似。有效值為 2015、2018 和 2021 (預設值)。

flag

flags 包含旗標的字串清單，可在編譯期間傳遞至 rustc。

ld_flags

ld-flags 包含字串清單，其中列出要傳遞至連結器的標記，以便在編譯來源時使用。這些會透過 -C linker-args rustc 標記傳遞。clang 用於連結器前端，可叫用 lld 進行實際連結。

功能

features 是功能的字串清單，必須在編譯期間啟用。這會由 --cfg 'feature="foo"' 傳遞至 rustc。大部分的功能都是加法，因此在許多情況下，這會包含所有依附模組所需的完整功能集。不過，如果功能互斥，請在提供相衝突功能的任何建構檔案中定義其他模組。

cfgs

cfgs 包含要於編譯期間啟用的 cfg 旗標字串清單。這會透過 --cfg foo 和 --cfg "fizz=buzz" 傳遞至 rustc。

建構系統會在特定情況下自動設定特定 cfg 標記，如下所列：

  • 以 dylib 建構的模組會設有 android_dylib cfg。

  • 使用 VNDK 的模組會設定 android_vndk cfg。這與 C++ 的 __ANDROID_VNDK__ 定義相似。

條紋

strip 可控制是否要去除輸出檔案 (如適用)，以及去除方式。如果未設定，裝置模組預設會移除所有內容，除了 mini debuginfo。根據預設，主機模組不會移除任何符號。有效值包括 none (停用去除) 和 all (去除所有內容，包括 mini debuginfo)。如需其他值，請參閱 Soong 模組參考資料。

host_supported

針對裝置模組，host_supported 參數會指出模組是否也應提供主機變數。

定義程式庫依附元件

Rust 模組可以透過下列屬性依附 CC 和 Rust 程式庫：

資源名稱 說明
rustlibs 列出同時也是依附元件的 rust_library 模組。請將此方法設為宣告依附元件的偏好方法，因為這可讓建構系統選取偏好的連結。(請參閱下方的「連結 Rust 程式庫」一節)
rlibs 必須以 rlibs 的形式進行靜態連結的 rust_library 模組清單。(請謹慎使用；請參閱下方的連結 Rust 程式庫時)。
shared_libs 必須以動態連結方式連結為共用程式庫的 cc_library 模組清單。
static_libs 必須以靜態資料庫的形式進行靜態連結的 cc_library 模組清單。
whole_static_libs 應以靜態方式連結為靜態資料庫，並在產生的資料庫中完整納入的 cc_library 模組清單。對於 rust_ffi_static 變體，whole_static_libraries 會納入產生的靜態資料庫封存檔中。對於 rust_library_rlib 變化版本，whole_static_libraries 程式庫會併入產生的 rlib 程式庫中。

連結至 Rust 程式庫時，建議您使用 rustlibs 屬性，而非 rlibs 或 dylibs，除非您有特定原因。這樣一來，建構系統就能根據根模組需求選取正確的連結，並降低依附元件樹狀結構同時包含 rlib 和 dylib 版本程式庫的機率 (這會導致編譯失敗)。

不支援及僅部分支援的建構功能

Soong 的 Rust 僅支援 vendor 和 vendor_ramdisk 映像檔和快照。不過，系統支援 staticlibs、cdylibs、rlibs 和 binaries。針對供應商映像檔建構目標，會設定 android_vndk cfg 屬性。如果系統和供應商目標之間存在差異，您可以在程式碼中使用此值。rust_proc_macros 不會擷取為供應商快照的一部分；如果需要依附這些檔案，請務必妥善控管版本。

不支援產品、VNDK 和復原映像檔。

漸進式建構

開發人員可以將 SOONG_RUSTC_INCREMENTAL 環境變數設為 true，啟用 Rust 來源的遞增編譯功能。

警告：這無法保證產生的二進位檔與 buildbot 產生的二進位檔相同。包含在物件檔案中的函式或資料的位址可能會有所不同。為確保產生的構件與 EngProd 基礎架構建構的構件 100% 相同，請保持這個值未設定。