Es gibt zwei Arten von Rust-Bibliotheksmodulen: eines, das Rust-Bibliotheken erzeugt, und eines, das C-kompatible Bibliotheken erzeugt. Für das Build-System können Sie Rust-Prozedurmakros (proc-macros) als spezielle Art von Bibliothek betrachten.
rust_library
Das rust_library-Modul erstellt Rust-Bibliotheken, die von anderen Rust-Modulen verwendet werden können.
Zusätzlich zu den _host-Varianten haben Rust-Bibliotheken Modultypen, die die verfügbare Verknüpfung steuern.
| Rust-Bibliotheksmodultyp | Definition |
|---|---|
| rust_library | Bietet beide Bibliotheksvarianten, rlib und dylib. AOSP empfiehlt diesen Modultyp für Rust-Bibliotheken, da Module so richtig funktionieren, wenn sie als Abhängigkeit unter der Eigenschaft rustlibs aufgeführt sind. |
| rust_library_rlib | Stellt nur die rlib-Variante einer Rust-Bibliothek bereit. Module, die nur rlib-Varianten bereitstellen, funktionieren möglicherweise nicht mit der rustlibs-Property. |
| rust_library_dylib | Stellt nur die dylib-Variante einer Rust-Bibliothek bereit. Module, die nur dylib-Varianten bereitstellen, funktionieren möglicherweise nicht mit der rustlibs-Property. |
rust_ffi
Das Modul rust_ffi erstellt C-kompatible Bibliotheken für die Interoperabilität mit CC-Modulen.
Zusätzlich zu den _host-Varianten haben Rust-FFI-Bibliotheken Modultypen, die die verfügbare Verknüpfung steuern. Diese sind in der folgenden Tabelle aufgeführt.
| Rust-FFI-Bibliotheksmodultyp | Definition |
|---|---|
| rust_ffi | Bietet sowohl statische als auch gemeinsam genutzte C-Bibliotheksvarianten. |
| rust_ffi_shared | Stellt nur die C-Variante der gemeinsam genutzten Bibliothek bereit. |
| rust_ffi_static | Stellt nur die statische C-Bibliothek bereit. |
Ein einfaches Beispiel für die Verwendung von rust_ffi zum Aufrufen von Rust aus C finden Sie auf der Seite Android Rust Patterns.
Weitere Informationen zur erweiterten Verwendung finden Sie in der offiziellen Rust-Dokumentation.
rust_proc_macro
Prozedurale Makros (Proc-Makros) in Rust können nützlich sein, um den Compiler zu erweitern, damit er Quellcode transformiert oder neue Attribute bereitstellt. Weitere Informationen finden Sie in der offiziellen Rust-Dokumentation auf der Seite Procedural Macros.
Für das Build-System funktioniert das rust_proc_macro-Modul ähnlich wie die rust_library-Module. Fügen Sie für Module, die von rust_proc_macros abhängen, den Modulnamen dem Attribut proc_macros hinzu.
Da proc_macros Compiler-Plug-ins sind, sind sie zwangsläufig auf den Host ausgerichtet und erzeugen keinen Code, der auf einem Gerät ausgeführt werden könnte.
Wichtige Eigenschaften von Rust-Bibliotheken
Die in der Tabelle unten definierten Properties gelten zusätzlich zu den wichtigen gemeinsamen Properties, die für alle Module gelten. Diese sind entweder besonders wichtig für Rust-Bibliotheksmodule oder weisen ein einzigartiges Verhalten auf, das spezifisch für den Modultyp rust_library ist.
| Rust-Bibliothekseigenschaften | Definition |
|---|---|
| Stamm / Name | Mit dem Attribut stem wird der Dateiname der Ausgabebibliothek gesteuert, der andernfalls standardmäßig name lautet.
Der Rust-Compiler stellt bestimmte Anforderungen an Bibliotheksdateinamen. Daher erzwingt das Build-System diese Anforderungen, um Kompilierungsprobleme zu vermeiden.
Der Ausgabedateiname muss dem Format |
| crate_name | Dies ist eine erforderliche Property für Module, die Bibliotheken erstellen. Sie steht außerdem in Beziehung zum Ausgabedateinamen. Weitere Informationen finden Sie in der Definition von stem. |
| export_include_dirs | Für rust_ffi-Module definiert diese Eigenschaft eine Liste von Strings, die relative Include-Pfade darstellen. Diese Pfade enthalten Header, die von abhängigen cc-Modulen verwendet werden können. |
Verknüpfung von „rust_library“ oder „rust_ffi“
Standardmäßig werden Rust-Bibliotheksmodule, die auf Geräte ausgerichtet sind, immer dynamisch mit libstd verknüpft. Hostmodule werden jedoch immer statisch mit libstd verknüpft.
Die für rustlibs-Abhängigkeiten verwendete Verknüpfung hängt von den Verknüpfungseinstellungen des Stammmoduls ab. Beispiel: Bei einem rust_binary mit prefer_rlib: true werden Rust-Bibliotheksvarianten verwendet, die rustlibs als rlibs verknüpfen.
Damit die Erstellung von Modulen für Root-Abhängigkeiten möglich ist, die nicht auf dynamischen Rust-Bibliotheken basieren (z. B. statische ausführbare Dateien), bietet rlibs sowohl dynamische als auch statische libstd-Linkage-Varianten. Die richtige Variante wird automatisch von Soong verknüpft.