Android Rust 模塊

作為一般原則， rust_*模塊定義嚴格遵守cc_*的使用和期望。以下是 Rust 二進製文件的模塊定義示例：

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

本頁介紹了rust_*模塊最常見的屬性。有關特定模塊類型和示例模塊定義的更多信息，請參閱二進制模塊、庫模塊或測試模塊頁面。

基本模塊類型

類型定義想要查詢更多的信息
rust_binary Rust 二進製文件二進制模塊頁面
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生成源代碼並生成一個為特定 protobuf 提供接口的 Rust 庫。 Protobufs 模塊和源代碼生成器頁面
rust_bindgen生成源代碼並生成一個 Rust 庫，其中包含與 C 庫的 Rust 綁定。 Bindgen 綁定模塊和源生成器頁面

重要的共同屬性

這些屬性在所有 Android Rust 模塊中都很常見。與各個 Rust 模塊相關的任何其他（唯一）屬性都列在該模塊的頁面上。

名稱

name是您的模塊的名稱。與其他 Soong 模塊一樣，這在大多數Android.bp模塊類型中必須是唯一的。默認情況下， name用作輸出文件名。如果輸出文件名必須與模塊名不同，請使用stem屬性來定義它。

幹

stem （可選）提供對輸出文件名的直接控制（不包括文件擴展名和其他後綴）。例如，具有rust_library_rlib libfoo會生成一個libfoo.rlib文件。如果不為stem屬性提供值，則輸出文件名默認採用模塊名稱。

當您無法將模塊名稱設置為所需的輸出文件名時，請使用stem函數。例如， log箱的rust_library被命名為liblog_rust ，因為liblog cc_library已經存在。在這種情況下使用stem屬性可確保輸出文件名為liblog.*而不是liblog_rust.* 。

源文件

srcs包含一個代表模塊入口點的源文件（通常是main.rs或lib.rs ）。 rustc處理編譯所需的所有其他源文件的解析和發現，這些在生成的deps文件中枚舉。

如果可能，請避免在平台代碼中使用這種用法；有關更多信息，請參閱源生成器。

箱子名稱

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要求。有關詳細信息，請參閱庫模塊部分。

皮棉

rustc linter默認為除源生成器之外的所有模塊類型運行。定義了一些 lint 集並用於驗證模塊源。此類 lint 集的可能值如下：

  • default （默認的 lints 集，取決於模塊的位置）
  • 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 （默認值）。

旗幟

flags包含在編譯期間傳遞給rustc的標誌的字符串列表。

ld_flags

ld-flags包含在編譯源代碼時傳遞給鏈接器的標誌字符串列表。這些是由-C linker-args rustc 標誌傳遞的。 clang用作鏈接器前端，調用lld進行實際鏈接。

特徵

features是在編譯期間必須啟用的功能的字符串列表。這通過--cfg 'feature="foo"'傳遞給 rustc。大多數功能都是附加的，因此在許多情況下，這包括所有依賴模塊所需的完整功能集。但是，在功能相互排斥的情況下，請在任何提供衝突功能的構建文件中定義其他模塊。

配置文件

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參數指示模塊是否還應提供主機變體。

定義庫依賴項

Rust 模塊可以通過以下屬性同時依賴 CC 和 Rust 庫：

屬性名稱描述
rustlibs同樣是依賴項的rust_library模塊列表。將此作為您聲明依賴項的首選方法，因為它允許構建系統選擇首選鏈接。 （請參閱下面的鏈接 Rust 庫時）
rlibs必須靜態鏈接為rlibs的rust_library模塊列表。 （謹慎使用；請參閱下面的與 Rust 庫鏈接時。）
dylibs要動態鏈接為dylibs的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 源代碼的增量編譯。

警告：這不能保證生成與 buildbots 生成的二進製文件相同的二進製文件。目標文件中包含的函數或數據的地址可能不同。為確保生成的工件與 EngProd 基礎架構構建的工件 100% 相同，請不要設置此值。