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.

Grundlegende Modultypen

Wichtige gemeinsame Eigenschaften

Diese Eigenschaften sind für alle Android-Rust-Module gleich. Alle zusätzlichen (eindeutigen) Eigenschaften, 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 Dateiname für die Ausgabe verwendet. Wenn sich der Ausgabedateiname vom Modulnamen unterscheiden muss, verwenden Sie die Property stem, um ihn zu definieren.

Stiel

stem (optional) ermöglicht die direkte Steuerung des Ausgabedateinamens (ohne Dateiendung und andere Suffixe). Eine rust_library_rlib-Bibliothek mit dem Stammwert libfoo erzeugt beispielsweise 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 Ausgabedateinamen festlegen können. Beispiel: Die rust_library für den log-Container heißt liblog_rust, da bereits eine liblog cc_library 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.

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

crate_name

crate_name legt die Metadaten für den Namen des Pakets über das Flag rustc --crate_name fest. Bei Modulen, die Bibliotheken generieren, 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.

Diese Eigenschaft ist für alle rust_*-Module gemeinsam, aber erforderlich für Module, die Rust-Bibliotheken generieren (z. B. rust_library rust_ffi, rust_bindgen, rust_protobuf und rust_proc_macro). Bei diesen Modulen werden rustc-Anforderungen an die Beziehung zwischen crate_name und dem Ausgabedateinamen erzwungen. 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. Folgende Werte sind für solche Lint-Sets möglich:

• default die Standard-Lints, je nach Speicherort des Moduls
• android die strengste Lint-Sammlung, die für den gesamten Android-Plattformcode gilt
• vendor eine lockere Reihe 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 werden einige Lint-Sets definiert, die zum Validieren der Modulquelle verwendet werden. Mögliche Werte:

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

Ausgabe

Mit edition wird die Rust-Version definiert, die zum Kompilieren dieses Codes verwendet werden soll. Das entspricht den std-Versionen 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 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.

Funktionen

features ist eine Stringliste mit Funktionen, die während der Kompilierung aktiviert werden müssen. Dieser wird von --cfg 'feature="foo"' an rustc übergeben. Die meisten Funktionen sind additiv, sodass in vielen Fällen der vollständige Funktionssatz enthalten ist, der für alle abhängigen Module erforderlich ist. Wenn Funktionen jedoch sich gegenseitig ausschließen, definieren Sie in allen Build-Dateien zusätzliche Module, die sich überschneidende Funktionen bereitstellen.

cfgs

cfgs enthält eine Stringliste mit 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 setzt bestimmte cfg-Flags in bestimmten Situationen automatisch. Diese sind unten aufgeführt:

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

• Für Module, die das VNDK verwenden würden, ist die android_vndk-cfg festgelegt. Das ä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 aus 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 Soong-Modulreferenz.

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 Properties sowohl von CC- als auch von Rust-Bibliotheken abhängen:

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änkt unterstützte Build-Funktionen

Soong's Rust 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 Ziele von Builds von Anbieterbildern ist die Eigenschaft android_vndk cfg festgelegt. Sie können diese Funktion in 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 von Rust-Quellcode aktivieren, indem sie die Umgebungsvariable SOONG_RUSTC_INCREMENTAL auf true festlegen.

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 sich unterscheiden. Damit die generierten Artefakte zu 100 % mit denen übereinstimmen, die mit der EngProd-Infrastruktur erstellt wurden, lassen Sie diesen Wert leer.