Rust 程式庫模組有兩種,一種會產生 Rust 程式庫,另一種則會產生與 C 相容的程式庫。此外,就建構系統而言,您可以將 Rust 程序巨集 (proc-macros
) 視為特殊類型的程式庫。
rust_library
rust_library
模組會產生 Rust 程式庫,供其他 Rust 模組使用。
除了 _host
變體外,Rust 程式庫也有模組型別,可控制可用的連結。
Rust 程式庫模組類型 | 定義 |
---|---|
rust_library | 提供 rlib 和 dylib 兩種程式庫變體。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 編譯器對程式庫檔案名稱設有特定規定,因此建構系統會強制執行這些規定,避免發生編譯問題。輸出檔案名稱的格式必須為「 |
crate_name | 這是產生程式庫的模組的必要屬性,此外,它也與輸出檔案名稱有關。(請參閱 stem 定義)。 |
export_include_dirs | 如果是 rust_ffi 模組,這項屬性會定義代表相對 include 路徑的字串清單:包含依附 cc 模組可使用的標頭的路徑。 |
rust_library 或 rust_ffi 的連結
根據預設,以裝置為目標的 Rust 程式庫模組一律會動態連結至 libstd
。不過,主機模組一律會針對 libstd
靜態連結。
用於 rustlibs
依附元件的連結取決於根模組的連結偏好設定。(舉例來說,含有 prefer_rlib: true
的 rust_binary
會使用連結 rustlibs
做為 rlibs
的 Rust 程式庫變體。)
如要允許產生不依附任何動態 Rust 程式庫 (例如靜態可執行檔) 的根依附元件模組,rlibs
會提供動態和靜態 libstd
連結變數。Soong 會自動連結正確的變體。