Android Rust-Module

rust_*-Moduldefinitionen entsprechen in der Regel genau der Verwendung und den Erwartungen von cc_*. Das folgende Beispiel zeigt eine Moduldefinition für ein Rust-Binary:

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

Auf dieser Seite werden die gängigsten Properties für rust_*-Module behandelt. Weitere Informationen zu bestimmten Modultypen und Beispielmoduldefinitionen finden Sie unter Binäre Module, Bibliotheksmodule und Testmodule.

Hinweis: Aktuelle, automatisch generierte Dokumentation für alle Modultypen und ‑eigenschaften finden Sie in der Soong-Modulreferenz.

Grundlegende Modultypen

Eingeben	Definition	Weitere Informationen
rust_binary	Ein Rust-Binärprogramm	Seite Binärmodule
rust_library	Erzeugt eine Rust-Bibliothek und bietet sowohl rlib- als auch dylib-Varianten.	rust_library, Seite „Bibliotheksmodule“.
rust_ffi	Erzeugt eine Rust-C-Bibliothek, die von cc-Modulen verwendet werden kann, und bietet sowohl statische als auch freigegebene Varianten.	rust_ffi, Seite „Bibliothek – Module“
rust_proc_macro	Erzeugt eine proc-macro Rust-Bibliothek. (Diese sind analog zu Compiler-Plug-ins.)	rust_proc_macro, Seite „Bibliotheksmodule“
rust_test	Erzeugt eine Rust-Testbinärdatei, die die standardmäßige Rust-Testanwendung verwendet.	Seite Module testen
rust_fuzz	Erzeugt eine Rust-Fuzz-Binärdatei, die libfuzzer nutzt.	Beispiel für das Modul rust_fuzz
rust_protobuf	Er generiert Quellcode und erstellt eine Rust-Bibliothek, die eine Schnittstelle für ein bestimmtes Protobuf bietet.	Seiten Protobuf-Module und Quellgeneratoren
rust_bindgen	Generiert Quellcode und erstellt eine Rust-Bibliothek mit Rust-Bindungen zu C-Bibliotheken.	Die Seiten Bindgen Bindings Modules und Source Generators

Wichtige gemeinsame Eigenschaften

Diese Attribute sind in allen Android Rost-Modulen gleich. Alle zusätzlichen (eindeutigen) Eigenschaften, die mit einzelnen Rust-Modulen verknüpft sind, werden auf der Seite des Moduls aufgeführt.

Name

name ist der Name Ihres Moduls. Wie bei anderen Soong-Modulen muss dieser Name für die meisten Android.bp-Modultypen eindeutig sein. Standardmäßig wird name als Name der Ausgabedatei verwendet. Wenn sich der Ausgabedateiname vom Modulnamen unterscheiden muss, verwenden Sie die Property stem, um ihn zu definieren.

Stiel

stem (optional) bietet direkte Kontrolle über den Ausgabedateinamen (mit Ausnahme der Dateiendung und anderer Suffixe). So erzeugt beispielsweise eine rust_library_rlib-Bibliothek mit dem Stammwert libfoo eine libfoo.rlib-Datei. Wenn Sie keinen Wert für die Property stem angeben, wird der Dateiname der Ausgabe standardmäßig aus dem Modulnamen übernommen.

Verwenden Sie die Funktion stem, wenn Sie den Modulnamen nicht auf den gewünschten Namen der Ausgabedatei festlegen können. Die rust_library für die Kiste log heißt beispielsweise liblog_rust, da liblog cc_library bereits vorhanden ist. Wenn Sie in diesem Fall die Property stem verwenden, wird die Ausgabedatei liblog.* statt liblog_rust.* genannt.

„srcs“

srcs enthält eine einzelne Quelldatei, die den Einstiegspunkt in Ihr Modul darstellt (normalerweise main.rs oder lib.rs). rustc übernimmt die Auflösung und Suche nach allen anderen Quelldateien, die für die Kompilierung erforderlich sind. Diese werden in der erstellten Datei deps aufgelistet.

Tipp:srcs verarbeitet auch die generierte Quelle, auf die im Makro include! verwiesen wird. Diese Quellen müssen von einem anderen Modul wie genrule oder rust_protobuf bereitgestellt werden. Fügen Sie srcs den Namen des Moduls, das die generierte Quelle bereitstellt, mit dem Präfix : ein, um die Quelle einzubeziehen. (Zum Beispiel ":libmyproto". Die Hauptquelldatei muss der erste Eintrag im Array sein, wenn diese Funktion verwendet wird.

Vermeiden Sie diese Verwendung nach Möglichkeit für Plattformcode. Weitere Informationen finden Sie unter Quellcodegeneratoren.

kiste_name

crate_name legt die Metadaten für den Kistennamen über das --crate_name-Flag rustc fest. Bei Modulen, die Bibliotheken erstellen, muss dieser mit dem erwarteten Crate-Namen in der Quelle übereinstimmen. Wenn beispielsweise auf das Modul libfoo_bar in der Quelle als extern crate foo_bar verwiesen wird, muss dies crate_name: "foo_bar" sein.

Dieses Attribut ist für alle rust_*-Module gleich, aber für Module, die Rust-Bibliotheken erstellen (z. B. rust_library rust_ffi, rust_bindgen, rust_protobuf und rust_proc_macro), erforderlich. Diese Module erzwingen rustc-Anforderungen für die Beziehung zwischen crate_name und dem Ausgabedateinamen. Weitere Informationen finden Sie im Abschnitt Bibliotheksmodule.

Lint

Der rustc Linter wird standardmäßig für alle Modultypen außer Quellgeneratoren ausgeführt. Einige Lint-Sets werden definiert und zur Validierung der Modulquelle verwendet. Mögliche Werte für solche Lint-Sets sind:

• default die Standard-Lints, je nach Speicherort des Moduls
• android ist der strengste Lint-Satz, der für den gesamten Android-Plattformcode gilt
• vendor einen gelockerten Satz von Lints auf den Anbietercode angewendet
• none, um alle Lint-Warnungen und -Fehler zu ignorieren

Clippy_lints

Der Clippy-Linter wird standardmäßig auch für alle Modultypen außer Quellgeneratoren ausgeführt. Es sind einige Lints definiert, mit denen die Modulquelle validiert wird. Dies sind einige mögliche Werte:

• default-Standardsatz von Lints je nach Modulstandort
• android ist der strengste Lint-Satz, der für den gesamten Android-Plattformcode gilt
• vendor einen gelockerten Satz von Lints auf den Anbietercode angewendet
• none, um alle Lint-Warnungen und -Fehler zu ignorieren

Tipp:Sie können Linters während der Entwicklung auf „none“ setzen, um Linter-Fehler zu vermeiden. Bei der Prüfung müssen Sie jedoch möglicherweise angeben, dass Sie festgeschriebene Module mit weniger strikten Lints verwenden.

Ausgabe

Mit edition wird die Rust-Version definiert, die für die Kompilierung dieses Codes verwendet werden soll. Dies entspricht den Standardversionen für C und C++. Gültige Werte sind 2015 und 2018 (Standardeinstellung).

flags

flags enthält eine Stringliste mit Flags, die während der Kompilierung an rustc übergeben werden sollen.

ld_flags

ld-flags enthält eine Stringliste mit Flags, die beim Kompilieren der Quelle an den Linker übergeben werden. Diese werden über das -C linker-args-Flag von rustc übergeben. clang wird als Linker-Frontend verwendet und ruft lld für die eigentliche Verknüpfung auf.

Hinweis: Da diese an Clang übergeben werden, behandeln Sie sie als Clang-Flags. Präfix-Flags, die mit dem üblichen -Wl-Clang-Präfix an lld übergeben werden.

Funktionen

features ist eine Stringliste von Funktionen, die während der Kompilierung aktiviert werden müssen. Wird von --cfg 'feature="foo"' an Rustc übergeben. Die meisten Funktionen sind additiv, sodass in vielen Fällen alle Funktionen enthalten sind, die von allen abhängigen Modulen benötigt werden. In Fällen, in denen Funktionen sich gegenseitig ausschließen, sollten Sie jedoch in allen Build-Dateien zusätzliche Module definieren, die in Konflikt stehende Funktionen enthalten.

Hinweis :Im Gegensatz zu einem Cargo-Build gibt es keine „Standardfunktionen“, die implizit aktiviert sind. Die Funktion „default“ ist ein spezielles Cargo-Keyword. Sofern der Code nicht explizit eine Funktion namens „default“ verarbeitet, hat die Einstellung „default“ keine Auswirkungen.

cfgs

cfgs enthält eine Stringliste mit cfg-Flags, die während der Kompilierung aktiviert werden sollen. Diese wird von --cfg foo und --cfg "fizz=buzz" an rustc übergeben.

Das Build-System setzt bestimmte cfg-Flags in bestimmten Situationen automatisch. Diese sind unten aufgeführt:

• Für als dylib erstellte Module ist die android_dylib-cfg festgelegt.

• Für Module, die das VNDK verwenden, wird die cfg-Datei android_vndk festgelegt. Dies ähnelt der Definition von __ANDROID_VNDK__ für C++.

strip

Mit strip wird festgelegt, ob und wie die Ausgabedatei (falls zutreffend) entfernt wird. Wenn dieser Parameter nicht festgelegt ist, werden bei Gerätemodulen standardmäßig alle Informationen außer Mini-Debug-Informationen entfernt. Bei Hostmodulen werden standardmäßig keine Symbole entfernt. Gültige Werte sind none, um das Entfernen zu deaktivieren, und all, um alles zu entfernen, einschließlich der Mini-Debug-Informationen. Weitere Werte finden Sie in der Referenz zu Soong-Modulen.

host_supported

Bei Gerätemodulen gibt der Parameter host_supported an, ob das Modul auch eine Hostvariante bereitstellen soll.

Bibliotheksabhängigkeiten definieren

Rust-Module können durch die folgenden Attribute sowohl von der CC- als auch der Rust-Bibliothek abhängen:

Name der Property	Beschreibung
rustlibs	Liste der rust_library-Module, die auch Abhängigkeiten sind. Verwenden Sie dies als bevorzugte Methode zum Deklarieren von Abhängigkeiten, da das Build-System so die bevorzugte Verknüpfung auswählen kann. Weitere Informationen finden Sie unten im Abschnitt Beim Verknüpfen mit Rust-Bibliotheken.
rlibs	Liste der rust_library-Module, die statisch als rlibs verknüpft werden müssen. Seien Sie vorsichtig. Weitere Informationen finden Sie unten im Abschnitt Beim Verknüpfen mit Rust-Bibliotheken.
shared_libs	Liste der cc_library-Module, die dynamisch als gemeinsam genutzte Bibliotheken verknüpft werden müssen.
static_libs	Liste der cc_library-Module, die statisch als statische Bibliotheken verknüpft werden müssen.
whole_static_libs	Liste der cc_library-Module, die statisch als statische Bibliotheken verknüpft und als Ganzes in die resultierende Bibliothek aufgenommen werden sollen. Bei rust_ffi_static-Varianten wird whole_static_libraries in das resultierende statische Bibliotheksarchiv aufgenommen. Bei rust_library_rlib-Varianten werden whole_static_libraries-Bibliotheken in die resultierende rlib-Bibliothek gebündelt. Tipp:Dadurch wird verhindert, dass Sie die Abhängigkeiten abhängiger Elemente für diese Bibliothek neu deklarieren. In einigen Fällen kann dies jedoch zu einer unnötigen Größe führen, wenn die statische Bibliothek in einem Abhängigkeitsbaum dupliziert wird. Vollständig in „rlibs“ enthaltene statische Bibliotheken werden vollständig in das abhängige „dylibs“ aufgenommen, wodurch eine weitere Quelle potenzieller Bloats entsteht.

Wenn Sie eine Verknüpfung mit Rust-Bibliotheken herstellen, sollten Sie nach Möglichkeit die Eigenschaft rustlibs anstelle von rlibs oder dylibs verwenden, es sei denn, Sie haben einen bestimmten Grund dafür. So kann das Buildsystem die richtige Verknüpfung basierend auf den Anforderungen des Stammmoduls auswählen. Außerdem wird die Wahrscheinlichkeit verringert, dass ein Abhängigkeitsbaum sowohl die rlib- als auch die dylib-Version einer Bibliothek enthält, was zu einem Kompilierungsfehler führt.

Nicht unterstützte und eingeschränkte Support-Build-Funktionen

Rust von Soong bietet eingeschränkte Unterstützung für vendor- und vendor_ramdisk-Images und -Snapshots. staticlibs, cdylibs, rlibs und binaries werden jedoch unterstützt. Für Anbieter-Image-Build-Ziele ist das Attribut android_vndk cfg festgelegt. Sie können dies im Code verwenden, wenn es Unterschiede zwischen den System- und Anbieterzielen gibt. rust_proc_macros werden nicht als Teil von Anbieter-Snapshots erfasst. Wenn diese benötigt werden, müssen Sie sie entsprechend versionieren.

Produkt-, VNDK- und Wiederherstellungs-Images werden nicht unterstützt.

Inkrementelle Builds

Entwickler können die inkrementelle Kompilierung der Rust-Quelle aktivieren, indem sie die Umgebungsvariable SOONG_RUSTC_INCREMENTAL auf true setzen.

Warnung: Es ist nicht garantiert, dass die Binärdateien mit denen identisch sind, die von Buildbots generiert werden. Die Adressen von Funktionen oder Daten in den Objektdateien können unterschiedlich sein. Lassen Sie diesen Wert nicht konfiguriert, damit die generierten Artefakte zu 100 % den Artefakten entsprechen, die von der EngProd-Infrastruktur erstellt wurden.