Moduli Rust per Android

Come principio generale, le definizioni dei moduli rust_* rispettano fedelmente l'utilizzo e le aspettative di cc_*. Di seguito è riportato un esempio di definizione di un modulo per un binario Rust:

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

Questa pagina tratta le proprietà più comuni per i moduli rust_*. Per maggiori informazioni su tipi di moduli specifici ed esempi di definizioni di moduli, consulta Moduli binari, Moduli di libreria o Moduli di test.

Tipi di moduli di base

TipoDefinizionePer ulteriori informazioni
rust_binaryUn binario Rust Pagina Moduli binari
rust_libraryProduce una libreria Rust e fornisce varianti rlib e dylib. rust_library, pagina Moduli della raccolta.
rust_ffiProduce una libreria C Rust utilizzabile dai moduli cc e fornisce varianti statiche e condivise. rust_ffi, pagina Moduli della raccolta
rust_proc_macroProduce una libreria proc-macro Rust. Sono analoghi ai plug-in del compilatore. rust_proc_macro, pagina Moduli delle librerie
rust_testProduce un binario di test Rust che utilizza l'imbracatura di test standard Rust. Pagina Test Modules
rust_fuzzProduce un binario di fuzzing Rust che sfrutta libfuzzer. Esempio di modulo rust_fuzz
rust_protobufGenera l'origine e produce una libreria Rust che fornisce un'interfaccia per un protobuf specifico. Pagine Moduli Protobufs e Generatori di origine
rust_bindgenGenera il codice sorgente e produce una libreria Rust contenente i binding Rust alle librerie C. Moduli di binding Bindgen e pagine Generatori di origine

Proprietà comuni importanti

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

nome

name è il nome del modulo. Come gli altri moduli Soong, questo deve essere univoco nella 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, utilizza la proprietà stem per definirlo.

stelo

stem (facoltativo) fornisce il controllo diretto sul nome del file di output (esclusi l'estensione del file e altri suffissi). Ad esempio, una libreria rust_library_rlib con un valore di base 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 file di output desiderato. Ad esempio, rust_library per la crate log è denominato liblog_rust, perché esiste già un liblog cc_library. L'utilizzo della proprietà stem in questo caso garantisce che il file di output venga denominato liblog.* anziché liblog_rust.*.

srcs

srcs contiene un singolo file di origine che rappresenta il punto di ingresso del modulo (di solito 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 elencati nel file deps prodotto.

Se possibile, evita questo utilizzo per il codice della piattaforma. Per ulteriori informazioni, consulta 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 del crate previsto utilizzato nell'origine. Ad esempio, se il modulo libfoo_bar viene fatto riferimento nel codice sorgente 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 (come rust_library, rust_ffi, rust_bindgen, rust_protobuf e rust_proc_macro). Questi moduli applicano i requisiti rustc alla relazione tra crate_name e il nome del file di output. Per ulteriori informazioni, consulta la sezione Moduli della libreria.

lint

Il rustc linter viene eseguito per impostazione predefinita per tutti i tipi di moduli, ad eccezione dei generatori di codice sorgente. Alcuni set di lint sono definiti e utilizzati per convalidare l'origine del modulo. I valori possibili per questi set di lint sono i seguenti:

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

clippy_lints

Il linter clippy viene eseguito per impostazione predefinita per tutti i tipi di moduli, ad eccezione dei generatori di origine. Sono definiti alcuni set di lint che vengono utilizzati per convalidare l'origine del modulo. Ecco alcuni valori possibili:

  • Set predefinito di lint di default a seconda della posizione del modulo
  • android il set di lint più rigoroso che si applica a tutto il codice della piattaforma Android
  • vendor un insieme rilassato di lint applicati al codice fornitore
  • none per ignorare tutti gli avvisi e gli errori di lint

edizione

edition definisce la versione di Rust da utilizzare per compilare questo codice. È simile alle versioni standard 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 -C linker-args rustc. clang viene utilizzato come front-end del linker, richiamando lld per il collegamento effettivo.

funzioni

features è un elenco di stringhe di funzionalità che devono essere attivate durante la compilazione. Questo valore viene passato a rustc da --cfg 'feature="foo"'. La maggior parte delle funzionalità sono additive, quindi in molti casi si tratta dell'insieme completo di funzionalità richieste 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 attivare durante la compilazione. Queste informazioni vengono trasmesse 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 android_dylib cfg.

  • I moduli che utilizzano VNDK avranno impostato il file android_vndk. Questa definizione è simile a quella di __ANDROID_VNDK__ per C++.

strip

strip controlla se e come viene eliminato il file di output (se applicabile). Se questo valore non è impostato, i moduli del dispositivo vengono impostati per rimuovere tutto tranne le mini informazioni di debug. Per impostazione predefinita, i moduli host non rimuovono alcun simbolo. I valori validi includono none per disattivare l'eliminazione e all per eliminare tutto, incluse le mini informazioni di debug. Ulteriori valori sono disponibili nella Guida di 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.

Definisci le dipendenze della libreria

I moduli Rust possono dipendere sia da librerie CC che da librerie Rust tramite le seguenti proprietà:

Nome proprietà Descrizione
rustlibs Elenco dei moduli rust_library che sono anche dipendenze. Utilizza questo metodo come metodo preferito per dichiarare le dipendenze, in quanto consente al sistema di build di selezionare il collegamento preferito. (Consulta la sezione 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 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 colleghi 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 radice e si riduce la possibilità che un albero delle dipendenze contenga sia le versioni rlib che dylib di una libreria (il che causerà l'errore di compilazione).

Funzionalità di build non supportate e con supporto limitato

Rust di Soong offre supporto limitato per le immagini e gli snapshot vendor e vendor_ramdisk. Tuttavia, sono supportati staticlibs, cdylibs, rlibs e binaries. Per i target di build delle immagini del fornitore, è impostata la proprietà android_vndk cfg. Puoi utilizzarlo nel codice se ci sono differenze tra i target di sistema e del fornitore. rust_proc_macros non vengono acquisiti nell'ambito degli snapshot del fornitore; se dipendono da questi, assicurati di controllare la versione in modo appropriato.

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

Build incrementali

Gli sviluppatori possono attivare la compilazione incrementale del codice sorgente Rust impostando la variabile di ambiente SOONG_RUSTC_INCREMENTAL su true.

Avviso: non è garantito che vengano prodotti binari 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.