Modules Android Rust

En règle générale, les définitions de module rust_* sont très proches de l'utilisation et des 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 couvre 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 répertorié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.

stem

stem (facultatif) permet de contrôler directement le nom de fichier de sortie (à l'exclusion de l'extension de fichier et d'autres suffixes). Par exemple, une rust_library_rlib bibliothèque avec une valeur de stem libfoo produit 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 pour le 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 Générateurs de sources .

crate_name

crate_name définit les métadonnées du nom du crate 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, alors la valeur 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 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 de 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 lint 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 lint assoupli appliqué au code du fournisseur
• none : permet d'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 lint sont définis et utilisés pour valider la source du module. Voici quelques valeurs possibles :

• default : ensemble de lint 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 lint assoupli appliqué au code du fournisseur
• none : permet d'ignorer tous les avertissements et erreurs de lint

édition

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

flags

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. Ces indicateurs sont transmis par l'indicateur rustc -C linker-args. clang est utilisé comme interface de l'éditeur de liens, en appelant lld pour la liaison réelle.

fonctionnalités

features est une liste de chaînes de fonctionnalités qui doivent être activées lors de la compilation. Cette liste est transmise à rustc par --cfg 'feature="foo"'. La plupart des fonctionnalités sont additives. Dans de nombreux cas, cela consiste donc en l'ensemble complet de fonctionnalités requis par tous les modules dépendants. Toutefois, dans les cas où les fonctionnalités s'excluent mutuellement, 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. Cette liste est transmise à rustc par --cfg foo et --cfg "fizz=buzz".

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

• Les modules créés en tant que dylib auront le cfg android_dylib défini.

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

strip

strip contrôle si et comment le fichier de sortie est supprimé (le cas échéant). Si cette valeur n'est pas définie, les modules d'appareil suppriment par défaut tout, à 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-informations de débogage. Vous trouverez d'autres valeurs dans la référence des 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 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 de compilation non compatibles et à 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 compatibles. Pour les cibles de compilation d'images 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 fournisseur. Les rust_proc_macros ne sont pas capturées dans les instantanés de fournisseur. Si vous en dépendez, assurez-vous de les contrôler de manière appropriée.

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

Compilations incrémentales

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

Avertissement : Cela ne garantit pas la production de 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.