Android-Rust-Module

rust_*-Moduldefinitionen entsprechen in der Regel genau der Verwendung und den Erwartungen von cc_*. Im Folgenden finden Sie ein Beispiel für ein Modul, Definition für ein Rust-Binärprogramm:

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

Auf dieser Seite werden die häufigsten Attribute für rust_*-Module behandelt. Für zu bestimmten Modultypen und Beispielmoduldefinitionen, Siehe Binärmodule Bibliotheksmodule, oder Testmodule

Grundlegende Modultypen

EingebenDefinitionWeitere Informationen
rust_binaryEin Rust-Binärprogramm Binärmodule Seite
rust_libraryErzeugt eine Rust-Bibliothek und bietet sowohl rlib- als auch dylib-Varianten. rust_library, Page „Library Modules“ (Bibliotheksmodule).
rust_ffiErzeugt eine Rust-C-Bibliothek, die über Cc verwendet werden kann Module und bietet sowohl statische als auch gemeinsam genutzte Varianten. rust_ffi, Seite „Bibliotheksmodule“
rust_proc_macroErstellt eine proc-macro-Rust-Bibliothek. (Diese sind analog zu Compiler-Plug-ins.) rust_proc_macro, Seite „Bibliotheksmodule“
rust_testErzeugt eine Rust-Testbinärdatei mit dem Standard-Rust-Test-Harnisch. Seite Module testen
rust_fuzzErzeugt eine Rust-Fuzz-Binärdatei, die libfuzzer nutzt. Beispiel für ein rust_fuzz-Modul
rust_protobufGeneriert eine Quelle und erstellt einen Rust-Wert -Bibliothek, die eine Schnittstelle für einen bestimmten protobuf bereitstellt. Seiten Protobufs-Module und Source Generators
rust_bindgenGeneriert eine Quelle und erstellt einen Rust-Bibliothek mit Rust-Bindungen an C-Bibliotheken. Die Seiten Bindgen Bindings Modules und Source Generators

Wichtige allgemeine 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 auch dieser Name eindeutig sein für die meisten Android.bp-Modultypen. Standardmäßig wird name als Ausgabe verwendet filename. Wenn sich der Ausgabedateiname vom Modulnamen unterscheiden muss, verwenden Sie die Property stem, um ihn zu definieren.

Stamm

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 das Attribut stem angeben, verwendet der Ausgabedateiname den Modulname.

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 z. B. liblog_rust, weil ein liblog cc_library existiert bereits. Mit dem Attribut stem wird in diesem Fall sichergestellt, dass die Ausgabe Die Datei heißt liblog.* statt liblog_rust.*.

„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 von Plattformcodes nach Möglichkeit. Siehe Quellgeneratoren .

crate_name

crate_name legt die Metadaten für den Kistennamen über das rustc---crate_name fest. melden. 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_libraryrust_ffi, rust_bindgen, rust_protobuf und rust_proc_macro). Bei diesen Modulen gelten rustc-Anforderungen an die Beziehung zwischen crate_name und dem Ausgabedateinamen. Weitere Informationen finden Sie im Abschnitt Bibliotheksmodule.

Lint

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 solches Lint lautet:

  • default ist der Standardsatz von Lints, abhängig vom Speicherort des Moduls
  • android ist der strengste Lint-Satz, der 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. Einige Arten von Fusseln definiert, die zur Validierung der Modulquelle verwendet werden. Dies sind einige Werte:

  • default Standard-Lints je nach Speicherort des Moduls
  • android ist der strengste Lint-Satz, der 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 für die Kompilierung dieses Codes verwendet werden soll. Dies entspricht den Standardversionen für C und C++. Gültige Werte sind 2015 und 2018 (Standardeinstellung).

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 an den Linker übergeben werden sollen Quelle. 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. In Fällen, in denen sich Funktionen jedoch gegenseitig ausschließen, Zusätzliche Module in allen Build-Dateien definieren, die in Konflikt stehende Funktionen bereitstellen.

cfgs

cfgs enthält eine Stringliste mit cfg-Flags, die während der Kompilierung aktiviert werden sollen. Diese 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-cfg festgelegt.

  • Für Module, die den VNDK verwenden, 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-Informationen zur Fehlerbehebung. Weitere Werte finden Sie in der Soong-Modulreferenz.

host_supported

Bei Gerätemodulen gibt der Parameter host_supported an, ob das Modul sollte auch eine Hostvariante angegeben werden.

Bibliotheksabhängigkeiten definieren

Rust-Module können über die folgenden Eigenschaften sowohl von CC- als auch von Rust-Bibliotheken abhängen:

Name der Property Beschreibung
rustlibs Liste der rust_library-Module, die auch Abhängigkeiten sind. Verwenden Sie diese Methode, um Abhängigkeiten zu deklarieren, da das Build-System so die bevorzugte Verknüpfung auswählen kann. (Siehe unten Verknüpfung mit Rust-Bibliotheken)
rlibs Liste der rust_library Module, die statisch verknüpft sein müssen als rlibs. (Mit Vorsicht zu verwenden; siehe Bei Verknüpfungen mit Rust-Bibliotheken (siehe unten)
shared_libs Liste der cc_library-Module, die dynamisch sein müssen als geteilte Fotogalerien verknüpft.
static_libs Liste der cc_library-Module, die statisch sein müssen als statische Bibliotheken verknüpft.
whole_static_libs Liste der cc_library-Module, die statisch als statische Bibliotheken verknüpft und vollständig in die resultierende Bibliothek aufgenommen werden sollen. Für rust_ffi_static Varianten, whole_static_libraries werden in der das daraus entstandene statische Bibliotheksarchiv. Bei rust_library_rlib Varianten werden whole_static_libraries Bibliotheken in der resultierenden rlib-Bibliothek gebündelt.

Verwenden Sie beim Verknüpfen mit Rust-Bibliotheken nach Möglichkeit die Eigenschaft rustlibs anstelle von rlibs oder dylibs, 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änkte Support-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 Ziele von Builds von Anbieterbildern ist die Eigenschaft android_vndk cfg festgelegt. Sie können dies im Code verwenden, zwischen System- und Anbieterzielen. rust_proc_macros sind nicht im Rahmen von Anbieter-Snapshots erfasst; Wenn diese davon abhängen, eine entsprechende Versionskontrolle.

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

Inkrementelle Builds

Entwickler können die inkrementelle Kompilierung Rust-Quelle durch Festlegen des SOONG_RUSTC_INCREMENTAL Umgebungsvariable auf true.

Warnung: Es wird nicht garantiert, dass Sie Binärdateien erstellen, die mit den die von Buildbots generiert wurden. Die Adressen von Funktionen oder Daten, die in der können abweichen. Um sicherzustellen, dass die generierten Artefakte 100 % sind die mit denen der EngProd-Infrastruktur identisch sind, lassen Sie diesen Wert nicht.