Moduli Android Rust

Come principio generale, le definizioni dei moduli rust_* si attengono strettamente all'utilizzo e alle aspettative di cc_*. Di seguito è riportato un esempio di definizione di 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 maggiori informazioni sui tipi di moduli specifici e sulle definizioni di esempio di modulo, consulta Moduli binari, Moduli di libreria o Moduli di test.

Tipi di moduli di base

Importanti proprietà comuni

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

nome

name è il nome del modulo. Come gli altri moduli Qwiklabs, 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.

gambo

stem (facoltativo) consente di controllare direttamente il nome del file di output (esclusa l'estensione del file e altri suffissi). Ad esempio, una raccolta rust_library_rlib con un valore del tronco pari a libfoo produce un file libfoo.rlib. Se non fornisci un valore per la proprietà stem, il nome del file di output adotta per impostazione predefinita il nome del modulo.

Utilizza la funzione stem se non puoi impostare il nome del modulo sul nome file di output desiderato. Ad esempio, il rust_library per la cassa log è denominato liblog_rust perché esiste già un liblog cc_library. In questo caso, l'utilizzo della proprietà stem garantisce che il file di output venga denominato liblog.* anziché liblog_rust.*.

src

srcs contiene un unico file di origine che rappresenta il punto di ingresso del modulo (di solito main.rs o lib.rs). rustc gestisce la risoluzione e il rilevamento di tutti gli altri file di origine richiesti per la compilazione, elencati nel file deps che viene generato.

Se possibile, evita questo utilizzo per il codice della piattaforma. Per ulteriori informazioni, consulta Generatori di codice sorgente.

crate_name

crate_name imposta i metadati del nome della cassa tramite il flag rustc --crate_name. Per i moduli che producono librerie, deve corrispondere al nome della cassa previsto utilizzato nell'origine. Ad esempio, se nell'origine viene fatto riferimento al modulo libfoo_bar come extern crate foo_bar, 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 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 vengono definiti e utilizzati per convalidare l'origine del modulo. I valori possibili per questi set di lint sono i seguenti:

• default l'insieme predefinito di linee, 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 di lint meno rigorosi applicati al codice del fornitore
• none per ignorare tutti gli avvisi e gli errori lint

clippy_lints

Anche il linter Clippy viene eseguito per impostazione predefinita per tutti i tipi di moduli, ad eccezione dei generatori di codice sorgente. Sono definiti alcuni set di lint che vengono utilizzati per convalidare il codice sorgente del modulo. Ecco alcuni valori possibili:

• default insieme 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 di lint meno rigorosi applicati al codice del fornitore
• none per ignorare tutti gli avvisi e gli errori di lint

edizione

edition definisce la versione Rust da utilizzare per compilare questo codice. È simile alle versioni std per C e C++. I valori validi sono 2015 e 2018 (predefinito).

flag

flags contiene un elenco di stringhe di flag da passare a rustc durante la compilazione.

ld_flag

ld-flags contiene un elenco di stringhe di flag da passare al linker durante la compilazione del codice sorgente. Questi vengono superati dalla bandiera rustc -C linker-args. clang viene utilizzato come front-end del linker, che richiama lld per il collegamento effettivo.

funzioni

features è un elenco di stringhe di funzionalità che devono essere abilitate durante la compilazione. Questo viene passato a Rustc da --cfg 'feature="foo"'. La maggior parte delle funzionalità è additiva, perciò in molti casi si tratta dell'intero set di funzionalità richieste da tutti i moduli dipendenti. Tuttavia, nei casi in cui le funzionalità si escludono l'una dall'altra, 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. Questo viene passato a rustc da --cfg foo e --cfg "fizz=buzz".

Il sistema di compilazione imposta automaticamente determinati flag cfg in determinate situazioni, elencate di seguito:

• I moduli creati come dylib avranno il set cfg android_dylib.

• Per i moduli che utilizzerebbero il VNDK sarà impostato il valore cfg android_vndk. È simile alla definizione di __ANDROID_VNDK__ per C++.

strip

strip controlla se e come viene rimosso il file di output (se applicabile). Se non viene configurato, i moduli dispositivo eliminano per impostazione predefinita tutte le informazioni tranne quelle mini di debug. Per impostazione predefinita, i moduli host non eliminano alcun simbolo. I valori validi includono none per disattivare l'eliminazione e all per rimuovere tutti i dati, incluse le informazioni di debug mini. Ulteriori valori sono disponibili nel riferimento ai moduli Soong.

supportato_da_host

Per i moduli del dispositivo, il parametro host_supported indica se il modulo deve fornire anche una variante host.

Definisci le dipendenze delle librerie

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

Quando esegui il collegamento con le 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 compilazione può selezionare il collegamento corretto in base a ciò che richiede il modulo principale e riduce la possibilità che un albero delle dipendenze contenga entrambe le versioni rlib edylib di una libreria (con un conseguente errore della 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, sono supportati i criteri staticlibs, cdylibs, rlibs e binaries. Per i target di compilazione delle immagini del fornitore, è impostata la proprietà android_vndk cfg. Puoi utilizzarlo nel codice se esistono differenze tra i target del sistema e del fornitore. rust_proc_macros non vengono acquisiti come parte degli snapshot dei fornitori. Se dipendono da questi fattori, assicurati di controllarli in modo appropriato.

Le immagini del prodotto, VNDK e di 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.

Attenzione: non è garantito che vengano generati programmi 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.