Modules Android Rust

En règle générale, les définitions des modules 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 aborde les propriétés les plus courantes des modules rust_*. Pour en savoir plus sur les types de modules spécifiques et obtenir des exemples de définitions de modules, consultez 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 est le 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 du fichier de sortie doit être différent de celui du module, utilisez la propriété stem pour le définir.

tige

stem (facultatif) permet de contrôler directement le nom du fichier de sortie (à l'exclusion de l'extension de fichier et des autres suffixes). Par exemple, une bibliothèque rust_library_rlib avec une valeur de radical 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 caisse 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 produit.

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

crate_name

crate_name définit les métadonnées du nom de la caisse via l'indicateur rustc --crate_name. Pour les modules qui produisent des bibliothèques, cette valeur 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 en tant que extern crate foo_bar, 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 (tels que rust_library, rust_ffi, rust_bindgen, rust_protobuf et rust_proc_macro). Ces modules appliquent les exigences rustc concernant la relation entre crate_name et le nom du 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 de lint sont définis et utilisés pour valider la source du module. Voici les valeurs possibles pour ces ensembles de lint :

• default, l'ensemble par défaut de lints, en fonction de l'emplacement du module
• android : ensemble de lint le plus strict qui s'applique à tout le code de la plate-forme Android
• vendor : ensemble de lints détendu appliqué au code du fournisseur
• none pour ignorer tous les avertissements et erreurs 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. Plusieurs ensembles de lints sont définis et utilisés pour valider la source du module. Voici quelques valeurs possibles :

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

édition

edition définit l'édition Rust à utiliser pour compiler ce code. Cette valeur est semblable 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'indicateurs à transmettre à l'éditeur de liens lors de la compilation de la source. Elles sont transmises par l'indicateur rustc -C linker-args. clang est utilisé comme frontend de l'éditeur de liens, en appelant lld pour l'association proprement dite.

fonctionnalités

features est une liste de chaînes de caractéristiques qui doivent être activées lors de la compilation. Cette valeur est transmise à rustc par --cfg 'feature="foo"'. La plupart des fonctionnalités sont cumulatives. Dans de nombreux cas, il s'agit donc de l'ensemble complet des fonctionnalités requises par tous les modules dépendants. Toutefois, dans les cas où les fonctionnalités sont exclusives les unes des autres, définissez des modules supplémentaires dans tous les fichiers de compilation qui fournissent des fonctionnalités conflictuelles.

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 créés en tant que dylib auront le paramètre de configuration android_dylib défini.

• Les modules qui utiliseraient le VNDK auront le paramètre cfg android_vndk défini. Elle est semblable à la définition __ANDROID_VNDK__ pour C++.

strip

strip contrôle si et comment le fichier de sortie est dépouillé (le cas échéant). Si ce paramètre n'est pas défini, les modules d'appareil sont configurés par défaut pour supprimer tous les éléments, à l'exception des informations de débogage minimales. 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 informations de débogage minimales. 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 hôte.

Définir les dépendances de la bibliothèque

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

Lorsque vous créez une association avec des bibliothèques Rust, nous vous recommandons de le faire à l'aide de 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 liaison appropriée en fonction des exigences du module racine et réduit le risque 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 non compatibles ou à compatibilité limitée

Le 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 acceptés. Pour les cibles de compilation d'images de fournisseurs, 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 fournisseur. Les rust_proc_macros ne sont pas capturés dans les instantanés des fournisseurs. Si vous en dépendez, assurez-vous de les contrôler correctement en termes de version.

Les images 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 cette commande produise des binaires identiques à ceux générés par les buildbots. Les adresses des fonctions ou des données contenues dans les fichiers objets peuvent être différentes. Pour vous assurer que les artefacts générés sont identiques à 100 % à ceux créés par l'infrastructure EngProd, ne définissez pas cette valeur.