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產生原始碼並產生一個Rust庫，為特定的 protobuf 提供介面。 Protobufs 模組和來源產生器頁面
rust_bindgen產生原始碼並產生一個Rust庫，其中包含與 C 庫的Rust綁定。 Bindgen 綁定模組和來源產生器頁面

重要的共同屬性

這些屬性在所有 Android Rust模組中都是通用的。與各個Rust模組關聯的任何其他（唯一）屬性都列在該模組的頁面上。

姓名

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

幹

stem （可選）提供對輸出檔案名稱的直接控制（不包括檔案副檔名和其他後綴）。例如，主幹值為libfoo的rust_library_rlib函式庫會產生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 名稱元資料。對於生成庫的模組，這必須與來源中使用的預期包名稱相符。例如，如果模組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的 lint 集，取決於模組的位置
  • android最嚴格的 lint 集，適用於所有 Android 平台程式碼
  • vendor一組應用於供應商代碼的寬鬆的 lints
  • none忽略所有 lint 警告和錯誤

Clippy_lints

預設情況下， clippy linter也會針對除來源產生器之外的所有模組類型執行。定義了幾組 lint，用於驗證模組來源。這些是一些可能的值：

  • default預設 lint 集取決於模組的位置
  • android最嚴格的 lint 集，適用於所有 Android 平台程式碼
  • vendor一組應用於供應商代碼的寬鬆的 lints
  • none忽略所有 lint 警告和錯誤

版

edition定義了用於編譯此程式碼的Rust版本。這類似於 C 和 C++ 的 std 版本。有效值為2015和2018 （預設）。

旗幟

flags包含在編譯期間傳遞給rustc的標誌字串清單。

ld_flags

ld-flags包含編譯原始碼時傳遞給連結器的標誌字串清單。這些由-C linker-args rustc 標誌傳遞。 clang用作連結器前端，呼叫lld進行實際連結。

特徵

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

cfg

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

建置系統會在特定情況下自動設定某些cfg標誌，如下所列：

  • 建置為 dylib 的模組將設定android_dylib cfg。

  • 使用 VNDK 的模組將設定android_vndk cfg。這類似於 C++ 的__ANDROID_VNDK__定義。

條

strip控制是否以及如何剝離輸出檔案（如果適用）。如果未設置，設備模組預設會刪除除微型調試資訊之外的所有內容。預設情況下，主機模組不會刪除任何符號。有效值包括none來停用剝離，以及all來剝離所有內容，包括迷你偵錯資訊。其他值可以在Soong Modules Reference中找到。

主機支援

對於裝置模組， 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% 相同，請保留該值未設定。