6.1 KiB
Modèles de manifests Cargo workspace et crate membre
Rôle des deux fichiers
Le manifest racine est celui d'un workspace virtuel à une unité de release ; le manifest membre montre une crate bibliothèque ordinaire. Les deux fichiers forment un exemple TOML syntaxiquement valide. Après copie dans un nouveau projet, il faut aussi fournir le code source de la crate avant de demander à Cargo de la compiler. Le dépôt PGR ne devient pas lui-même un workspace Cargo.
Ces modèles prolongent les trois configurations de 001-RUST_CARGO_TOOLING.md. Le propriétaire des choix normatifs reste 510-RUST_CARGO.md. Les chemins project-core-lib, le nom du package et la version 0.1.0 sont des valeurs d'exemple à remplacer : cette version ne reflète pas VERSION de PGR et ne définit pas la version d'un autre projet.
Adopter le manifest racine
Copier templates/rust-cargo/Cargo.toml vers Cargo.toml du projet, corriger son header # file: et commencer sa propre révision de fichier à 1. Adapter members aux répertoires qui existent effectivement, puis choisir la version canonique de l'unité de release. Lorsque toutes les crates partagent une seule release, aligner [workspace.package].version sur le VERSION de ce projet ; plusieurs unités de release indépendantes ne doivent pas hériter d'une version fictive commune.
L'édition 2024 et resolver = "3" sont cohérents avec l'exemple rustfmt.toml. Pour un workspace virtuel, fixer explicitement le resolver souhaité ; adapter ensemble l'édition, Rustfmt et la toolchain compatible si le projet prend d'autres valeurs. publish = false est un défaut prudent pour cet exemple ; définir la politique de publication réelle avant de publier une crate.
license, repository et authors ne sont volontairement pas renseignés avec des identités fictives. Si ces métadonnées ont une valeur vraie et commune, les déclarer dans [workspace.package] et les hériter explicitement dans chaque crate concernée, par exemple license.workspace = true seulement après avoir déclaré license à la racine. Ne pas imposer un auteur, une licence ou une URL propres à KSP/Games.
Le bloc [workspace.dependencies] est vide tant qu'aucune dépendance concrète ne sert plusieurs crates. Déclarer à la racine seulement les contraintes et features réellement communes ; les features propres à un membre sont activées sur sa dépendance locale. Cargo ajoute les features demandées au membre à celles déjà sélectionnées au workspace ; éviter d'activer globalement une feature de test ou de plateforme par facilité. Les dépendances de test appartiennent à [dev-dependencies] du membre qui les utilise.
Les trois lints Rust et les 18 niveaux Clippy reprennent la politique partagée observée dans KSP et Games. Les allow retiennent leurs choix de style explicite, notamment needless_return malgré implicit_return = "deny", et évitent qu'un lint de suggestion réécrive systématiquement ce style. Réviser leur pertinence pour le projet avant adoption. Les seuils et réglages supplémentaires appartiennent au clippy.toml distinct : ce fichier ne définit aucun niveau de lint.
Adopter le manifest membre
Copier le membre vers crates/<nom>/Cargo.toml, adapter name, son chemin dans members et le header # file:. version.workspace = true, edition.workspace = true et publish.workspace = true rendent visibles les héritages choisis ; ajouter séparément license.workspace = true, repository.workspace = true ou authors.workspace = true si les valeurs existent à la racine et concernent cette crate. [lints] workspace = true est requis pour reprendre les niveaux du workspace : leur présence à la racine ne suffit pas à les appliquer automatiquement aux membres.
Le bloc [dependencies] vide se remplit selon les besoins de la crate. Pour une dépendance déjà déclarée sous [workspace.dependencies], utiliser localement nom = { workspace = true }, avec features = [...] au besoin. Pour une dépendance strictement locale, choisir sa contrainte directement dans ce membre ; aucune liste tierce arbitraire n'est copiée par ce modèle.
Une application binaire peut reprendre les mêmes héritages après adaptation du nom, du layout et de sa cible src/main.rs ; ne pas fabriquer un deuxième manifest quasi identique. Une crate à version ou politique de publication réellement indépendante doit déclarer ses valeurs locales et ne plus hériter ces champs par automatisme.
Exception locale de lints
Une frontière FFI peut avoir besoin de unsafe_code = "allow" dans une crate particulière, comme l'entrée Android observée dans Games. Cette exception demande justification, portée étroite et validation du code unsafe concerné. Cargo ne permet pas de combiner workspace = true avec des définitions de lints locaux dans le même manifest membre : retirer l'héritage [lints] pour cette crate et déclarer localement [lints.rust] ainsi que [lints.clippy], en recopiant les niveaux partagés réellement conservés puis en ajustant seulement l'exception motivée. Les autres membres continuent d'hériter des lints racine.
Vérification dans le projet destinataire
Après avoir ajouté le code source nécessaire, vérifier d'abord la résolution des manifests et les héritages, puis les contrôles réellement applicables :
cargo metadata --format-version 1 --no-deps
cargo fmt --all -- --check
cargo check --workspace
cargo clippy --workspace --all-targets --all-features -- -D warnings
Vérifier séparément le cas d'une crate à lints locaux lorsque le projet comporte réellement une exception. Cargo.lock et les artefacts créés par ces commandes suivent la politique du projet et la configuration Cargo de 001-RUST_CARGO_TOOLING.md.