Istnieją 2 typy modułów biblioteki Rust: jeden tworzy biblioteki Rust, a drugi – biblioteki zgodne z C. Dodatkowo na potrzeby systemu kompilacji możesz traktować makra proceduralne Rust (proc-macros) jako specjalny rodzaj biblioteki.
rust_library
Moduł rust_library tworzy biblioteki Rust do użytku przez inne moduły Rust.
Oprócz wariantów _host biblioteki Rust mają typy modułów, które kontrolują dostępne połączenia.
| Typ modułu biblioteki Rust | Definicja |
|---|---|
| rust_library | Zawiera obie wersje biblioteki: rlib i dylib. AOSP zaleca ten typ modułu w przypadku bibliotek Rust, ponieważ umożliwia on prawidłowe działanie modułów, gdy są one wymienione jako zależność we właściwości rustlibs. |
| rust_library_rlib | Zawiera tylko wariant rlib biblioteki Rust. Nie można zagwarantować, że moduły zawierające tylko warianty rlib będą działać z właściwością rustlibs. |
| rust_library_dylib | Zawiera tylko wariant dylib biblioteki Rust. Nie można zagwarantować, że moduły udostępniające tylko warianty dylib będą działać z właściwością rustlibs. |
rust_ffi
Moduł rust_ffi generuje biblioteki zgodne z językiem C, które umożliwiają współpracę z modułami CC.
Oprócz wariantów _host biblioteki Rust FFI mają typy modułów, które kontrolują dostępne połączenia. Pokazujemy je w tabeli poniżej.
| Typ modułu biblioteki Rust FFI | Definicja |
|---|---|
| rust_ffi | Udostępnia obie wersje biblioteki C: statyczną i współdzieloną. |
| rust_ffi_shared | Zawiera tylko wariant biblioteki współużytkowanej C. |
| rust_ffi_static | Zawiera tylko wariant statycznej biblioteki C. |
Podstawowy przykład użycia rust_ffi do wywoływania kodu Rust z C znajdziesz na stronie Android Rust Patterns.
Więcej informacji o zaawansowanym korzystaniu z tego języka znajdziesz w oficjalnej dokumentacji języka Rust.
rust_proc_macro
Makra proceduralne w języku Rust (proc-macros) mogą być przydatne do rozszerzania kompilatora w celu przeprowadzania transformacji kodu źródłowego lub udostępniania nowych atrybutów. Więcej informacji o nich znajdziesz na stronie Procedural Macros w oficjalnej dokumentacji języka Rust.
W systemie kompilacji moduł rust_proc_macro działa podobnie jak moduły rust_library. W przypadku modułów, które zależą od rust_proc_macros, dodaj nazwę modułu do właściwości proc_macros.
Ponieważ proc_macros są wtyczkami kompilatora, są one przeznaczone dla hosta i nie generują kodu, który można by uruchomić na urządzeniu.
Ważne właściwości biblioteki Rust
Właściwości zdefiniowane w tabeli poniżej są dodatkiem do ważnych właściwości wspólnych, które mają zastosowanie do wszystkich modułów. Są one szczególnie ważne w przypadku modułów biblioteki Rust lub wykazują unikalne zachowanie charakterystyczne dla typu modułu rust_library.
| Właściwości biblioteki Rust | Definicja |
|---|---|
| stem / name | Właściwość stem określa nazwę pliku biblioteki wyjściowej, która domyślnie ma wartość name.
Kompilator Rust nakłada pewne wymagania na nazwy plików bibliotek, dlatego system kompilacji wymusza te wymagania, aby uniknąć problemów z kompilacją.
Nazwa pliku wyjściowego musi być zgodna z formatem |
| crate_name | Jest to wymagana właściwość modułów generujących biblioteki. Jest ona też powiązana z nazwą pliku wyjściowego. (Zobacz definicję stem). |
| export_include_dirs | W przypadku modułów rust_ffi ta właściwość definiuje listę ciągów znaków reprezentujących względne ścieżki dołączania: ścieżki zawierające nagłówki, których mogą używać zależne moduły cc. |
Łączenie rust_library lub rust_ffi
Domyślnie moduły biblioteki Rust przeznaczone na urządzenia są zawsze łączone dynamicznie z libstd. Moduły hosta są jednak zawsze połączone statycznie z libstd.
Powiązanie używane w przypadku zależności rustlibs zależy od preferencji dotyczących powiązań modułu głównego. (Na przykład rust_binary z prefer_rlib: true będzie używać wariantów biblioteki Rust, które łączą rustlibs jako rlibs).
Aby umożliwić tworzenie modułów zależności głównej, które nie korzystają z żadnych dynamicznych bibliotek Rusta (np. statycznych plików wykonywalnych), rlibs udostępnia zarówno dynamiczne, jak i statyczne warianty libstd łączenia. Prawidłowy wariant jest automatycznie łączony przez Soong.