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 du 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 dont la valeur racine est 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.*.

SRC

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.

nom_crate

crate_name définit les métadonnées du nom de la caisse via l'option rustc --crate_name. Pour les modules qui génèrent des bibliothèques, ce champ 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 produisent des bibliothèques Rust (telles que rust_library rust_ffi, rust_bindgen, rust_protobuf et rust_proc_macro). Ces modules appliquent les exigences rustc sur la relation entre crate_name et le nom de fichier de sortie. Pour en savoir plus, consultez la section Modules de bibliothèque.

lint

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 d'analyse lint sont les suivantes:

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

Clippy

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 lint sont définis. Ils sont utilisés pour valider la source du module. Voici quelques valeurs possibles :

• default ensemble d'analyses lint par défaut en fonction de l'emplacement du module
• android est l'ensemble lint le plus strict qui s'applique à tout le code de la plate-forme Android.
• vendor : ensemble assoupli de lint appliqué 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. Cette méthode est semblable aux versions std pour C et C++. Les valeurs valides sont 2015 et 2018 (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'indicateurs à transmettre à l'éditeur de liens lors de la compilation de la source. Ils sont transmis par l'indicateur -C linker-args rustc. clang est utilisé comme interface de l'éditeur de liens, qui appelle lld pour l'association proprement dite.

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. Ceci est transmis à rustc par --cfg foo et --cfg "fizz=buzz".

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

• Le fichier de configuration android_dylib est défini pour les modules compilés en tant que dylib.

• Le cfg android_vndk est défini pour les modules qui utilisent le VNDK. Cette méthode est semblable à la définition __ANDROID_VNDK__ pour C++.

strip

strip contrôle si le fichier de sortie est supprimé et comment (le cas échéant). Si cette règle n'est pas configurée, les modules de l'appareil suppriment par défaut toutes les informations, à l'exception des mini informations de débogage. Par défaut, les modules hôtes ne suppriment aucun symbole. Les valeurs valides incluent none pour désactiver la suppression et all pour tout supprimer, y compris les mini debuginfo. Vous trouverez des valeurs supplémentaires dans la documentation de référence sur les modules Soong.

compatible avec l'hôte

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 des bibliothèques CC et Rust via les propriétés suivantes:

Lorsque vous associez des bibliothèques Rust, il est recommandé 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 la bonne association en fonction des besoins du module racine et réduit le risque qu'une arborescence 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'image de fournisseur, la propriété android_vndk cfg 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és dans les instantanés de fournisseurs. Si vous en dépendez, assurez-vous de contrôler correctement les versions.

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 parfaitement identiques à ceux créés par l'infrastructure EngProd, ne définissez pas cette valeur.