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 und 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 der Ausgabedateiname sich 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. Die rust_library für die Kiste log heißt beispielsweise liblog_rust, da bereits eine 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 Lintsatz, der für den gesamten Android-Plattformcode gilt
• vendor – eine lockere Gruppe von Lints, die auf 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. Einige mögliche Werte:

• default Standardsatz von Lints je nach Speicherort des Moduls
• android – der strengste Lintsatz, der für den gesamten Android-Plattformcode gilt
• vendor – eine lockere Gruppe von Lints, die auf 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 von Funktionen, die während der Kompilierung aktiviert werden müssen. Dieser Wert wird von --cfg 'feature="foo"' an rustc übergeben. Die meisten Funktionen sind additiv. In vielen Fällen besteht dies also aus dem vollständigen Funktionsumfang, der von allen abhängigen Modulen benötigt wird. 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:

• Für Module, 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 Definition von __ANDROID_VNDK__ für C++.

strip

Mit strip wird gesteuert, ob und wie die Ausgabedatei (falls zutreffend) gekürzt wird. Wenn dieser Wert nicht festgelegt ist, werden bei 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 zum Deaktivieren des Entfernens und all zum Entfernen aller Elemente, 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 Eigenschaften sowohl von CC- als auch von Rust-Bibliotheken abhängen:

Beim Verknüpfen mit Rust-Bibliotheken sollten Sie dies nach Möglichkeit 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

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 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 davon 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 festlegen.

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 werden.