Modules Android Rust

En règle générale, les définitions de module rust_* sont étroitement liées Conditions d'utilisation et attentes concernant cc_*. Voici un exemple de module d'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 plus d'informations sur des types de modules spécifiques et des exemples de définitions de module, voir Modules binaires, Modules de bibliothèque ou Modules de test.

Remarque :Pour obtenir une documentation à jour générée automatiquement pour tous les types de modules et , consultez les Documentation de référence sur le module Soong

Types de modules de base

Type	Définition	Pour plus d'informations
rust_binary	Un binaire Rust	Modules binaires page
rust_library	Génère une bibliothèque Rust et fournit à la fois rlib et dylib variantes.	rust_library, Modules de bibliothèque.
rust_ffi	Génère une bibliothèque C Rust utilisable par Cc modules, et fournit des variantes statiques et partagées.	rust_ffi, Page "Modules de bibliothèque"
rust_proc_macro	Génère une bibliothèque Rust proc-macro. (Ils sont semblables aux plug-ins de compilation.)	rust_proc_macro, Page "Modules des bibliothèques"
rust_test	Génère un binaire de test Rust qui utilise le à un harnais de test Rust standard.	Page Modules de test
rust_fuzz	Génère un binaire à fuzz Rust en exploitant libfuzzer	Exemple de module rust_fuzz
rust_protobuf	Génère la source et produit un objet Rust qui fournit une interface à un protobuf particulier.	Pages Modules Protobufs et Générateurs sources
rust_bindgen	Génère la source et produit un Bibliothèque Rust contenant des liaisons Rust vers des bibliothèques C.	Modules de liaisons Bindgen et Générateurs sources

Propriétés communes importantes

Ces propriétés sont communes à toutes les applications Android Rust Modules. Tout établissement supplémentaire (unique) associé à un individu Les modules Rust sont répertoriés sur la page de ce module.

nom

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

tige

stem (facultatif) permet de contrôler directement le nom du fichier de sortie (sauf l'extension de fichier et d'autres suffixes). Par exemple, un rust_library_rlib dont la valeur racine est libfoo génère un fichier libfoo.rlib. Si vous ne fournissent pas de valeur pour la propriété stem, le nom de fichier de sortie adopte nom du module par défaut.

Utilisez la fonction stem lorsque vous ne pouvez pas définir le nom du module sur la sortie souhaitée nom de fichier. Par exemple, le rust_library de la caisse log est nommé liblog_rust parce qu'un liblog cc_library existe déjà. Dans ce cas, l'utilisation de la propriété stem garantit que la 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 (généralement main.rs ou lib.rs). rustc gère la résolution et la découverte de tous les autres fichiers sources nécessaires à la compilation, et il s'agit énumérées dans le fichier deps généré.

Conseil: srcs gère également les source générée référencée par la macro include!. Ces les sources doivent être fournies par un autre module (tel que genrule ou rust_protobuf, etc.). Pour inclure la source, ajoutez le nom le module qui fournit la source générée à srcs ; ajoutez-lui le préfixe :. (Comme dans ":libmyproto", par exemple. Le fichier source principal doit être la première entrée du tableau lorsque vous utilisez cette de Google Cloud.

Si possible, évitez cette utilisation pour le code de plate-forme. voir Générateurs de sources pour en savoir plus.

nom_crate

crate_name définit les métadonnées du nom de la caisse via le --crate_name rustc. . Pour les modules qui produisent des bibliothèques, cela doit correspondre à la nom de caisse 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 il 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 (telles que rust_library rust_ffi, rust_bindgen, rust_protobuf et rust_proc_macro). Ces modules appliquent les exigences de rustc sur la relation entre crate_name et le nom de fichier de sortie. Pour en savoir plus, consultez les Modules de la 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 d'analyse lint sont définies et utilisées pour valider la source du module. Valeurs possibles pour ce lint sont les suivants:

• default est l'ensemble d'analyses lint par défaut, en fonction de l'emplacement du module.
• android est l'ensemble d'analyse 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 lint

clippy_lints

L'outil clippy linter est également utilisé sont exécutés par défaut pour tous les types de modules, à l'exception des générateurs de sources. Quelques ensembles de lint sont définies et sont utilisées pour valider la source du module. Voici quelques exemples :

• default ensemble d'analyses lint par défaut en fonction de l'emplacement du module
• android est l'ensemble d'analyse 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 lint

Conseil: Vous pouvez définir linters sur `none` pendant le développement pour éviter les erreurs linter. Toutefois, pendant l'examen, vous devrez peut-être justifier l'existence de modules validés lint moins stricts

édition

edition définit l'édition Rust à utiliser pour la compilation de ce code. Cette méthode est semblable aux versions std pour C et C++. Valeurs valides sont 2015 et 2018 (par défaut).

indicateurs

flags contient une liste d'indicateurs de chaîne à 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 source. Celles-ci sont transmises par l'indicateur rustc -C linker-args. clang est utilisé comme l'interface de l'éditeur de liens, en appelant lld pour l'association proprement dite.

Remarque :Comme ils sont transmis à Clang, traitez-les comme des indicateurs Clang. Préfixe options à transmettre à lld avec le préfixe Clang -Wl habituel.

fonctionnalités

features est une liste de chaînes de fonctionnalités qui doivent être activées lors de la compilation. Ce paramètre est transmis à rustc par --cfg 'feature="foo"'. La plupart des caractéristiques se cumulent, Dans de nombreux cas, il s'agit donc de l'ensemble des fonctionnalités requises par toutes les dépendances modules. Toutefois, lorsque des fonctionnalités s'excluent les unes des autres, définir des modules supplémentaires dans tous les fichiers de compilation qui fournissent des fonctionnalités en conflit.

Remarque :Contrairement à un build Cargo, il n'existe pas d'ensemble de fonctionnalités "par défaut" est activé de manière implicite. La valeur par défaut est un mot clé spécial cargo. sauf si gère explicitement une fonctionnalité appelée "default", en définissant "default" ne contient pas impact.

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 compilation définit automatiquement certains indicateurs cfg, en particulier énumérés ci-dessous:

• Le cfg android_dylib est défini pour les modules créés en tant que dylib.

• Le cfg android_vndk est défini pour les modules qui utilisent le VNDK. C'est semblable à __ANDROID_VNDK__ pour C++.

strip

strip détermine si le fichier de sortie est supprimé et de quelle manière (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 d'autres valeurs dans le 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 à la fois des 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. Utiliser en tant que votre méthode préférée pour déclarer des dépendances, car elle permet au système de compilation sélectionnez l'association de votre choix. (voir En cas d'association à des bibliothèques Rust ci-dessous)
rlibs	Liste des modules rust_library qui doivent être associés de manière statique en tant que rlibs. (Utilisez-le avec précaution, reportez-vous aux En cas d'association à des bibliothèques Rust, ci-dessous.)
shared_libs	Liste des modules cc_library qui doivent être dynamiques associées en tant que bibliothèques partagées.
static_libs	Liste des modules cc_library qui doivent être statiques liés en tant que bibliothèques statiques.
whole_static_libs	Liste des modules cc_library qui doivent être statiques liés en tant que bibliothèques statiques et inclus dans leur intégralité dans la bibliothèque obtenue. Pour rust_ffi_static variante, whole_static_libraries sera incluse dans le de l'archive statique de bibliothèque générée. Pour rust_library_rlib variante, Les bibliothèques whole_static_libraries seront regroupées dans le rlib obtenu bibliothèque. Remarque:Cela vous empêche de redéclarer les dépendances les dépendances pour cette bibliothèque. Cependant, dans certains cas, cela peut entraîner une surcharge si la bibliothèque statique est dupliquée dans une dépendance arborescence. Les bibliothèques statiques entièrement incluses dans "rlibs" le seront aussi dans "dylibs" dépendants, ce qui fournit une autre source potentielle de surcharge.

En cas d'association à des bibliothèques Rust, en tant que utilisez la propriété rustlibs plutôt que rlibs ou dylibs, sauf si vous avez une raison spécifique de le faire. Cela permet au build pour sélectionner la bonne liaison en fonction des besoins du module racine, et cela réduit le risque qu'une arborescence de dépendances contienne à la fois rlib et dylib versions d'une bibliothèque (ce qui entraînera l'échec de la compilation).

Fonctionnalités de compilation non compatibles et limitées

Rust de Soong offre une compatibilité limitée pour vendor et vendor_ramdisk images et instantanés. Toutefois, staticlibs, cdylibs, rlibs et binaries sont acceptés. Pour les cibles de compilation d'images de fournisseurs, La propriété cfg android_vndk est définie. Vous pouvez l'utiliser dans le code les différences entre les cibles du système et celles du fournisseur. rust_proc_macros ne sont pas capturées dans les instantanés des fournisseurs ; s'ils en dépendent, assurez-vous d'un contrôle de version approprié.

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

Compilations incrémentielles

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

Avertissement: Il n'est pas garanti que cela produise des binaires identiques à ceux générés par les buildbots. Adresses des fonctions ou des données contenues dans le champ peuvent être différents. Pour s'assurer que les artefacts générés sont à 100% identiques à celles créées par l'infrastructure EngProd, ne définissez pas cette valeur.