Come principio generale, le definizioni dei moduli rust_* rispettano da vicino l'utilizzo e le aspettative di cc_*. Di seguito è riportato un esempio di definizione di un modulo
per un file binario Rust:
rust_binary {
name: "hello_rust",
crate_name: "hello_rust",
srcs: ["src/hello_rust.rs"],
host_supported: true,
}
Questa pagina illustra le proprietà più comuni per i moduli rust_*. Per
ulteriori informazioni sui tipi di moduli specifici e sulle definizioni dei moduli di esempio,
consulta le pagine
Moduli binari,
Moduli libreria,
o
Moduli di test.
Tipi di moduli di base
| Tipo | Definizione | Per ulteriori informazioni |
|---|---|---|
rust_binary | Un file binario Rust | Pagina Moduli binari |
rust_library | Produce una libreria Rust e fornisce le varianti rlib e
dylib. |
rust_library,
pagina Moduli libreria. |
rust_ffi | Produce una libreria C Rust utilizzabile dai moduli cc e fornisce varianti statiche e condivise. | rust_ffi,
pagina Moduli libreria |
rust_proc_macro | Produce una proc-macro Rust libreria.
(Sono analoghe ai plug-in del compilatore.) |
rust_proc_macro,
pagina Moduli librerie |
rust_test | Produce un file binario di test Rust che utilizza l' infrastruttura di test Rust standard. | Pagina Moduli di test |
rust_fuzz | Produce un file binario di fuzzing Rust che sfrutta
libfuzzer. |
rust_fuzz esempio di modulo |
rust_protobuf | Genera l'origine e produce una Rust libreria che fornisce un'interfaccia per un determinato protobuf. | Pagine Moduli Protobuf e Generatori di origine |
rust_bindgen | Genera l'origine e produce una Rust libreria contenente binding Rust per le librerie C. | Pagine Moduli di binding Bindgen e Generatori di origine |
Proprietà comuni importanti
Queste proprietà sono comuni a tutti i moduli Rust di Android. Eventuali proprietà aggiuntive (univoche) associate ai singoli Rust moduli sono elencate nella pagina del modulo.
name
name è il nome del modulo. Come altri moduli Soong, deve essere univoco nella maggior parte dei tipi di moduli Android.bp. Per impostazione predefinita, name viene utilizzato come nome file di output. Se il nome file di output deve essere diverso dal nome del modulo, utilizza la proprietà stem per definirlo.
stem
stem (facoltativo) fornisce il controllo diretto sul nome file di output (esclusi l'estensione del file e altri suffissi). Ad esempio, una rust_library_rlib
libreria con un valore di base libfoo produce un file libfoo.rlib. Se non fornisci un valore per la proprietà stem, il nome file di output adotta il nome del modulo per impostazione predefinita.
Utilizza la funzione stem quando non puoi impostare il nome del modulo sul nome file di output desiderato. Ad esempio, la rust_library per la crate log è denominata
liblog_rust,
perché esiste già una liblog cc_library. L'utilizzo della proprietà stem in questo caso garantisce che il file di output sia denominato liblog.* anziché liblog_rust.*.
srcs
srcs contiene un singolo file di origine che rappresenta il punto di ingresso del modulo (in genere main.rs o lib.rs). rustc gestisce la risoluzione e l'individuazione di tutti gli altri file di origine necessari per la compilazione, che vengono enumerati nel file deps prodotto.
Se possibile, evita questo utilizzo per il codice della piattaforma. Per ulteriori informazioni, consulta la sezione Generatori di origine .
crate_name
crate_name imposta i metadati del nome della crate tramite il flag rustc --crate_name. Per i moduli che producono librerie, questo deve corrispondere al nome della crate previsto utilizzato nell'origine. Ad esempio, se il modulo libfoo_bar viene fatto riferimento
nell'origine come extern crate foo_bar, allora questo deve essere
crate_name: "foo_bar".
Questa proprietà è comune a tutti i moduli rust_*, ma è obbligatoria per i moduli
che producono librerie Rust (ad esempio rust_library
rust_ffi, rust_bindgen, rust_protobuf, e rust_proc_macro). Questi
moduli applicano i requisiti rustc sulla relazione tra crate_name
e il nome file di output. Per ulteriori informazioni, consulta la
sezione Moduli libreria.
lints
Il linter rustc viene eseguito per impostazione predefinita per tutti i tipi di moduli, ad eccezione dei generatori di origine. Alcuni set di lint vengono definiti e utilizzati per convalidare l'origine del modulo. I valori possibili per questi set di lint sono i seguenti:
default: il set di lint predefinito, a seconda della posizione del moduloandroid: il set di lint più rigoroso che si applica a tutto il codice della piattaforma Androidvendor: un set di lint rilassato applicato al codice del fornitorenone: per ignorare tutti gli avvisi e gli errori di lint
clippy_lints
Anche il linter clippy viene eseguito per impostazione predefinita per tutti i tipi di moduli, ad eccezione dei generatori di origine. Vengono definiti alcuni set di lint che vengono utilizzati per convalidare l'origine del modulo. Ecco alcuni valori possibili:
default: set di lint predefinito a seconda della posizione del moduloandroid: il set di lint più rigoroso che si applica a tutto il codice della piattaforma Androidvendor: un set di lint rilassato applicato al codice del fornitorenone: per ignorare tutti gli avvisi e gli errori di lint
edition
edition definisce l'edizione Rust da utilizzare per la
compilazione di questo codice. È simile alle versioni std per C e C++. I valori validi sono 2015, 2018 e 2021 (valore predefinito).
flags
flags contiene un elenco di stringhe di flag da passare a rustc durante la compilazione.
ld_flags
ld-flags contiene un elenco di stringhe di flag da passare al linker durante la compilazione dell'origine. Questi vengono passati dal flag `rustc` -C linker-args. clang viene utilizzato come front-end del linker, richiamando lld per il collegamento effettivo.
features
features è un elenco di stringhe di funzionalità che devono essere abilitate durante la compilazione.
Viene passato a rustc da --cfg 'feature="foo"'. La maggior parte delle funzionalità sono additive, quindi in molti casi si tratta del set completo di funzionalità richiesto da tutti i moduli dipendenti. Tuttavia, nei casi in cui le funzionalità si escludono a vicenda, definisci moduli aggiuntivi in tutti i file di build che forniscono funzionalità in conflitto.
cfgs
cfgs contiene un elenco di stringhe di flag cfg da abilitare durante la compilazione.
Viene passato a rustc da --cfg foo e --cfg "fizz=buzz".
Il sistema di compilazione imposta automaticamente determinati flag cfg in situazioni particolari, elencate di seguito:
I moduli creati come dylib avranno il cfg
android_dylibimpostato.I moduli che utilizzano il VNDK avranno il cfg
android_vndkimpostato. È simile alla__ANDROID_VNDK__definizione per C++.
strip
strip controlla se e come il file di output viene rimosso (se applicabile).
Se non è impostato, i moduli del dispositivo vengono rimossi per impostazione predefinita, ad eccezione delle mini informazioni di debug.
Per impostazione predefinita, i moduli host non rimuovono alcun simbolo. I valori validi includono none per disabilitare la rimozione e all per rimuovere tutto, incluse le mini informazioni di debug.
Ulteriori valori sono disponibili nel
riferimento ai moduli Soong.
host_supported
Per i moduli del dispositivo, il parametro host_supported indica se il modulo deve fornire anche una variante host.
Definire le dipendenze della libreria
I moduli Rust possono dipendere dalle librerie CC e Rust tramite le seguenti proprietà:
| Nome proprietà | Descrizione |
|---|---|
rustlibs |
Elenco dei moduli rust_library che sono anche dipendenze. Utilizza questo come metodo preferito per dichiarare le dipendenze, in quanto consente al sistema di compilazione di selezionare il collegamento preferito. (Vedi Quando si esegue il collegamento alle librerie Rust di seguito) |
rlibs |
Elenco dei moduli rust_library che devono essere collegati staticamente
come rlibs. (Utilizzare con cautela; vedi
Quando si esegue il collegamento alle librerie Rust di seguito.) |
shared_libs |
Elenco dei moduli cc_library che devono essere collegati dinamicamente
come librerie condivise. |
static_libs |
Elenco dei moduli cc_library che devono essere collegati staticamente
come librerie statiche. |
whole_static_libs |
Elenco dei moduli cc_library che devono essere collegati staticamente
come librerie statiche e inclusi interamente nella libreria risultante. Per
rust_ffi_static varianti, whole_static_libraries verrà incluso nell'
archivio della libreria statica risultante. Per le varianti rust_library_rlib,
whole_static_libraries librerie verranno raggruppate nella libreria rlib
risultante.
|
Quando si esegue il collegamento alle librerie Rust, come
best practice, utilizza la proprietà rustlibs anziché rlibs o
dylibs, a meno che tu non abbia un motivo specifico per farlo. In questo modo, il sistema di build
può selezionare il collegamento corretto in base a ciò che richiede il modulo root e
riduce la probabilità che un albero delle dipendenze contenga sia le versioni rlib che
dylib di una libreria (il che causerà un errore di compilazione).
Funzionalità di build non supportate e con supporto limitato
Rust di Soong offre un supporto limitato per le immagini e gli snapshot vendor e
vendor_ramdisk. Tuttavia, staticlibs, cdylibs, rlibs e binaries sono supportati. Per le destinazioni di build delle immagini del fornitore, viene impostata la proprietà cfg android_vndk. Puoi utilizzarla nel codice se esistono differenze tra le destinazioni di sistema e del fornitore. rust_proc_macros non vengono acquisite come parte degli snapshot del fornitore; se queste dipendono, assicurati di controllarle correttamente con il controllo delle versioni.
Le immagini di prodotto, VNDK e ripristino non sono supportate.
Build incrementali
Gli sviluppatori possono abilitare la compilazione incrementale dell'origine
Rust impostando la variabile di ambiente SOONG_RUSTC_INCREMENTAL
su true.
Avviso: non è garantito che i file binari prodotti siano identici a quelli generati dai buildbot. Gli indirizzi delle funzioni o dei dati contenuti nei file oggetto potrebbero essere diversi. Per assicurarti che gli artefatti generati siano identici al 100% a quelli creati dall'infrastruttura EngProd, lascia questo valore non impostato.