Android-Rust-Module

Im Allgemeinen halten sich rust_*-Moduldefinitionen eng an die Verwendung und Erwartungen von cc_*. Das folgende Beispiel zeigt eine Moduldefinition für eine Rust-Binärdatei:

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

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

Grundlegende Modultypen

Wichtige gemeinsame Eigenschaften

Diese Attribute sind für alle Rust-Module für Android gleich. Alle zusätzlichen (eindeutigen) Attribute, die mit einzelnen Rust-Modulen verknüpft sind, werden auf der Seite des jeweiligen 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 Ausgabedateiname verwendet. Wenn sich der Ausgabedateiname vom Modulnamen unterscheiden muss, verwenden Sie die Eigenschaft stem, um ihn zu definieren.

Stamm

Mit stem (optional) können Sie den Ausgabedateinamen direkt steuern (ohne Dateiendung und andere Suffixe). Beispiel: Eine rust_library_rlib-Bibliothek mit dem Stammwert libfoo erzeugt eine libfoo.rlib-Datei. Wenn Sie keinen Wert für die Property stem angeben, wird standardmäßig der Modulname für den Ausgabedateinamen verwendet.

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

srcs

srcs enthält eine einzelne Quelldatei, die den Einstiegspunkt für Ihr Modul darstellt (in der Regel main.rs oder lib.rs). rustc übernimmt die Auflösung und Erkennung aller anderen für die Kompilierung erforderlichen Quelldateien. Diese werden in der erstellten Datei deps aufgeführt.

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

crate_name

crate_name legt die Metadaten für den Crate-Namen über das Flag rustc --crate_name fest. Bei Modulen, die Bibliotheken erstellen, muss dieser Name mit dem erwarteten Crate-Namen im Quellcode übereinstimmen. Wenn beispielsweise auf das Modul libfoo_bar im Quellcode als extern crate foo_bar verwiesen wird, muss „crate_name“ „foo_bar“ sein.

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

Lints

Der rustc-Linter wird standardmäßig für alle Modultypen mit Ausnahme von Quellgeneratoren ausgeführt. Einige Lint-Sets werden definiert und zum Validieren von Modulquellen verwendet. Folgende Werte sind für solche Lint-Sets möglich:

• default die Standardgruppe von Lints, je nach Speicherort des Moduls
• android – der strengste Lint-Satz, der für den gesamten Android-Plattformcode gilt
• vendor – eine Reihe von Lints, die auf den Anbietercode 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 sind einige Gruppen von Lints definiert, die zum Validieren des Modulquellcodes verwendet werden. Hier sind einige mögliche Werte:

• default Standardsatz von Lints je nach Speicherort des Moduls
• android – der strengste Lint-Satz, der für den gesamten Android-Plattformcode gilt
• vendor – eine Reihe von Lints, die auf den Anbietercode angewendet werden
• none, um alle Lint-Warnungen und ‑Fehler zu ignorieren

Ausgabe

edition definiert die Rust-Version, die zum Kompilieren dieses Codes verwendet werden soll. Dies ähnelt den Standardversionen für C und C++. Gültige Werte sind 2015, 2018 und 2021 (Standard).

flags

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

ld_flags

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

Funktionen

features ist eine Stringliste mit Funktionen, die während der Kompilierung aktiviert werden müssen. Dies wird von --cfg 'feature="foo"' an rustc übergeben. Die meisten Funktionen sind additiv. In vielen Fällen besteht diese Menge also aus allen Funktionen, die von allen abhängigen Modulen benötigt werden. Wenn sich Funktionen jedoch gegenseitig ausschließen, definieren Sie zusätzliche Module in allen Build-Dateien, die in Konflikt stehende Funktionen bereitstellen.

cfgs

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

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

• Bei Modulen, die als „dylib“ erstellt wurden, ist die android_dylib-Konfiguration festgelegt.

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

strip

strip steuert, ob und wie die Ausgabedatei (falls zutreffend) gekürzt wird. Wenn dies nicht festgelegt ist, werden in Gerätemodulen standardmäßig alle Informationen außer Mini-Debug-Informationen entfernt. In 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 Soong Modules Reference.

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 über die folgenden Attribute sowohl von CC- als auch von Rust-Bibliotheken abhängen:

Beim Verknüpfen mit Rust-Bibliotheken sollten Sie dies als Best Practice mit der Eigenschaft rustlibs anstelle von rlibs oder dylibs tun, es sei denn, Sie haben einen bestimmten Grund dafür. So kann das Build-System 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änkt unterstützte Build-Funktionen

Die Rust-Implementierung 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 Build-Ziele für Anbieter-Images wird die Eigenschaft 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 Anbietersnapshots erfasst. Wenn Sie von diesen abhängig sind, müssen Sie sie entsprechend versionieren.

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

Inkrementelle Builds

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

Warnung: Es ist nicht garantiert, dass dadurch Binärdateien erstellt werden, die mit den von Buildbots generierten Binärdateien identisch sind. Die Adressen von Funktionen oder Daten in den Objektdateien können sich unterscheiden. Lassen Sie diesen Wert leer, damit die generierten Artefakte zu 100 % mit den Artefakten übereinstimmen, die von der EngProd-Infrastruktur erstellt wurden.