程式庫模組

Rust 程式庫模組有兩種,一種會產生 Rust 程式庫,另一種則會產生與 C 相容的程式庫。此外,就建構系統而言,您可以將 Rust 程序巨集 (proc-macros) 視為特殊類型的程式庫。

rust_library

rust_library 模組會產生 Rust 程式庫,供其他 Rust 模組使用。

除了 _host 變體外,Rust 程式庫也有模組型別,可控制可用的連結。

Rust 程式庫模組類型 定義
rust_library 提供 rlibdylib 兩種程式庫變體。Android 開放原始碼計畫建議 Rust 程式庫使用這個模組類型,因為模組列為 rustlibs 屬性下的依附元件時,這樣才能正常運作
rust_library_rlib 僅提供 Rust 程式庫的 rlib 變數;僅提供 rlib 變數的模組無法保證能與 rustlibs 屬性搭配運作。
rust_library_dylib 僅提供 Rust 程式庫的 dylib 變數; 僅提供 dylib 變數的模組無法保證能與 rustlibs 屬性搭配運作。

rust_ffi

rust_ffi 模組會產生與 C 相容的程式庫,以便與 CC 模組互通。

除了 _host 變數外,Rust FFI 程式庫也有模組類型,可控制可用的連結,如下表所示。

Rust FFI 程式庫模組類型 定義
rust_ffi 提供靜態和共用兩種 C 程式庫變體。
rust_ffi_shared 僅提供 C 共用程式庫變數。
rust_ffi_static 僅提供 C 靜態程式庫變體。

如需使用 rust_ffi 從 C 呼叫 Rust 的基本範例,請參閱「Android Rust 模式」頁面。

如要瞭解更進階的用法,請參閱 Rust 官方說明文件

rust_proc_macro

Rust 程序巨集 (proc-macros) 可用於擴充編譯器,以執行原始碼轉換或提供新屬性。如要進一步瞭解這些項目,請參閱官方 Rust 說明文件的「程序巨集」頁面。

就建構系統而言,rust_proc_macro 模組的運作方式與 rust_library 模組類似。對於依附於 rust_proc_macros 的模組,請將模組名稱新增至 proc_macros 屬性。

由於 proc_macros 是編譯器外掛程式,因此必然會以主機為目標,且不會產生任何可在裝置上執行的程式碼。

Rust 程式庫的重要屬性

下表定義的屬性是適用於所有模組的重要通用屬性。這些屬性對 Rust 程式庫模組特別重要,或是展現 rust_library 模組類型特有的行為。

Rust 程式庫屬性 定義
詞幹 / 名稱 stem 屬性會控制輸出程式庫的檔案名稱,否則預設為 name

Rust 編譯器對程式庫檔案名稱設有特定規定,因此建構系統會強制執行這些規定,避免發生編譯問題。輸出檔案名稱的格式必須為「lib<crate_name><suffix>」。(這裡依附於 crate_name 屬性)。

crate_name 這是產生程式庫的模組的必要屬性,此外,它也與輸出檔案名稱有關。(請參閱 stem 定義)。
export_include_dirs 如果是 rust_ffi 模組,這項屬性會定義代表相對 include 路徑的字串清單:包含依附 cc 模組可使用的標頭的路徑。

rust_library 或 rust_ffi 的連結

根據預設,以裝置為目標的 Rust 程式庫模組一律會動態連結至 libstd。不過,主機模組一律會針對 libstd 靜態連結。

用於 rustlibs 依附元件的連結取決於根模組的連結偏好設定。(舉例來說,含有 prefer_rlib: truerust_binary 會使用連結 rustlibs 做為 rlibs 的 Rust 程式庫變體。)

如要允許產生不依附任何動態 Rust 程式庫 (例如靜態可執行檔) 的根依附元件模組,rlibs 會提供動態和靜態 libstd 連結變數。Soong 會自動連結正確的變體。