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, 程式庫模組頁面
rust_proc_macro產生 proc-macro Rust 程式庫。 (這些類似於編譯器外掛程式)。 rust_proc_macro, 程式庫模組頁面
rust_test產生使用 Rust 測試二進位檔 標準 Rust 測試控管工具。 「測試模組」頁面
rust_fuzz利用 libfuzzer 產生 Rust 模糊測試二進位檔。 rust_fuzz 模組範例
rust_protobuf產生來源並產生 Rust 程式庫，為特定 protobuf 提供介面。 Protobufs 模組和來源產生器頁面
rust_bindgen產生來源並產生 Rust 程式庫，內含 Rust 繫結至 C 程式庫。 Bindgen 繫結模組和來源產生器頁面

重要常用屬性

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

name

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

Stem

stem (選用) 可直接控管輸出檔案名稱 (不含檔案副檔名和其他後置字串)。例如 rust_library_rlib stem 值為 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++ 的 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 集。這是 與 __ANDROID_VNDK__ 類似 C++ 的定義

條

strip 會控制是否要移除輸出檔案，以及如何移除檔案 (如適用)。 如果不設定這項政策，裝置模組預設會移除除了迷你偵錯資訊以外的所有項目。 主機模組預設不會移除任何符號。有效值包括 none 停用去除功能，all 則去除所有資訊，包括小型偵錯資訊。 其他值請參閱 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 設為 Rust 來源 將環境變數設為 true

警告：這無法保證產生的二進位檔與 buildbot 產生的二進位檔相同。其中包含的函式或資料位址， 不一定相同確保產生的構件 100% 和 EngProd 基礎架構建構的應用程式一樣，不設定這個值。