Android Rust-Module

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.