Modules Android Rust

En règle générale, les définitions du module rust_* adhèrent étroitement à l'utilisation et aux attentes 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 plus d'informations sur des types de modules spécifiques et des exemples de définitions de modules, consultez Modules binaires , Modules de bibliothèque ou Modules de test .

Types de modules de base

Taper	Définition	Pour plus d'informations
rust_binary	Un binaire Rust	Page Modules binaires
rust_library	Produit une bibliothèque Rust et fournit des variantes rlib et dylib .	rust_library , page Modules de bibliothèque.
rust_ffi	Produit une bibliothèque Rust C utilisable par les modules cc et fournit des variantes statiques et partagées.	rust_ffi , page Modules de bibliothèque
rust_proc_macro	Produit une bibliothèque Rust proc-macro . (Ceux-ci sont analogues aux plugins du compilateur.)	rust_proc_macro , page Modules de bibliothèques
rust_test	Produit un binaire de test Rust qui utilise le harnais de test Rust standard.	Page des modules de test
rust_fuzz	Produit un binaire Rust fuzz exploitant libfuzzer .	exemple de module rust_fuzz
rust_protobuf	Génère des sources et produit une bibliothèque Rust qui fournit une interface pour un protobuf particulier.	Pages Modules Protobufs et Générateurs de sources
rust_bindgen	Génère la source et produit une bibliothèque Rust contenant les liaisons Rust aux bibliothèques C.	Pages des modules de liaisons Bindgen et des générateurs de sources

Propriétés communes importantes

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

nom

name est le nom de votre module. Comme les autres modules Soong, celui-ci 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 du nom du module, utilisez la propriété stem pour le définir.

tige

stem (facultatif) fournit un contrôle direct sur le nom du fichier de sortie (à l'exclusion de l'extension du fichier et des autres suffixes). Par exemple, une bibliothèque rust_library_rlib avec une valeur de tige libfoo produit un fichier libfoo.rlib . Si vous ne fournissez pas de valeur pour la propriété stem , le nom du 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 du fichier de sortie souhaité. Par exemple, la rust_library de la caisse log est nommée liblog_rust , car une liblog cc_library existe déjà. L'utilisation de la propriété stem dans ce cas 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, et ceux-ci sont énumérés dans le fichier deps produit.

Dans la mesure du possible, évitez cette utilisation pour le code de la plateforme ; voir Générateurs de sources pour plus d'informations.

nom_caisse

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, cela doit correspondre au nom de caisse attendu utilisé dans la source. Par exemple, si le module libfoo_bar est référencé dans les sources sous le extern crate foo_bar , alors il doit s'agir de crate_name : "foo_bar".

Cette propriété est commune à tous les modules rust_* , mais elle est requise 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 du fichier de sortie. Pour plus d'informations, consultez la section Modules de bibliothèque .

peluches

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

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

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 de peluches default en fonction de l'emplacement du module
• android l'ensemble de charpie le plus strict qui s'applique à tout le code de la plate-forme Android
• vendor un ensemble détendu de peluches appliquées au code du fournisseur
• none pour ignorer tous les avertissements et erreurs liés aux peluches

édition

edition définit l’édition Rust à utiliser pour compiler ce code. Ceci est similaire aux versions std pour C et C++. Les valeurs valides sont 2015 et 2018 (par défaut).

drapeaux

flags contient une liste de chaînes de drapeaux à 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. Ceux-ci sont transmis par l'indicateur -C linker-args rustc. clang est utilisé comme frontal de l'éditeur de liens, appelant lld pour la liaison réelle.

caractéristiques

features est une liste de chaînes de fonctionnalités qui doivent être activées lors de la compilation. Ceci est transmis à rustc par --cfg 'feature="foo"' . La plupart des fonctionnalités sont additives, donc dans de nombreux cas, il s'agit de l'ensemble complet des fonctionnalités requises par tous les modules dépendants. Cependant, dans les cas où les fonctionnalités s'excluent les unes des autres, définissez des modules supplémentaires dans tous les fichiers de build fournissant des fonctionnalités contradictoires.

CFG

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 build définit automatiquement certains indicateurs cfg dans des situations particulières, répertoriées ci-dessous :

• Les modules construits en tant que dylib auront le jeu de cfg android_dylib .

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

bande

strip contrôle si et comment le fichier de sortie est supprimé (le cas échéant). Si cette option n'est pas définie, les modules de périphérique suppriment par défaut tout sauf mini debuginfo. Les modules hôtes, par défaut, 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. Des valeurs supplémentaires peuvent être trouvées dans la référence des modules Soong .

hôte_supporté

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

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

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

Nom de la propriété	Description
rustlibs	Liste des modules rust_library qui sont également des dépendances. Utilisez-le comme méthode préférée pour déclarer les dépendances, car cela permet au système de build de sélectionner le lien préféré. (Voir Lors de la liaison avec les bibliothèques Rust , ci-dessous)
rlibs	Liste des modules rust_library qui doivent être liés statiquement en tant que rlibs . (À utiliser avec prudence ; voir Lors de la liaison avec les bibliothèques Rust , ci-dessous.)
shared_libs	Liste des modules cc_library qui doivent être liés dynamiquement en tant que bibliothèques partagées.
static_libs	Liste des modules cc_library qui doivent être liés statiquement en tant que bibliothèques statiques.
whole_static_libs	Liste des modules cc_library qui doivent être liés statiquement en tant que bibliothèques statiques et inclus dans leur intégralité dans la bibliothèque résultante. Pour les variantes rust_ffi_static , whole_static_libraries sera inclus dans l'archive de bibliothèque statique résultante. Pour les variantes rust_library_rlib , les bibliothèques whole_static_libraries seront regroupées dans la bibliothèque rlib résultante.

Lorsque vous effectuez une liaison avec des bibliothèques Rust , il est recommandé de le faire en utilisant 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 construction de sélectionner la liaison correcte en fonction de ce dont le module racine a besoin, et cela 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înerait l'échec de la compilation).

Fonctionnalités de construction de support non prises en charge et limitées

Soong's Rust offre une prise en charge limitée des images et instantanés vendor et vendor_ramdisk . Cependant, staticlibs , cdylibs , rlibs et binaries sont pris en charge. Pour les cibles de création d’images du 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 du système et du fournisseur. rust_proc_macros ne sont pas capturés dans le cadre des instantanés du fournisseur ; si ceux-ci dépendent de ceux-ci, assurez-vous de les contrôler de manière appropriée.

Les images de produit, VNDK et de récupération ne sont pas prises en charge.

Constructions incrémentielles

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

Attention : cela n'est pas garanti de produire 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 garantir que les artefacts générés sont 100 % identiques à ceux construits par l'infrastructure EngProd, laissez cette valeur non définie.