Moduły Rust na Androida

Zasadniczo definicje modułów rust_* są ściśle zgodne z zasadami cc_* – wykorzystanie i oczekiwania. Oto przykład definicji modułu dla binarnego pliku Rust:

rust_binary {
    name: "hello_rust",
    crate_name: "hello_rust",
    srcs: ["src/hello_rust.rs"],
    host_supported: true,
}

Na tej stronie przedstawiamy najczęstsze właściwości modułów rust_*. Dla: więcej informacji o typach konkretnych modułów i ich definicjach, zobacz moduły binarne, Moduły biblioteczne, lub Moduły testowe.

Podstawowe typy modułów

TypDefinicjaWięcej informacji
rust_binaryPlik binarny Rust Moduły binarne strona
rust_libraryTworzy bibliotekę Rust i udostępnia zarówno rlib, jak i dylib wariantów. rust_library, strona Moduły w bibliotece.
rust_ffiTworzy bibliotekę C Rust, której można używać w modułach cc. Zapewnia ona warianty statyczne i współdzielone. rust_ffi, strona Komponenty w bibliotece
rust_proc_macroTworzy bibliotekę proc-macro w języku Rust. (Działają one analogicznie do wtyczek kompilatora). rust_proc_macro, strona Biblioteki Modułów
rust_testTworzy testowy binarny plik Rust, który korzysta ze standardowego zestawu testów Rust. Strona Testowanie modułów
rust_fuzzTworzy binarny plik fuzzingu Rust, korzystając z libfuzzer. rust_fuzz – przykład modułu
rust_protobufGeneruje kod źródłowy i tworzy bibliotekę Rust, która zapewnia interfejs dla konkretnego protobufa. strony Protobufs Modules i Source Generators.
rust_bindgenGeneruje źródło i generuje Biblioteka Rust zawierająca powiązania Rust z bibliotekami C. strony Moduły bindgen i Generatory źródeł.

Ważne właściwości wspólne

Te właściwości są wspólne dla wszystkich modułów Rust na Androida. Dodatkowe (unikalne) właściwości powiązane z poszczególnymi modułami Rust są wymienione na stronie danego modułu.

nazwa

name to nazwa modułu. Podobnie jak inne moduły Soong, element ten musi być niepowtarzalny w większości typów modułów Android.bp. Domyślnie jako nazwa pliku wyjściowego jest używana wartość name. Jeśli nazwa pliku wyjściowego musi być inna niż nazwa modułu, użyj właściwości stem, aby ją zdefiniować.

łodyga

stem (opcjonalnie) umożliwia bezpośrednią kontrolę nazwy pliku wyjściowego (z wyjątkiem rozszerzenia pliku i innych sufiksów). Przykład: rust_library_rlib biblioteka z wartością rdzenia libfoo tworzy plik libfoo.rlib. Jeśli nie podasz wartości dla właściwości stem, nazwa pliku wyjściowego przyjmie atrybut nazwę modułu.

Użyj funkcji stem, gdy nie możesz ustawić nazwy modułu jako żądanej nazwy pliku wyjściowego. Na przykład nazwa rust_library w skrzynce log ma nazwę liblog_rust, ponieważ liblog cc_library już istnieje. Użycie w tym przypadku właściwości stem sprawi, że dane wyjściowe ma nazwę liblog.*, a nie liblog_rust.*.

Źródła

srcs zawiera pojedynczy plik źródłowy, który reprezentuje punkt wejścia pliku moduł (zwykle main.rs lub lib.rs). rustc obsługuje rozdzielczość i wykrywania wszystkich innych plików źródłowych wymaganych do kompilacji. Są to można określić w generowanym pliku deps.

W miarę możliwości unikaj używania tego kodu w kodzie platformy. Więcej informacji znajdziesz w artykule Generatory kodu.

nazwa_skrzynki

crate_name ustawia metadane nazwy skrzynki za pomocą flagi rustc --crate_name. W przypadku modułów, które generują biblioteki, ta wartość musi odpowiadać oczekiwanej nazwie kontenera użytej w źródle. Jeśli na przykład odwołanie do modułu libfoo_bar w źródle jako extern crate foo_bar, to musi być crate_name: "foo_bar".

Ta właściwość jest wspólna dla wszystkich modułów rust_*, ale jest wymagana w przypadku modułów. które tworzą biblioteki Rust (np. rust_library) rust_ffi, rust_bindgen, rust_protobuf i rust_proc_macro). Te moduły egzekwują wymagania rustc dotyczące relacji między crate_name oraz nazwę pliku wyjściowego. Więcej informacji znajdziesz w sekcji Moduły biblioteki.

lints

rustc linter, jest uruchamiany domyślnie dla wszystkich typów modułów z wyjątkiem generatorów źródeł. Niektóre zestawy lint są definiowane i używane do sprawdzania źródła modułu. Możliwe wartości takich zestawów reguł lint:

  • default domyślny zestaw narzędzi lint, zależnie od lokalizacji modułu;
  • android – najbardziej rygorystyczny zestaw lint, który dotyczy całego kodu platformy Androida
  • vendor – zestaw prostych lintów zastosowanych do kodu dostawcy
  • none, aby zignorować wszystkie ostrzeżenia i błędy lint

clippy_lints

Linter klipów jest również jest uruchamiany domyślnie dla wszystkich typów modułów z wyjątkiem generatorów źródeł. Zdefiniowano kilka zestawów narzędzi lint służących do sprawdzania źródła modułu. Oto kilka możliwych wartości:

  • default domyślny zestaw narzędzi lint w zależności od lokalizacji modułu
  • android – najbardziej rygorystyczny zestaw lint, który dotyczy całego kodu platformy Androida
  • vendor – zestaw prostych lintów zastosowanych do kodu dostawcy
  • none, aby ignorować wszystkie ostrzeżenia i błędy dotyczące lintowania
.

wydanie

edition określa wersję Rust, która będzie używana w przypadku na kompilację kodu. Jest to podobne do wersji standardowych w C i C++. Dopuszczalne wartości to 2015 i 2018 (domyślna).

flagi

flags zawiera listę flag, które należy przekazać do rustc podczas kompilacji.

flagi_ld

ld-flags zawiera listę flag, które mają być przekazywane do tagu łączącego podczas kompilacji źródła. Są one przekazywane przez flagę rustc -C linker-args. clang jest używany jako front-end tagu łączącego, wywołując lld do faktycznego łączenia.

Funkcje

features to ciąg znaków listy funkcji, które muszą być włączone podczas kompilacji. Treść jest przekazywana do rustc przez --cfg 'feature="foo"'. Większość funkcji się sumuje, dlatego w wielu przypadkach składa się on z zestawu funkcji wymaganych przez wszystkie modułów. Jeśli jednak funkcje wzajemnie się wykluczają, zdefiniować dodatkowe moduły w plikach kompilacji, które zawierają funkcje powodujące konflikty.

cfgs

cfgs zawiera listę ciągów znaków z flagami cfg, które mają być włączone podczas kompilacji. rustc otrzymuje te dane od --cfg foo i --cfg "fizz=buzz".

System kompilacji automatycznie ustawia określone flagi cfg omówionych poniżej sytuacji:

  • Moduły utworzone jako dylib będą miały ustawioną wartość cfg android_dylib.

  • Moduły, które używają VNDK, będą miały ustawioną wartość cfg android_vndk. Jest to podobne do definicji funkcji __ANDROID_VNDK__ w języku C++.

rozbieranie się

Opcja strip określa, czy i w jaki sposób plik wyjściowy ma być pozbawiony danych (jeśli to konieczne). Jeśli zasada jest nieskonfigurowana, moduły urządzenia domyślnie usuwają wszystko oprócz minidebugowania. Moduły hosta domyślnie nie usuwają żadnych symboli. Prawidłowe wartości to none , aby wyłączyć usuwanie, a także all, aby usunąć wszystko, łącznie z mini debuginfo. Dodatkowe wartości można znaleźć w przewodniku po modułach Song.

host_supported

W przypadku modułów urządzenia parametr host_supported wskazuje, powinien podawać także wariant hosta.

Definiowanie zależności biblioteki

Moduły Rust mogą zależeć zarówno od bibliotek CC, jak i Rust za pomocą tych właściwości:

Nazwa usługi Opis
rustlibs Lista modułów rust_library, które są również zależnościami. Użyj tej metody do deklarowania zależności, ponieważ pozwala ona systemowi kompilacji wybrać preferowane powiązanie. (patrz poniżej sekcja o linkowaniu do bibliotek Rust)
rlibs Lista rust_library modułów, które muszą być statyczne jako rlibs. (Zachowaj ostrożność; zobacz W przypadku łączenia z bibliotekami Rust (poniżej).
shared_libs Lista modułów cc_library, które muszą być dynamicznie połączone jako biblioteki udostępnione.
static_libs Lista cc_library modułów, które muszą być statycznie połączone jako biblioteki statyczne.
whole_static_libs Lista modułów cc_library, które powinny być połączone statycznie jako biblioteki statyczne i włączone w całości do biblioteki wynikowej. W przypadku wariantów rust_ffi_static w archiwum biblioteki statycznej uwzględnione zostaną warianty whole_static_libraries. W przypadku rust_library_rlib wariantu, whole_static_libraries biblioteki zostanie zawarte w pakiecie do wynikowego rlib bibliotece.

Podczas tworzenia linków do bibliotek Rust zalecamy używanie właściwości rustlibs zamiast rlibs lub dylibs, chyba że masz konkretny powód, aby tego nie robić. Pozwala to systemowi kompilacji wybrać prawidłowe połączenie na podstawie wymagań modułu głównego i zmniejsza prawdopodobieństwo, że drzewo zależności będzie zawierać wersje rlib i dylib biblioteki (co spowoduje niepowodzenie kompilacji).

Nieobsługiwane i ograniczone funkcje kompilacji

Soong Rust zapewnia ograniczone wsparcie dla obrazów i zrzutów ekranu vendor i vendor_ramdisk. Obsługiwane są jednak staticlibs, cdylibs, rlibs i binaries. W przypadku celów kompilacji obrazu dostawcy parametr Właściwość android_vndk cfg jest ustawiona. Możesz użyć tego w kodzie, jeśli występują różnice między wartościami docelowymi systemu a dostawcy. rust_proc_macros nie rejestrowane jako część zrzutów od dostawców; upewnij się, czy są one zależne od tego, odpowiednio kontrolować ich wersję.

Obrazy produktu, VNDK i odzyskiwania nie są obsługiwane.

Kompilacje przyrostowe

Deweloperzy mogą włączyć przyrostową kompilację funkcji Źródło Rust przez ustawienie parametru SOONG_RUSTC_INCREMENTAL zmienną środowiskową na true.

Ostrzeżenie: nie ma gwarancji, że pliki binarne będą identyczne z tymi wygenerowanymi przez buildboty. Adresy funkcji lub danych zawartych w mogą być inne. Aby mieć pewność, że wygenerowane artefakty są w 100% taka sama jak infrastruktura EngProd, pozostaw tę wartość nieustawioną.