Ogólnie rzecz biorąc, definicje modułów rust_* są ściśle zgodne z użytkowaniem i oczekiwaniami cc_* . Poniżej znajduje się przykład definicji modułu dla pliku binarnego Rust :
rust_binary {
name: "hello_rust",
crate_name: "hello_rust",
srcs: ["src/hello_rust.rs"],
host_supported: true,
}
Na tej stronie omówiono najczęstsze właściwości modułów rust_* . Aby uzyskać więcej informacji na temat określonych typów modułów i przykładowych definicji modułów, zobacz Moduły binarne , Moduły biblioteczne lub Moduły testowe .
Podstawowe typy modułów
| Typ | Definicja | Po więcej informacji |
|---|---|---|
rust_binary | Plik binarny Rusta | Strona modułów binarnych |
rust_library | Tworzy bibliotekę Rust i udostępnia warianty rlib i dylib . | rust_library , strona Moduły biblioteczne. |
rust_ffi | Tworzy bibliotekę Rust C, z której mogą korzystać moduły cc, i zapewnia zarówno statyczne, jak i współdzielone warianty. | rust_ffi , strona Moduły biblioteczne |
rust_proc_macro | Tworzy bibliotekę proc-macro Rust . (Są one analogiczne do wtyczek kompilatora.) | rust_proc_macro , strona Moduły bibliotek |
rust_test | Tworzy plik binarny testu rdzy , który wykorzystuje standardową uprząż testową rdzy . | Strona modułów testowych |
rust_fuzz | Tworzy binarny plik binarny Rust Fuzz wykorzystujący libfuzzer . | Przykład modułu rust_fuzz |
rust_protobuf | Generuje źródło i tworzy bibliotekę Rust , która zapewnia interfejs dla określonego protobufa. | Strony modułów Protobufs i generatorów źródeł |
rust_bindgen | Generuje źródło i tworzy bibliotekę Rust zawierającą powiązania Rusta z bibliotekami C. | Strony modułów Bindgen Bindings i generatorów źródeł |
Ważne wspólne właściwości
Te właściwości są wspólne dla wszystkich modułów Androida Rust . Wszelkie dodatkowe (unikalne) właściwości powiązane z poszczególnymi modułami Rust są wymienione na stronie tego modułu.
nazwa
name to nazwa twojego modułu. Podobnie jak inne moduły Soong, musi to być unikalne dla większości typów modułów Android.bp . Domyślnie jako nazwa pliku wyjściowego używana jest name . Jeśli nazwa pliku wyjściowego musi różnić się od nazwy modułu, użyj właściwości stem , aby ją zdefiniować.
trzon
stem (opcjonalny) zapewnia bezpośrednią kontrolę nad nazwą pliku wyjściowego (z wyłączeniem rozszerzenia pliku i innych przyrostków). Na przykład biblioteka rust_library_rlib z wartością rdzenia libfoo tworzy plik libfoo.rlib . Jeśli nie podasz wartości właściwości stem , nazwa pliku wyjściowego domyślnie przyjmie nazwę modułu.
Użyj funkcji stem , jeśli nie możesz ustawić nazwy modułu na żądaną nazwę pliku wyjściowego. Na przykład rust_library skrzynki z log nosi nazwę liblog_rust , ponieważ liblog cc_library już istnieje. Użycie właściwości stem w tym przypadku gwarantuje, że plik wyjściowy będzie miał nazwę liblog.* zamiast liblog_rust.* .
źródła
srcs zawiera pojedynczy plik źródłowy, który reprezentuje punkt wejścia do modułu (zwykle main.rs lub lib.rs ). rustc zajmuje się rozpoznawaniem i wykrywaniem wszystkich innych plików źródłowych wymaganych do kompilacji, które są wyliczane w generowanym pliku deps .
Jeśli to możliwe, unikaj tego użycia kodu platformy; zobacz Generatory źródeł, aby uzyskać więcej informacji.
nazwa_skrzynki
crate_name ustawia metadane nazwy skrzynki za pomocą flagi rustc --crate_name . W przypadku modułów tworzących biblioteki musi to być zgodne z oczekiwaną nazwą skrzynki użytą w źródle. Na przykład, jeśli moduł libfoo_bar jest wymieniony w źródle jako extern crate foo_bar , to musi to być nazwa_skrzynki: "foo_bar".
Ta właściwość jest wspólna dla wszystkich modułów rust_* , ale jest wymagana w przypadku modułów tworzących biblioteki Rusta (takie jak rust_library rust_ffi , rust_bindgen , rust_protobuf i rust_proc_macro ). Moduły te wymuszają wymagania rustc dotyczące relacji pomiędzy crate_name a nazwą pliku wyjściowego. Więcej informacji można znaleźć w sekcji Moduły biblioteczne .
kłaczki
Linter rustc jest domyślnie uruchamiany dla wszystkich typów modułów z wyjątkiem generatorów źródłowych. Niektóre zestawy lint są zdefiniowane i używane do sprawdzania źródła modułu. Możliwe wartości takich zestawów lint są następujące:
-
defaultdomyślny zestaw lintów, w zależności od lokalizacji modułu -
androidnajsurowszy zestaw lint, który ma zastosowanie do całego kodu platformy Android -
vendorswobodny zestaw lintów zastosowanych do kodu dostawcy -
none, aby zignorować wszystkie ostrzeżenia i błędy
klippy_lints
Clippy linter jest również domyślnie uruchamiany dla wszystkich typów modułów z wyjątkiem generatorów źródłowych. Zdefiniowano kilka zestawów lint, które służą do sprawdzania poprawności źródła modułu. Oto kilka możliwych wartości:
-
defaultdomyślny zestaw lint w zależności od lokalizacji modułu -
androidnajsurowszy zestaw lint, który ma zastosowanie do całego kodu platformy Android -
vendorswobodny zestaw lintów zastosowanych do kodu dostawcy -
none, aby zignorować wszystkie ostrzeżenia i błędy
wydanie
edition definiuje edycję Rusta , która będzie używana do kompilacji tego kodu. Jest to podobne do standardowych wersji dla C i C++. Prawidłowe wartości to 2015 i 2018 (domyślnie).
flagi
flags zawiera ciąg znaków flag, które mają zostać przekazane do rustc podczas kompilacji.
ld_flagi
ld-flags zawiera ciąg znaków flag, które należy przekazać do linkera podczas kompilacji źródła. Są one przekazywane przez flagę rustc -C linker-args . clang jest używany jako interfejs linkera, wywołując lld w celu faktycznego połączenia.
cechy
features to lista ciągów funkcji, które muszą być włączone podczas kompilacji. Jest to przekazywane do rustc przez --cfg 'feature="foo"' . Większość funkcji ma charakter addytywny, więc w wielu przypadkach składa się to z pełnego zestawu funkcji wymaganych przez wszystkie zależne moduły. Jednakże w przypadkach, gdy funkcje wykluczają się nawzajem, zdefiniuj dodatkowe moduły w dowolnych plikach kompilacji, które zapewniają sprzeczne funkcje.
cfgs
cfgs zawiera listę ciągów flag cfg , które mają być włączone podczas kompilacji. Jest to przekazywane do rustc przez --cfg foo i --cfg "fizz=buzz" .
System kompilacji automatycznie ustawia określone flagi cfg w określonych sytuacjach, wymienionych poniżej:
Moduły zbudowane jako dylib będą miały ustawioną wartość
android_dylibcfg.Moduły korzystające z VNDK będą miały ustawioną wartość
android_vndkcfg. Jest to podobne do definicji__ANDROID_VNDK__dla C++.
rozebrać się
strip kontroluje, czy i w jaki sposób plik wyjściowy jest usuwany (jeśli ma to zastosowanie). Jeśli ta opcja nie jest ustawiona, moduły urządzeń domyślnie usuwają wszystko oprócz minidebuginfo. Moduły hosta domyślnie nie usuwają żadnych symboli. Prawidłowe wartości to none , aby wyłączyć usuwanie, i all , aby usunąć wszystko, łącznie z mini informacjami debugowania. Dodatkowe wartości można znaleźć w dokumentacji modułów Soong .
obsługiwany przez hosta
W przypadku modułów urządzeń parametr host_supported wskazuje, czy moduł powinien również udostępniać wariant hosta.
Zdefiniuj zależności bibliotek
Moduły Rust mogą zależeć zarówno od bibliotek CC, jak i Rust poprzez następujące właściwości:
| Nazwa właściwości | Opis |
|---|---|
rustlibs | Lista modułów rust_library , które są również zależnościami. Użyj tej metody jako preferowanej metody deklarowania zależności, ponieważ pozwala systemowi kompilacji wybrać preferowane powiązanie. (Zobacz Linkowanie do bibliotek Rusta poniżej) |
rlibs | Lista modułów rust_library , które muszą być statycznie połączone jako rlibs . (Używaj ostrożnie; zobacz Łączenie z bibliotekami Rusta poniżej.) |
shared_libs | Lista modułów cc_library , które muszą być dynamicznie połączone jako biblioteki współdzielone. |
static_libs | Lista modułów cc_library , które muszą być statycznie połączone jako biblioteki statyczne. |
whole_static_libs | Lista modułów cc_library , które powinny być statycznie połączone jako biblioteki statyczne i zawarte w całości w wynikowej bibliotece. W przypadku wariantów rust_ffi_static whole_static_libraries zostaną uwzględnione w wynikowym archiwum biblioteki statycznej. W przypadku wariantów rust_library_rlib biblioteki whole_static_libraries zostaną dołączone do wynikowej biblioteki rlib . |
Łącząc się z bibliotekami Rusta , jako najlepszą praktykę rób to przy użyciu właściwości rustlibs zamiast rlibs lub dylibs , chyba że masz ku temu konkretny powód. Umożliwia to systemowi kompilacji wybranie prawidłowego powiązania w oparciu o wymagania modułu głównego i zmniejsza ryzyko, że drzewo zależności będzie zawierać zarówno wersję biblioteki rlib , jak i dylib (co spowoduje niepowodzenie kompilacji).
Nieobsługiwane i ograniczone funkcje kompilacji wsparcia
Soong's Rust oferuje ograniczoną obsługę obrazów i migawek vendor i vendor_ramdisk . Obsługiwane są jednak staticlibs , cdylibs , rlibs i binaries . W przypadku obiektów docelowych kompilacji obrazu dostawcy ustawiona jest właściwość android_vndk cfg . Można tego użyć w kodzie, jeśli istnieją różnice między elementami docelowymi systemu i dostawcy. rust_proc_macros nie są przechwytywane jako część migawek dostawców; jeśli są one zależne, upewnij się, że odpowiednio kontrolujesz ich wersje.
Obrazy produktów, VNDK i odzyskiwania nie są obsługiwane.
Kompilacje przyrostowe
Programiści mogą włączyć przyrostową kompilację źródła Rusta , ustawiając zmienną środowiskową SOONG_RUSTC_INCREMENTAL na true .
Ostrzeżenie : nie gwarantuje się utworzenia plików binarnych identycznych z plikami generowanymi przez roboty budowlane. Adresy funkcji lub danych zawartych w plikach obiektowych mogą być różne. Aby mieć pewność, że wygenerowane artefakty będą w 100% identyczne z artefaktami zbudowanymi przez infrastrukturę EngProd, pozostaw tę wartość nieustawioną.