SEQUA-Engine/docs/adr/0004-multiplateforme-et-verification-locale.md

ADR 0004 : Multiplateforme par conception, vérification locale

• Statut : Acceptée, modifiée par ADR 0010 (voir « Modifications »)
• Date : 2026-11-06
• Décideur : Ange-Marie MAURIN - A2M Systèmes
• Références : docs/SEQUA_Engine_resume_complet_v2.md §10.3, §2 (principe 11), §15 (décision 15), §10.1, §9, §16

Contexte

Le document fait du multiplateforme une exigence d'architecture : Windows, Linux et macOS sont compilés et testés dès le premier jour (§2, principe 11) ; l'architecture ne suppose jamais une seule plateforme ; la compilation et les tests passent sur les trois plateformes à chaque modification (§10.3, décision 15). Le déterminisme doit être tenu entre plateformes (§10.1, §16), le rejeu devant être identique bit à bit côté simulation (§9).

Contrainte réelle : l'instance Gitea du projet n'a pas de runners CI, par choix du mainteneur. Aucune exécution n'est donc déclenchée automatiquement à chaque modification. La vérification est locale : presets CMake (CMakePresets.json) et scripts scripts/build.ps1, scripts/build.sh, scripts/check.ps1. Sous Windows, MSVC, CMake et Ninja sont fournis par Visual Studio 2022 ; build.ps1 les ajoute au PATH via vswhere et le DevShell.

État vérifié : les presets couvrent Windows (debug, release, ASan, prototypes), Linux (GCC debug, Clang ASan+UBSan) et macOS (Clang debug) ; check.ps1 enchaîne les presets Windows debug, release et ASan, puis, si studio/package.json existe, npm ci et npm run check. Seuls les presets Windows ont été exécutés à ce jour : les presets Linux et macOS existent mais n'ont pas encore tourné. Le test de rejeu déterministe comparé entre plateformes dépend donc d'exécutions manuelles.

L'écart avec §10.3 et la décision 15 est assumé : il n'y a pas d'intégration continue sur les trois plateformes à chaque modification.

Options envisagées

1. Runners Gitea auto-hébergés (Windows, Linux, macOS) : conforme au document et automatique, mais infrastructure et maintenance à porter, alors que l'instance n'a pas de runners et que le mainteneur n'en veut pas.
2. CI hébergée externe : automatise les trois plateformes, mais ajoute une dépendance et des coûts externes, et sort la vérification de l'instance Gitea.
3. Vérification locale scriptée : aucune infrastructure, configurations reproductibles par presets, mais aucune exécution garantie ni couverture automatique de Linux et macOS.

Décision

Le multiplateforme reste une exigence de conception : aucun code ne suppose Windows, les presets existent pour les trois plateformes et les règles de déterminisme de §10.1 s'appliquent. La vérification est locale et scriptée : check.ps1 avant commit sous Windows (debug, release, ASan, puis Studio), build.sh sous Linux et macOS. Aucun runner CI n'est installé sur l'instance Gitea ; l'écart avec l'intégration continue prévue est consigné ici et assumé, pas oublié.

Mesures de compensation retenues : check.ps1 avant chaque commit ; exécutions manuelles périodiques des presets Linux et macOS via build.sh ; empreintes de rejeu de référence dans les tests dès que la simulation existe, pour comparer les exécutions entre plateformes.

Conséquences

Positives

• Aucune infrastructure CI à maintenir ; tout fonctionne hors ligne avec les outils locaux.
• Les presets rendent les configurations explicites et reproductibles, avec avertissements traités comme erreurs et tests activés par défaut.
• Une commande Windows vérifie debug, release et ASan, puis Studio (typecheck, tests, build).
• Le multiplateforme reste dans l'architecture : presets, règles de déterminisme, pas de code spécifique non isolé.

Négatives et coûts

• Aucune vérification automatique à chaque modification : une régression Linux ou macOS peut rester invisible longtemps.
• Les presets Linux et macOS n'ont pas encore été exécutés ; leur validité est théorique à ce jour.
• Le rejeu comparé entre plateformes (§10.1, §16) dépend d'exécutions manuelles et de la discipline du mainteneur ; aucun journal automatique des résultats.
• check.ps1 est spécifique à Windows et ne couvre ni les prototypes ni les presets Linux/macOS ; il n'existe pas d'équivalent complet sous Linux/macOS, Studio inclus.
• clang-tidy reste optionnel (SEQUA_CLANG_TIDY vaut OFF par défaut et n'est activé par aucun preset) : l'analyse statique prévue §10.1 n'est pas systématique.
• L'absence de CI déplace la responsabilité sur la revue humaine : rien ne garantit que la vérification est lancée avant un commit.

Questions ouvertes

• Fréquence et déclencheur du passage manuel sur Linux et macOS (avant chaque phase, chaque version, chaque modification de code portable) : non fixés.
• Empreintes de rejeu de référence : une première existe (test « empreinte de référence multiplateforme » dans core/tests/sim/test_replay.cpp, comparaison bit à bit, sans tolérance). Reste à décider si les empreintes doivent sortir du code vers des fichiers versionnés quand les scènes de test se multiplieront.
• Conditions de réintroduction de runners Gitea ou d'une CI externe (contributions externes, fin de la phase 0, besoin de traçabilité) : non décidées.
• Versions minimales GCC et Clang réellement supportées et outillage macOS attendu : non fixés au-delà de CMake ≥ 3.25.
• Sanitizers sous macOS et équivalent complet de check.ps1 (Studio inclus) : non outillés.
• Publication des résultats de vérification (journal daté dans le dépôt ou simple rapport local) : non décidé.

Modifications

2026-11-07 : ADR 0010 (build unifié)

• check.ps1 lance build-all.ps1 -Type all au lieu de build.ps1 sur chaque preset : la vérification avant commit couvre aussi Godot hébergé (types debug et release), l'interface de Studio et le remplissage de bin/<plateforme>/<type>/.
• Conséquence « check.ps1 est spécifique à Windows et ne couvre ni les prototypes ni les presets Linux/macOS » : toujours vraie, mais Godot hébergé fait désormais partie de la vérification sous Windows.
• Le reste de la décision (aucun runner, vérification locale scriptée, compensations) est inchangé.