pgr/docs/templates/001-RUST_CARGO_TOOLING.md

Templates d'outillage Rust/Cargo

Rôle et sélection

Ces trois fichiers fournissent une baseline de configuration issue des conventions réellement utilisées dans KSP et Games. Ils s'appliquent à un projet Rust/Cargo qui choisit ce profil d'outillage ; ils ne créent pas une dépendance vers PGR après copie.

• rustfmt.toml — formatage canonique, avec notamment largeur 160 et édition 2024 dans l'exemple ;
• clippy.toml — paramètres de lints (seuils, exceptions de tests, identifiants courts) issus du noyau partagé des deux projets ;
• .cargo/config.toml — emplacements des artefacts Cargo hors de la racine source.

Les niveaux deny, allow, warn et forbid des lints Rust/Clippy appartiennent au Cargo.toml du workspace, selon 510-RUST_CARGO.md. clippy.toml règle des paramètres de lints, pas leur niveau. Les deux modèles Cargo et l'héritage [lints] workspace = true sont documentés dans 002-CARGO_MANIFESTS.md.

Copier et adapter

Copier ces fichiers aux chemins suivants dans le projet destinataire :

rustfmt.toml
clippy.toml
.cargo/config.toml

Adapter le header # file: de chacun à son nouveau chemin relatif. Comme il s'agit de nouveaux fichiers locaux, leur révision interne commence à 1 si le projet suit cette convention. Vérifier les choix avant de les utiliser :

1. rustfmt.toml : aligner edition sur l'édition déclarée dans le manifeste du projet. La largeur et les autres options constituent la convention de départ de KSP/Games et peuvent être ajustées pour le projet ;
2. clippy.toml : revoir les seuils au regard des types et API du projet ; adapter allowed-idents-below-min-chars à ses abréviations réelles. Les exceptions allow-*-in-tests sont une décision explicite du profil retenu ; elles ne relâchent pas les lints de production ;
3. .cargo/config.toml : remplacer project-name par un identifiant propre au projet pour éviter la collision de deux workspaces sous ../builds/. Depuis une configuration placée dans <racine>/.cargo/, Cargo résout ici les chemins relatifs par rapport à <racine>/ : la sortie se trouve donc sous le dossier frère <parent>/builds/<projet>/target/ ;
4. conserver les deux entrées target-dir et build-dir lorsque cette politique est choisie. Elles ciblent volontairement le même dossier, même si Cargo utilise actuellement target-dir comme valeur par défaut de build-dir ;
5. ajouter séparément les flags de cible, chemins particuliers ou ajustements Clippy nécessaires à un projet. Les flags Web présents dans Games ne sont pas un défaut de tous les projets Rust.

Le chemin de sortie sous builds/ est externe au dépôt source ; il ne doit pas être inclus dans les archives du projet. Si l'environnement impose un autre emplacement, ajuster la configuration du projet au lieu de copier un chemin machine depuis KSP ou Games.

Dans un projet existant, ces fichiers sont des références de comparaison. rustfmt.toml, clippy.toml ou .cargo/config.toml déjà présents MUST être comparés avant remplacement ; une différence locale peut rester KEEP-LOCAL, devenir un OVERRIDE explicite ou rester DEFER conformément à ../rules/230-ADOPTION.md. L’adoption n’exige pas une copie byte-for-byte des templates PGR.

Validation dans un projet Rust

Après adaptation, les contrôles utiles dépendent du code et des manifests effectivement présents :

cargo fmt --all -- --check
cargo clippy --workspace --all-targets --all-features -- -D warnings

Vérifier l'emplacement effectif des artefacts sur un build ou un check pertinent. La validation de PGR lui-même peut vérifier la syntaxe TOML et la cohérence des chemins sans demander de compiler un workspace Rust absent de son dépôt.