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，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 模組」和「來源產生器」頁面
rust_bindgen產生來源並產生包含 Rust 繫結至 C 程式庫的 Rust 程式庫。 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 linter。我們定義了幾組 Lint，用於驗證模組來源。以下是一些可能的值：

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

刊物

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

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 會控制是否要移除輸出檔案，以及如何移除檔案 (如適用)。如果不設定這項政策，裝置模組會預設移除除了迷你偵錯資訊以外的所有項目。 根據預設，主機模組不會移除任何符號。有效值包括 none (停用去除) 和 all (去除所有內容，包括 mini debuginfo)。如需其他值，請參閱 Soong 模組參考資料。

host_supported

若是裝置模組，host_supported 參數會指出模組是否也應提供主機變化版本。

定義程式庫依附元件

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

資源名稱 說明
rustlibs 也是依附元件的 rust_library 模組清單。請將此做為宣告依附元件的偏好方法，因為這可讓建構系統選取偏好的連結。(請參閱下方的「連結至 Rust 程式庫時」一節)。
rlibs rust_library 模組清單，必須以 rlibs 形式靜態連結。(請謹慎使用；請參閱下方的連結 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% 相同，請保留這個值。