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 二進位檔 二進位模組 頁面
rust_library產生 Rust 程式庫，並提供 rlib 和 dylib 變種版本。 rust_library「程式庫模組」頁面。
rust_ffi產生可供 cc 模組使用的 Rust C 程式庫，並提供靜態和共用變體。 rust_ffi, 程式庫模組頁面
rust_proc_macro產生 proc-macro Rust 程式庫。 (這類似於編譯器外掛程式)。 rust_proc_macro, 程式庫模組頁面
rust_test產生使用標準 Rust 測試架構的 Rust 測試二進位檔。 「測試模組」頁面
rust_fuzz產生利用 libfuzzer 的 Rust 模糊測試二進位檔。 rust_fuzz 模組範例
rust_protobuf產生來源並製作 Rust 程式庫，為特定 protobuf 提供介面。 「Protobufs Modules」和「Source Generators」頁面
rust_bindgen產生來源並建立 Rust 程式庫，其中包含 C 程式庫的 Rust 繫結。 Bindgen 繫結模組 和來源產生器頁面

重要的常見屬性

這些屬性在所有 Android Rust 模組中都很常見。與個別 Rust 模組相關聯的任何其他 (專屬) 屬性，都會列在該模組的頁面上。

name

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

詞幹

stem (選用) 可直接控管輸出檔案名稱 (不含副檔名和其他後置字串)。舉例來說，如果 rust_library_rlib 程式庫的詞幹值為 libfoo，就會產生 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 linter。系統會定義幾組 Lint，用於驗證模組來源。可能的值包括：

  • default 預設的 Lint 規則集，視模組位置而定
  • android 適用於所有 Android 平台程式碼的最嚴格 Lint 集合
  • vendor 針對供應商程式碼套用寬鬆的 Lint 規則
  • none 即可忽略所有 Lint 警告和錯誤

刊物

edition 定義用於編譯這段程式碼的 Rust 版本。這與 C 和 C++ 的標準版本類似。有效值為 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

strip 可控制是否要剝除輸出檔案 (如適用) 及剝除方式。 如果未設定，裝置模組預設會移除所有內容，迷你偵錯資訊除外。 主機模組預設不會移除任何符號。有效值包括停用剝除功能的 none，以及剝除所有內容 (包括迷你偵錯資訊) 的 all。如需其他值，請參閱 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 來源的遞增編譯。

警告：無法保證產生的二進位檔與建構機器人產生的二進位檔完全相同。物件檔案中包含的函式或資料位址可能不同。如要確保產生的構件與 EngProd 基礎架構建構的構件 100% 相同，請將這個值設為未設定。