Als allgemeines Prinzip orientieren sich die Moduldefinitionen von rust_*
eng an der Verwendung und den Erwartungen cc_*
. Das Folgende ist ein Beispiel einer Moduldefinition für eine Rust- Binärdatei:
rust_binary {
name: "hello_rust",
crate_name: "hello_rust",
srcs: ["src/hello_rust.rs"],
host_supported: true,
}
Diese Seite behandelt die häufigsten Eigenschaften für rust_*
Module. Weitere Informationen zu bestimmten Modultypen und Beispielmoduldefinitionen finden Sie unter Binärmodule , Bibliotheksmodule oder Testmodule .
Grundlegende Modultypen
Typ | Definition | Für mehr Informationen |
---|---|---|
rust_binary | Eine Rust -Binärdatei | Seite „Binärmodule“. |
rust_library | Erstellt eine Rust- Bibliothek und stellt sowohl rlib als auch dylib Varianten bereit. | rust_library , Seite „Bibliotheksmodule“. |
rust_ffi | Erstellt eine Rust -C-Bibliothek, die von CC-Modulen verwendet werden kann, und stellt sowohl statische als auch gemeinsam genutzte Varianten bereit. | rust_ffi , Seite „Bibliotheksmodule“. |
rust_proc_macro | Erstellt eine proc-macro Rust -Bibliothek. (Diese sind analog zu Compiler-Plugins.) | rust_proc_macro , Seite „Bibliotheksmodule“. |
rust_test | Erstellt eine Rust -Testbinärdatei, die das standardmäßige Rust- Testkabel verwendet. | Seite „Testmodule“. |
rust_fuzz | Erstellt eine Rust- Fuzz-Binärdatei, libfuzzer nutzt. | Beispiel für das Modul rust_fuzz |
rust_protobuf | Erzeugt Quellcode und erstellt eine Rust- Bibliothek, die eine Schnittstelle für einen bestimmten Protobuf bereitstellt. | Seiten zu Protobufs-Modulen und Quellgeneratoren |
rust_bindgen | Erzeugt eine Quelle und erstellt eine Rust- Bibliothek, die Rust- Bindungen an C-Bibliotheken enthält. | Seiten zu Bindgen-Bindungsmodulen und Quellgeneratoren |
Wichtige gemeinsame Eigenschaften
Diese Eigenschaften sind allen Android Rust- Modulen gemeinsam. Alle zusätzlichen (eindeutigen) Eigenschaften, die einzelnen Rust- Modulen zugeordnet sind, werden auf der Seite dieses Moduls aufgeführt.
Name
name
ist der Name Ihres Moduls. Wie andere Soong-Module muss dies für die meisten Android.bp
-Modultypen eindeutig sein. Standardmäßig wird name
als Ausgabedateiname verwendet. Wenn sich der Name der Ausgabedatei vom Namen des Moduls unterscheiden muss, verwenden Sie die stem
, um ihn zu definieren.
Stengel
stem
(optional) bietet direkte Kontrolle über den Namen der Ausgabedatei (mit Ausnahme der Dateierweiterung und anderer Suffixe). Beispielsweise erzeugt eine rust_library_rlib
-Bibliothek mit dem Stammwert libfoo
eine libfoo.rlib
Datei. Wenn Sie keinen Wert für die stem
angeben, übernimmt der Ausgabedateiname standardmäßig den Modulnamen.
Verwenden Sie die stem
, wenn Sie den Modulnamen nicht auf den gewünschten Ausgabedateinamen festlegen können. Beispielsweise heißt die rust_library
für die log
liblog_rust
, da bereits eine liblog cc_library
vorhanden ist. Durch die Verwendung der Eigenschaft stem
wird in diesem Fall sichergestellt, dass die Ausgabedatei den Namen liblog.*
anstelle von liblog_rust.*
.
srcs
srcs
enthält eine einzelne Quelldatei, die den Einstiegspunkt zu Ihrem Modul darstellt (normalerweise main.rs
oder lib.rs
). rustc
übernimmt die Auflösung und Erkennung aller anderen für die Kompilierung erforderlichen Quelldateien, und diese werden in der erstellten deps
Datei aufgelistet.
Vermeiden Sie nach Möglichkeit diese Verwendung für Plattformcode; Weitere Informationen finden Sie unter Quellgeneratoren .
Kistename
crate_name
legt die Metadaten des Crate-Namens über das Flag rustc
--crate_name
fest. Bei Modulen, die Bibliotheken erzeugen, muss dieser mit dem erwarteten Crate-Namen übereinstimmen, der in der Quelle verwendet wird. Wenn beispielsweise das Modul libfoo_bar
in der Quelle als extern crate foo_bar
referenziert wird, muss dies crate_name sein: „foo_bar“.
Diese Eigenschaft ist allen rust_*
Modulen gemeinsam, sie ist jedoch für Module erforderlich , die Rust -Bibliotheken erzeugen (wie rust_library
rust_ffi
, rust_bindgen
, rust_protobuf
und rust_proc_macro
). Diese Module erzwingen rustc
Anforderungen an die Beziehung zwischen crate_name
und dem Ausgabedateinamen. Weitere Informationen finden Sie im Abschnitt Bibliotheksmodule .
Flusen
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 Flusensets sind wie folgt:
-
default
wird der Standardsatz an Lints verwendet, abhängig vom Standort des Moduls -
android
ist der strengste Lint-Satz, der für den gesamten Code der Android-Plattform gilt -
vendor
eine lockere Reihe von Lints, die auf den Vendor-Code angewendet werden -
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 werden einige Sätze von Lints definiert, die zur Validierung der Modulquelle verwendet werden. Dies sind einige mögliche Werte:
-
default
Standardsatz von Lints, abhängig vom Standort des Moduls -
android
ist der strengste Lint-Satz, der für den gesamten Code der Android-Plattform gilt -
vendor
eine lockere Reihe von Lints, die auf den Vendor-Code angewendet werden -
none
, um alle Lint-Warnungen und -Fehler zu ignorieren
Auflage
edition
definiert die Rust- Edition, die zum Kompilieren dieses Codes verwendet werden soll. Dies ähnelt den Standardversionen für C und C++. Gültige Werte sind 2015
und 2018
(Standard).
Flaggen
flags
enthält eine String-Liste von Flags, die während der Kompilierung an rustc
übergeben werden.
ld_flags
ld-flags
enthält eine Zeichenfolgenliste mit Flags, die beim Kompilieren der Quelle an den Linker übergeben werden. Diese werden von der Rustc-Flagge -C linker-args
übergeben. clang
wird als Linker-Frontend verwendet und ruft lld
für die eigentliche Verlinkung auf.
Merkmale
features
ist eine String-Liste von Features, die während der Kompilierung aktiviert werden müssen. Dies wird von --cfg 'feature="foo"'
an rustc übergeben. Die meisten Funktionen sind additiv, sodass sie in vielen Fällen aus dem vollständigen Funktionssatz bestehen, der von allen abhängigen Modulen benötigt wird. Definieren Sie jedoch in Fällen, in denen Funktionen einander ausschließen, zusätzliche Module in allen Build-Dateien, die widersprüchliche Funktionen bereitstellen.
cfgs
cfgs
enthält eine Zeichenfolgenliste von cfg
Flags, die während der Kompilierung aktiviert werden sollen. Dies wird von --cfg foo
und --cfg "fizz=buzz"
an rustc
übergeben.
Das Build-System setzt in bestimmten Situationen automatisch bestimmte cfg
Flags, die unten aufgeführt sind:
Für Module, die als Dylib erstellt wurden, ist die Konfigurationsdatei
android_dylib
festgelegt.Für Module, die das VNDK verwenden würden, ist die Konfigurationsdatei
android_vndk
festgelegt. Dies ähnelt der__ANDROID_VNDK__
Definition für C++.
Streifen
strip
steuert, ob und wie die Ausgabedatei entfernt wird (falls zutreffend). Wenn dies nicht festgelegt ist, entfernen Gerätemodule standardmäßig alles außer Mini-Debuginfo. Hostmodule entfernen standardmäßig keine Symbole. Zu den gültigen Werten gehören none
, um das Strippen zu deaktivieren, und all
, um alles zu entfernen, einschließlich der Mini-Debuginfo. Weitere Werte finden Sie in der Soong Modules Reference .
host_supported
Bei Gerätemodulen gibt der Parameter host_supported
an, ob das Modul auch eine Host-Variante bereitstellen soll.
Bibliotheksabhängigkeiten definieren
Rust- Module können über die folgenden Eigenschaften sowohl von CC- als auch von Rust- Bibliotheken abhängen:
Name des Anwesens | Beschreibung |
---|---|
rustlibs | Liste der rust_library Module, die ebenfalls Abhängigkeiten sind. Verwenden Sie dies als Ihre bevorzugte Methode zum Deklarieren von Abhängigkeiten, da es dem Build-System ermöglicht, die bevorzugte Verknüpfung auszuwählen. (Siehe „ Beim Verknüpfen mit Rust -Bibliotheken“ weiter unten) |
rlibs | Liste der rust_library Module, die statisch als rlibs verknüpft werden müssen. (Mit Vorsicht verwenden; siehe „Beim Verknüpfen mit Rust -Bibliotheken“ weiter unten.) |
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 vollständig in die resultierende Bibliothek einbezogen werden sollen. Für rust_ffi_static Varianten werden whole_static_libraries in das resultierende statische Bibliotheksarchiv aufgenommen. Für rust_library_rlib Varianten werden whole_static_libraries -Bibliotheken in der resultierenden rlib Bibliothek gebündelt. |
Wenn Sie mit Rust-Bibliotheken verknüpfen , sollten Sie als Best Practice die Eigenschaft rustlibs
anstelle von rlibs
oder dylibs
verwenden, es sei denn, Sie haben einen bestimmten Grund dafür. Dadurch kann das Build-System die richtige Verknüpfung basierend auf den Anforderungen des Root-Moduls auswählen und die Wahrscheinlichkeit verringern, dass ein Abhängigkeitsbaum sowohl die rlib
als auch dylib
Version einer Bibliothek enthält (was dazu führt, dass die Kompilierung fehlschlägt).
Nicht unterstützte und eingeschränkt unterstützte Build-Funktionen
Soongs Rust bietet eingeschränkte Unterstützung für vendor
und vendor_ramdisk
Images und Snapshots. Allerdings werden staticlibs
, cdylibs
, rlibs
und binaries
unterstützt. Für Anbieter-Image-Build-Ziele ist die cfg
Eigenschaft android_vndk
festgelegt. Sie können dies im Code verwenden, wenn Unterschiede zwischen dem System und den Anbieterzielen bestehen. rust_proc_macros
werden nicht als Teil von Anbieter-Snapshots erfasst; Wenn diese abhängig sind, stellen Sie sicher, dass Sie sie entsprechend einer Versionskontrolle unterziehen.
Produkt-, VNDK- und Wiederherstellungsimages 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 kann nicht garantiert werden, dass Binärdateien erstellt werden, die mit den von Buildbots generierten identisch sind. Die Adressen von Funktionen oder Daten, die in den Objektdateien enthalten sind, können unterschiedlich sein. Um sicherzustellen, dass die generierten Artefakte zu 100 % mit denen identisch sind, die von der EngProd-Infrastruktur erstellt wurden, lassen Sie diesen Wert nicht festgelegt.