Moduli Android Rust

Come principio generale, le definizioni dei moduli rust_* aderiscono strettamente all'utilizzo e alle aspettative cc_* . Quello che segue è un esempio di definizione di modulo per un binario Rust :

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

Questa pagina copre le proprietà più comuni per i moduli rust_* . Per ulteriori informazioni su tipi di moduli specifici e definizioni di moduli di esempio, vedere Moduli binari , Moduli di libreria o Moduli di test .

Tipi di moduli base

Tipo Definizione Per maggiori informazioni
rust_binary Un binario Rust Pagina Moduli binari
rust_library Produce una libreria Rust e fornisce sia le varianti rlib che dylib . rust_library , pagina Moduli libreria.
rust_ffi Produce una libreria Rust C utilizzabile dai moduli cc e fornisce varianti sia statiche che condivise. rust_ffi , pagina Moduli libreria
rust_proc_macro Produce una libreria Rust proc-macro . (Questi sono analoghi ai plugin del compilatore.) rust_proc_macro , pagina Moduli librerie
rust_test Produce un file binario di test Rust che utilizza il cablaggio di test Rust standard. Pagina Moduli di test
rust_fuzz Produce un binario Rust fuzz sfruttando libfuzzer . Esempio di modulo rust_fuzz
rust_protobuf Genera il codice sorgente e produce una libreria Rust che fornisce un'interfaccia per un particolare protobuf. Pagine Moduli Protobufs e Generatori di sorgenti
rust_bindgen Genera il sorgente e produce una libreria Rust contenente collegamenti Rust alle librerie C. Pagine Moduli di associazioni Bindgen e Generatori di origine

Proprietà comuni importanti

Queste proprietà sono comuni a tutti i moduli Android Rust . Eventuali proprietà aggiuntive (uniche) associate ai singoli moduli Rust sono elencate nella pagina di quel modulo.

nome

name è il nome del modulo. Come altri moduli Soong, questo deve essere univoco per la maggior parte dei tipi di moduli Android.bp . Per impostazione predefinita, name viene utilizzato come nome del file di output. Se il nome del file di output deve essere diverso dal nome del modulo, utilizzare la proprietà stem per definirlo.

stelo

stem (facoltativo) fornisce il controllo diretto sul nome del file di output (esclusa l'estensione del file e altri suffissi). Ad esempio, una libreria rust_library_rlib con un valore radice di libfoo produce un file libfoo.rlib . Se non fornisci un valore per la proprietà stem , il nome del 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 del file di output desiderato. Ad esempio, la rust_library per il log crate si chiama 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 sorgente che rappresenta il punto di ingresso al tuo modulo (solitamente main.rs o lib.rs ). rustc gestisce la risoluzione e il rilevamento di tutti gli altri file sorgente richiesti per la compilazione e questi vengono enumerati nel file deps che viene prodotto.

Quando possibile, evitare questo utilizzo per il codice della piattaforma; vedere Generatori di sorgenti per ulteriori informazioni.

nome_cassa

crate_name imposta i metadati del nome del crate tramite il flag rustc --crate_name . Per i moduli che producono librerie, questo deve corrispondere al nome del contenitore previsto utilizzato nell'origine. Ad esempio, se si fa riferimento al modulo libfoo_bar nel codice sorgente come extern crate foo_bar , allora deve essere crate_name: "foo_bar".

Questa proprietà è comune a tutti i moduli rust_* , ma è richiesta per i moduli che producono librerie Rust (come 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 del file di output. Per ulteriori informazioni, consultare la sezione Moduli della libreria .

lanugine

Il linter rusticc viene eseguito per impostazione predefinita per tutti i tipi di moduli tranne i generatori di sorgenti. Alcuni set di lanugine sono definiti e utilizzati per convalidare l'origine del modulo. I valori possibili per tali set di lanugine sono i seguenti:

  • default il set predefinito di lanugine, a seconda della posizione del modulo
  • android il set di lanugine più rigoroso che si applica a tutto il codice della piattaforma Android
  • vendor una serie rilassata di lint applicati al codice del fornitore
  • none per ignorare tutti gli avvisi e gli errori relativi alla lanugine

clippy_lints

Anche il clippy linter viene eseguito per impostazione predefinita per tutti i tipi di moduli tranne i generatori di sorgenti. Sono definiti alcuni insiemi di lint che vengono utilizzati per convalidare l'origine del modulo. Questi sono alcuni valori possibili:

  • set predefinito di lanugine default in base alla posizione del modulo
  • android il set di lanugine più rigoroso che si applica a tutto il codice della piattaforma Android
  • vendor una serie rilassata di lint applicati al codice del fornitore
  • none per ignorare tutti gli avvisi e gli errori relativi alla lanugine

edizione

edition definisce l'edizione di Rust da utilizzare per compilare questo codice. Questo è simile alle versioni std per C e C++. I valori validi sono 2015 e 2018 (predefinito).

bandiere

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 del codice sorgente. Questi vengono passati dal flag -C linker-args rusticc. clang viene utilizzato come front-end del linker, invocando lld per il collegamento effettivo.

caratteristiche

features è un elenco di stringhe di funzionalità che devono essere abilitate durante la compilazione. Questo viene passato a rusticc da --cfg 'feature="foo"' . La maggior parte delle funzionalità sono aggiuntive, quindi in molti casi consistono nell'insieme completo di funzionalità richieste da tutti i moduli dipendenti. Tuttavia, nei casi in cui le funzionalità si escludono a vicenda, definire moduli aggiuntivi in ​​qualsiasi file di build che fornisca funzionalità in conflitto.

cfgs

cfgs contiene un elenco di stringhe di flag cfg da abilitare durante la compilazione. Questo 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 set cfg android_dylib .

  • I moduli che utilizzerebbero VNDK avranno il set cfg android_vndk . Questo è simile alla definizione __ANDROID_VNDK__ per C++.

striscia

strip controlla se e come il file di output viene rimosso (se applicabile). Se questa opzione non viene impostata, i moduli del dispositivo eliminano per impostazione predefinita tutto tranne le mini informazioni di debug. I moduli host, per impostazione predefinita, non rimuovono alcun simbolo. I valori validi includono none per disabilitare lo stripping e all per eliminare tutto, incluso il mini debuginfo. Ulteriori valori possono essere trovati nel riferimento ai moduli Soong .

host_supportato

Per i moduli 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 sia dalle librerie CC che da quelle Rust attraverso le seguenti proprietà:

Nome della proprietà Descrizione
rustlibs Elenco dei moduli rust_library che sono anche dipendenze. Utilizzalo come metodo preferito per dichiarare le dipendenze, poiché consente al sistema di compilazione di selezionare il collegamento preferito. (Vedi Quando ci si collega alle librerie Rust , di seguito)
rlibs Elenco dei moduli rust_library che devono essere collegati staticamente come rlibs . (Utilizzare con cautela; vedere Quando ci si collega 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 di moduli cc_library che dovrebbero essere collegati staticamente come librerie statiche e inclusi integralmente nella libreria risultante. Per le varianti rust_ffi_static , whole_static_libraries verrà incluso nell'archivio della libreria statica risultante. Per le varianti rust_library_rlib , le librerie whole_static_libraries verranno raggruppate nella libreria rlib risultante.

Quando ci si collega alle librerie Rust , come migliore pratica, farlo utilizzando la proprietà rustlibs anziché rlibs o dylibs a meno che non si abbia un motivo specifico per farlo. Ciò consente al sistema di compilazione di selezionare il collegamento corretto in base a ciò che richiede il modulo root e riduce la possibilità che un albero delle dipendenze contenga entrambe le versioni rlib e dylib di una libreria (che causerà il fallimento della compilazione).

Funzionalità di build con supporto limitato e non supportate

Rust di Soong offre un supporto limitato per le immagini e gli snapshot vendor e vendor_ramdisk . Tuttavia, sono supportati staticlibs , cdylibs , rlibs e binaries . Per le destinazioni di build dell'immagine del fornitore, è impostata la proprietà cfg android_vndk . È possibile utilizzarlo nel codice se sono presenti differenze tra il sistema e le destinazioni del fornitore. rust_proc_macros non vengono acquisiti come parte degli snapshot del fornitore; se si dipende da questi, assicurati di controllarne adeguatamente la versione.

Le immagini di prodotto, VNDK e di ripristino non sono supportate.

Build incrementali

Gli sviluppatori possono abilitare la compilazione incrementale del sorgente Rust impostando la variabile d'ambiente SOONG_RUSTC_INCREMENTAL su true .

Avvertenza : non è garantito che ciò produca file binari identici a quelli generati dai buildbot. Gli indirizzi delle funzioni o dei dati contenuti nei file oggetto possono essere diversi. Per garantire che gli artefatti generati siano identici al 100% a quelli creati dall'infrastruttura EngProd, lasciare questo valore non impostato.