Modules Android Rust

De manière générale, les définitions de module rust_* respectent étroitement l'utilisation et les attentes de cc_*. Voici un exemple de définition de module pour un binaire Rust:

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

Cette page présente les propriétés les plus courantes des modules rust_*. Pour en savoir plus sur les types de modules spécifiques et les exemples de définitions de modules, consultez les sections Modules binaires, Modules de bibliothèque ou Modules de test.

Types de modules de base

Propriétés communes importantes

Ces propriétés sont communes à tous les modules Rust Android. Toutes les propriétés supplémentaires (uniques) associées à des modules Rust individuels sont listées sur la page de ce module.

nom

name correspond au nom de votre module. Comme les autres modules Soong, il doit être unique pour la plupart des types de modules Android.bp. Par défaut, name est utilisé comme nom de fichier de sortie. Si le nom de fichier de sortie doit être différent du nom du module, utilisez la propriété stem pour le définir.

tige

stem (facultatif) permet de contrôler directement le nom de fichier de sortie (à l'exception de l'extension de fichier et des autres suffixes). Par exemple, une bibliothèque rust_library_rlib avec une valeur de base libfoo génère un fichier libfoo.rlib. Si vous ne fournissez pas de valeur pour la propriété stem, le nom de fichier de sortie adopte le nom du module par défaut.

Utilisez la fonction stem lorsque vous ne pouvez pas définir le nom du module sur le nom de fichier de sortie souhaité. Par exemple, le rust_library de la crate log est nommé liblog_rust, car un liblog cc_library existe déjà. Dans ce cas, l'utilisation de la propriété stem garantit que le fichier de sortie est nommé liblog.* au lieu de liblog_rust.*.

srcs

srcs contient un seul fichier source qui représente le point d'entrée de votre module (généralement main.rs ou lib.rs). rustc gère la résolution et la découverte de tous les autres fichiers sources requis pour la compilation, qui sont énumérés dans le fichier deps généré.

Dans la mesure du possible, évitez cette utilisation pour le code de la plate-forme. Pour en savoir plus, consultez la section Générateurs de code source.

crate_name

crate_name définit les métadonnées du nom de la crate via l'indicateur --crate_name rustc. Pour les modules qui génèrent des bibliothèques, ce nom doit correspondre au nom de crate attendu utilisé dans la source. Par exemple, si le module libfoo_bar est référencé dans la source sous le nom extern crate foo_bar, ce champ doit être crate_name: "foo_bar".

Cette propriété est commune à tous les modules rust_*, mais elle est obligatoire pour les modules qui génèrent des bibliothèques Rust (comme rust_library rust_ffi, rust_bindgen, rust_protobuf et rust_proc_macro). Ces modules appliquent les exigences rustc à la relation entre crate_name et le nom de fichier de sortie. Pour en savoir plus, consultez la section Modules de bibliothèque.

lints

Le linter rustc est exécuté par défaut pour tous les types de modules, à l'exception des générateurs de sources. Certains ensembles lint sont définis et utilisés pour valider la source du module. Les valeurs possibles pour ces ensembles de lint sont les suivantes:

• default : ensemble de lints par défaut, en fonction de l'emplacement du module
• android : ensemble lint le plus strict qui s'applique à tout le code de la plate-forme Android
• vendor : ensemble de lints appliqués au code du fournisseur
• none pour ignorer tous les avertissements et erreurs de lint

clippy_lints

Le linter clippy est également exécuté par défaut pour tous les types de modules, à l'exception des générateurs de sources. Quelques ensembles de lints sont définis et sont utilisés pour valider la source du module. Voici quelques valeurs possibles:

• Ensemble par défaut de lints default en fonction de l'emplacement du module
• android : ensemble lint le plus strict qui s'applique à tout le code de la plate-forme Android
• vendor : ensemble de lints appliqués au code du fournisseur
• none pour ignorer tous les avertissements et erreurs de lint

édition

edition définit l'édition Rust à utiliser pour compiler ce code. Cela ressemble aux versions std pour C et C++. Les valeurs valides sont 2015, 2018 et 2021 (par défaut).

indicateurs

flags contient une liste de chaînes d'indicateurs à transmettre à rustc lors de la compilation.

ld_flags

ld-flags contient une liste de chaînes d'options à transmettre au linker lors de la compilation de la source. Ils sont transmis par l'indicateur rustc -C linker-args. clang est utilisé comme interface du lisseur, qui appelle lld pour l'association réelle.

fonctionnalités

features est une liste de chaînes de fonctionnalités qui doivent être activées lors de la compilation. --cfg 'feature="foo"' le transmet à rustc. La plupart des fonctionnalités sont additives. Dans de nombreux cas, il s'agit donc de l'ensemble complet de fonctionnalités requis par tous les modules dépendants. Toutefois, lorsque les fonctionnalités sont exclusives les unes des autres, définissez des modules supplémentaires dans les fichiers de compilation qui fournissent des fonctionnalités en conflit.

cfgs

cfgs contient une liste de chaînes d'indicateurs cfg à activer lors de la compilation. Il est transmis à rustc par --cfg foo et --cfg "fizz=buzz".

Le système de compilation définit automatiquement certains indicateurs cfg dans des situations particulières, listées ci-dessous:

• Les modules compilés en tant que dylib auront la configuration android_dylib définie.

• La configuration android_vndk sera définie pour les modules qui utiliseraient le VNDK. Cela ressemble à la définition de __ANDROID_VNDK__ pour C++.

strip

strip contrôle si le fichier de sortie est supprimé et comment (le cas échéant). Si ce paramètre n'est pas défini, les modules de l'appareil suppriment par défaut tout sauf mini debuginfo. Par défaut, les modules hôtes ne suppriment aucun symbole. Les valeurs valides incluent none pour désactiver le dénudage et all pour supprimer tout, y compris le mini debuginfo. Vous trouverez d'autres valeurs dans la documentation de référence sur les modules Soong.

host_supported

Pour les modules d'appareil, le paramètre host_supported indique si le module doit également fournir une variante d'hôte.

Définir les dépendances de bibliothèque

Les modules Rust peuvent dépendre à la fois des bibliothèques CC et Rust via les propriétés suivantes:

Lorsque vous associez des bibliothèques Rust, nous vous recommandons d'utiliser la propriété rustlibs plutôt que rlibs ou dylibs, sauf si vous avez une raison spécifique de le faire. Cela permet au système de compilation de sélectionner l'association appropriée en fonction de ce que le module racine exige, et réduit la probabilité qu'un arbre de dépendances contienne à la fois les versions rlib et dylib d'une bibliothèque (ce qui entraînera l'échec de la compilation).

Fonctionnalités de build non compatibles et limitées

Rust de Soong offre une compatibilité limitée avec les images et les instantanés vendor et vendor_ramdisk. Toutefois, staticlibs, cdylibs, rlibs et binaries sont compatibles. Pour les cibles de compilation d'images du fournisseur, la propriété cfg android_vndk est définie. Vous pouvez l'utiliser dans le code s'il existe des différences entre les cibles système et les cibles du fournisseur. Les rust_proc_macros ne sont pas capturées dans les instantanés du fournisseur. Si vous dépendez de ces éléments, assurez-vous de les contrôler correctement.

Les images de produit, VNDK et de récupération ne sont pas acceptées.

Compilations incrémentielles

Les développeurs peuvent activer la compilation incrémentielle de la source Rust en définissant la variable d'environnement SOONG_RUSTC_INCREMENTAL sur true.

Avertissement: Il n'est pas garanti que des binaires identiques à ceux générés par les buildbots soient produits. Les adresses des fonctions ou des données contenues dans les fichiers d'objets peuvent être différentes. Pour vous assurer que les artefacts générés sont 100 % identiques à ceux créés par l'infrastructure EngProd, ne définissez pas cette valeur.