Sasedev/games
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

0.3.3-0-pre.1

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-09-21 08:39:57 +02:00
parent 76a955bd3d
commit f770f99a4a
9 changed files with 680 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
Android/README.md
View File

@@ -1,5 +1,5 @@
<!-- file: Android/README.md -->
<!-- version: 8 -->
<!-- version: 9 -->
# Android
@@ -20,7 +20,7 @@ Chaque module `game-*` est une application Android indépendante ; il dépend du
## Toolchain de référence
Pour la baseline `0.1.0-0-pre.9` :
La baseline stable `0.3.1` conserve :
- Android Gradle Plugin `9.4.0` ;
- Gradle `9.6.0` attendu par AGP 9.4 ;
@@ -28,9 +28,10 @@ Pour la baseline `0.1.0-0-pre.9` :
- `compileSdk 36` ;
- `targetSdk 36` ;
- `minSdk 21` ;
- NDK `28.2.13676358` (`r28c`) ;
- SDL3 Android AAR `3.4.16`.
Le NDK n'est pas encore utilisé directement dans ce delta. Le prochain jalon introduira la compilation Rust Android `cdylib` et figera la configuration NDK réellement nécessaire.
Le chemin historique compile déjà `game-android-entrypoint` via `cargo-ndk` et `scripts/build_android_rust.py`. `0.3.3` réactive ce produit Android natif afin de transférer cette orchestration dans Gradle, sans changer les responsabilités Rust/SDL3/Java/JNI.
## SDL3 AAR

4
Cargo.toml
View File

@@ -1,5 +1,5 @@
# file: Cargo.toml
# version: 80
# version: 81
[workspace]
resolver = "3"
@@ -21,7 +21,7 @@ members = [
]
[workspace.package]
version = "0.3.1"
version = "0.3.3-0-pre.1"
edition = "2024"
license = "MIT"
repository = "https://git.sasedev.com/Sasedev/games"

6
README.md
View File

@@ -1,5 +1,5 @@
<!-- file: README.md -->
<!-- version: 51 -->
<!-- version: 52 -->
# games.sasedev
@@ -27,9 +27,9 @@ Workspace expérimental puis productif pour des jeux multiplateformes principale
Version stable de référence : `0.3.1`.
Version suivante active planifiée : `0.3.3` (non démarrée). `0.3.2` reste différée.
Version active de développement : `0.3.3-0-pre.1`. `0.3.2` reste différée.
La stable `0.3.1` conserve Snake Tauri Android comme POC de référence validé sur AVD x86_64 et appareil ARM64 réel. La prochaine version active `0.3.3` est centrée sur Android SDL3 natif multi-ABI, le packaging Gradle/AAB et l’évaluation explicite de la compatibilité avec des versions Android plus anciennes.
La stable `0.3.1` conserve Snake Tauri Android comme POC de référence validé sur AVD x86_64 et appareil ARM64 réel. `0.3.3-0-pre.1` cadre maintenant la voie Android SDL3 native multi-ABI, le packaging Gradle/APK/AAB, le plancher Android soutenable et la compatibilité des bibliothèques natives avec les pages mémoire de 16 KB.
Les deux premiers jeux sont des POC structurels : `game-reflex-poc` et `game-snake-poc`. Ils existent d'abord pour valider les frontières du workspace, le moteur, les assets et le packaging multiplateforme.

204
deltas/0.3.3/0-pre.1.md Normal file
View File

@@ -0,0 +1,204 @@
<!-- file: deltas/0.3.3/0-pre.1.md -->
<!-- version: 1 -->
# Delta 0.3.3-0-pre.1
## Base
Base autoritaire : archive fournie `games-v0.3.1.zip`, téléchargée depuis le lien ZIP du tag Gitea `v0.3.1`.
La version workspace de la base est `0.3.1`. L'archive taggée ne contient pas `.git`; aucun état Git absent n'est inventé et aucune autre branche/version n'est utilisée comme source.
`0.3.2` reste différée conformément au prompt de reprise.
## Objet
Ouvrir `0.3.3` par son gate obligatoire `0-pre.1` : audit complet de la baseline et des règles, audit du pipeline Android SDL3 natif historique, recherche officielle actuelle, choix ABI/API, cadrage APK/AAB, contrainte pages mémoire 16 KB, sizing, risques, validations et plan vivant.
Cette tranche n'introduit volontairement aucune nouvelle tâche Gradle productive et ne modifie pas le comportement Android. La réécriture du chemin de build commence seulement en `0-pre.2`.
## Version
La version workspace passe de :
```text
0.3.1
```
à :
```text
0.3.3-0-pre.1
```
Les versions npm/Tauri et `versionName` Android ne sont pas synchronisées dans cette tranche de cadrage. Les produits concernés n'ont pas encore reçu de changement de packaging et `VER-TAURI-003`/`VER-TAURI-004` interdisent une synchronisation npm cérémonielle.
## Audit de l'archive
Avant modification, l'environnement de génération a obtenu :
```text
unzip -t : no errors
General Rust rule audit: clean
Rust export completeness audit: 0 candidate(s)
games.sasedev workspace audit: clean
Markdown table audit: clean (5 table(s), 222 file(s))
Distribution layout audit: clean (48 required path(s), 1 forbidden path(s) absent)
```
Le ZIP contient 378 fichiers, aucun lien symbolique, aucun fichier vide et aucun `.git`, `target/`, `node_modules/` ou `gen/android/` généré.
La sortie utilisateur initiale sur son arbre local est également propre pour les trois audits, avec 230 fichiers Markdown et un `cargo check --workspace` réussi. Elle montre ensuite un build Tauri Android Debug universal réussi pour ARM64 et x86_64. Le compte Markdown local supérieur au ZIP taggé est compatible avec un `gen/android/` Tauri déjà présent localement ; le ZIP fourni reste la source autoritaire et aucun fichier généré n'est ajouté au delta.
## Audit des règles
La revue demandée par `prompts/004-V0_3_3_START_PROMPT.md` confirme notamment :
- `0-pre.1` doit contenir le cadrage et le plan avant le développement lourd ;
- une prerelease non-fix synchronise la version workspace ;
- un nouveau chemin de build `0.3.x` ne doit pas être piloté par Python ;
- Gradle doit posséder l'artefact Android final et les outputs générés doivent rester hors sources versionnées ;
- toute modification Rust/Cargo déclenche fmt, audit, check workspace et Clippy strict ;
- les builds, tests et smokes finaux sont attestés côté utilisateur ;
- les tests workspace complets restent des gates rares et planifiées ;
- aucun historique `history/0.3.3/0-pre.1.md` n'est créé avant validation effective de cette tranche.
Aucune contradiction bloquante n'est trouvée entre le prompt, les règles et la baseline `v0.3.1`. L'audit documentaire relève toutefois un paragraphe obsolète dans `Android/README.md`, resté au vocabulaire `0.1.0-0-pre.9` et affirmant que le NDK n'était pas encore utilisé ; cette tranche le réaligne sur la réalité stable `0.3.1` sans changer le build.
## Pipeline Android hérité
La baseline configure :
```text
AGP 9.4.0
Gradle 9.6.0 attendu
JDK 17
compileSdk 36
targetSdk 36
minSdk 21
NDK 28.2.13676358 / r28c
SDL3 AAR 3.4.16
```
`scripts/build_android_rust.py` réalise aujourd'hui l'extraction/linkage SDL3 par ABI, la résolution NDK, `cargo ndk`, la sélection d'une unique feature jeu, le staging dans `src/main/jniLibs` et la vérification de `libgame_android_entrypoint.so`.
Ces responsabilités doivent être transposées dans la logique Gradle commune, avec outputs sous `build/generated/...`, avant suppression du script.
## Recherche et décisions 0-pre.1
Les sources officielles actuelles confirment :
- AGP 9.4.0 : Gradle 9.6.0, JDK 17 et NDK par défaut `28.2.13676358` ;
- SDL3 Android actuel : SDK 35+, NDK r28c+ et API minimale 21 ;
- SDL3 3.4.16 : release stable actuelle de la baseline ;
- Google Play : API 36+ requise depuis le 31 août 2026 pour nouvelles apps/mises à jour téléphone/tablette ;
- application native ciblant API 35+ : compatibilité pages mémoire 16 KB à assurer ; NDK r28+ produit l'alignement 16 KB par défaut ;
- AAB : format de distribution, dont le store dérive des APK optimisés, notamment par ABI.
Les choix retenus sont donc :
```text
minSdk candidat 21
ABI par défaut arm64-v8a + x86_64
armeabi-v7a différée
APK local universal multi-ABI
AAB distribution
splits ABI non par défaut
NDK natif r28c épinglé, distinct du NDK 30 observé dans le POC Tauri
```
Le détail, les sources et les risques sont consignés dans `docs/studies/025-V0_3_3_ANDROID_NATIVE_MULTI_ABI_AUDIT.md`.
## Plan créé
`docs/plans/003-V0_3_3_ANDROID_NATIVE_MULTI_ABI_PLAN.md` devient le plan actif avec le forecast révisé :
```text
0-pre.1 audit / règles / ABI-API / minSdk / APK-AAB / 16 KB / plan
0-pre.2 ownership Gradle/Cargo Snake sur arm64-v8a + wrapper Gradle
0-pre.3 arm64-v8a + x86_64 + APK universal + Reflex si factorisation naturelle
0-pre.4 AAB + minSdk/smokes + 16 KB + fermeture du script Python historique
2-beta.1 validation large + packaging final
3-rc.1 gel + reproductibilité + consolidation documentaire
0.3.3 promotion mécanique stable
```
Le scope reste compatible avec une seule version/session tant qu'aucune incompatibilité structurante de Gradle/cargo-ndk/SDL3 n'est découverte.
## Fichiers
Ajoutés :
```text
docs/plans/003-V0_3_3_ANDROID_NATIVE_MULTI_ABI_PLAN.md
docs/studies/025-V0_3_3_ANDROID_NATIVE_MULTI_ABI_AUDIT.md
deltas/0.3.3/0-pre.1.md
```
Modifiés :
```text
Android/README.md
Cargo.toml
README.md
docs/000-README.md
docs/plans/000-README.md
docs/studies/000-README.md
```
Aucun fichier Gradle, Rust source, règle normative, roadmap, changelog ou historique n'est modifié dans ce cadrage. `Android/README.md` reçoit uniquement la correction documentaire de baseline décrite ci-dessus.
## Validations exécutées dans l'environnement de génération
Après constitution de l'état livré, exécuter uniquement les audits statiques autorisés au générateur :
```bash
python3 scripts/audit_rust_workspace_rules.py
python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates Android Web deltas history
python3 scripts/audit_distribution_layout.py
```
Aucun build Cargo/Gradle, test ou smoke final n'est attribué au générateur.
## Validation utilisateur demandée
Le manifest workspace change de version ; la gate minimale est donc :
```bash
python3 scripts/audit_rust_workspace_rules.py
python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates Android Web deltas history
python3 scripts/audit_distribution_layout.py
cargo fmt --all
cargo fmt --all -- --check
cargo check --workspace
cargo clippy --workspace --all-targets --all-features -- -D warnings
```
Aucun test workspace complet n'est demandé : cette tranche ne change aucun code Rust, comportement, dépendance ou configuration Android productive.
La première gate du prompt `004` demande également l'inventaire frais qui conditionne `0-pre.2` :
```bash
rustc --version
cargo --version
cargo ndk --version
rustup target list --installed
java -version
printf 'JAVA_HOME=%s\nANDROID_HOME=%s\n' "$JAVA_HOME" "$ANDROID_HOME"
adb version
adb devices -l
emulator -list-avds
(cd Android && gradle --version)
printf 'configured NDK: '; sed -n 's/^androidNdkVersion=//p' Android/gradle.properties
ls -ld "$ANDROID_HOME/ndk/28.2.13676358"
test -f Android/libs/SDL3-3.4.16.aar && sha256sum Android/libs/SDL3-3.4.16.aar
```
La sortie déjà fournie confirme JDK 17 sélectionné via `JAVA_HOME`, les targets Tauri ARM64/x86_64 suffisamment opérationnelles pour produire un APK universal et un NDK 30 utilisé par Tauri. Elle ne remplace pas l'inventaire du pipeline Android natif ci-dessus.
## Suite après validation
Si la gate est propre, la tranche suivante crée `history/0.3.3/0-pre.1.md` avec les sorties réellement obtenues puis ouvre `0.3.3-0-pre.2`.
`0-pre.2` doit d'abord introduire le Gradle Wrapper et prouver sur Snake/ARM64 que `:game-snake-poc:assembleDebug` déclenche lui-même le build Rust/SDL3 sans `scripts/build_android_rust.py`. Une défaillance de la gate ou une erreur du cadrage produit d'abord `0-pre.1.fix.N`.

5
docs/000-README.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/000-README.md -->
<!-- version: 29 -->
<!-- version: 30 -->
# Documentation games.sasedev
@@ -16,7 +16,8 @@
- [`plans/000-README.md`](plans/000-README.md) — plans vivants des versions ; le plan actif porte notamment le découpage prévisionnel souple des prereleases.
- [`plans/001-V0_3_0_WEB_SNAKE_POC_PLAN.md`](plans/001-V0_3_0_WEB_SNAKE_POC_PLAN.md) — plan clôturé de `0.3.0`, premier POC Snake Web direct.
- [`plans/002-V0_3_1_TAURI_ANDROID_SNAKE_PLAN.md`](plans/002-V0_3_1_TAURI_ANDROID_SNAKE_PLAN.md) — plan actif de `0.3.1`, second host Snake Tauri Android.
- [`plans/002-V0_3_1_TAURI_ANDROID_SNAKE_PLAN.md`](plans/002-V0_3_1_TAURI_ANDROID_SNAKE_PLAN.md) — plan clôturé de `0.3.1`, second host Snake Tauri Android.
- [`plans/003-V0_3_3_ANDROID_NATIVE_MULTI_ABI_PLAN.md`](plans/003-V0_3_3_ANDROID_NATIVE_MULTI_ABI_PLAN.md) — plan actif de `0.3.3`, pipeline Android SDL3 natif Gradle/Cargo multi-ABI.
## Architecture

5
docs/plans/000-README.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/plans/000-README.md -->
<!-- version: 2 -->
<!-- version: 3 -->
# Plans de versions games.sasedev
@@ -12,4 +12,5 @@ Le `ROADMAP.md` reste la trajectoire macroscopique du projet ; les deltas décri
## Plans
- [`001-V0_3_0_WEB_SNAKE_POC_PLAN.md`](001-V0_3_0_WEB_SNAKE_POC_PLAN.md) — plan clôturé de `0.3.0`, baseline Snake et premier POC Web direct.
- [`002-V0_3_1_TAURI_ANDROID_SNAKE_PLAN.md`](002-V0_3_1_TAURI_ANDROID_SNAKE_PLAN.md) — plan actif de `0.3.1`, second host Snake Tauri Android.
- [`002-V0_3_1_TAURI_ANDROID_SNAKE_PLAN.md`](002-V0_3_1_TAURI_ANDROID_SNAKE_PLAN.md) — plan clôturé de `0.3.1`, second host Snake Tauri Android.
- [`003-V0_3_3_ANDROID_NATIVE_MULTI_ABI_PLAN.md`](003-V0_3_3_ANDROID_NATIVE_MULTI_ABI_PLAN.md) — plan actif de `0.3.3`, pipeline Android SDL3 natif Gradle/Cargo multi-ABI.

208
docs/plans/003-V0_3_3_ANDROID_NATIVE_MULTI_ABI_PLAN.md Normal file
View File

@@ -0,0 +1,208 @@
<!-- file: docs/plans/003-V0_3_3_ANDROID_NATIVE_MULTI_ABI_PLAN.md -->
<!-- version: 1 -->
# Plan 0.3.3 — Android SDL3 natif multi-ABI et packaging Gradle
## Statut
Plan actif créé pendant `0.3.3-0-pre.1` à partir de la stable taggée `v0.3.1`.
`0.3.2` reste volontairement différée. Aucun placeholder, POC Tauri Desktop ou changement cérémoniel n'est introduit pour cette version.
## Mission
`0.3.3` doit rendre le chemin Android SDL3 natif reproductible et possédé par Gradle/Cargo :
```text
Gradle -> Rust natif -> SDL3/JNI -> APK universal de test
Gradle -> Rust natif multi-ABI -> AAB de distribution
```
Le chemin productif Android ne doit dépendre ni de Tauri, ni de WebView, ni de WASM, ni d'un orchestrateur Python de build.
## Baseline et décisions retenues
La baseline `0.3.1` conserve :
- `game-android-entrypoint` comme `cdylib` commun ;
- exactement une feature jeu par application native ;
- Java comme glue Android ;
- `SaseGameActivity`/SDLActivity et un contrat JNI réduit ;
- assets canoniques hors modules Android et staging Gradle déjà basé sur la Variant API ;
- SDL3 AAR non vendorizé ;
- Snake Tauri Android uniquement comme POC de référence ARM64/x86_64.
Les décisions de cadrage `0-pre.1` sont :
```text
AGP 9.4.0
Gradle 9.6.0 à épingler par wrapper lors de l'implémentation
JDK 17
compileSdk 36
targetSdk 36
minSdk candidat 21
NDK 28.2.13676358 / r28c
SDL3 3.4.16
ABI par défaut arm64-v8a + x86_64
armeabi-v7a différée sans besoin produit mesuré
APK test universal multi-ABI
AAB artefact de distribution cible
splits ABI hors chemin par défaut
```
Le `minSdk 21` est fondé sur le plancher Android actuellement documenté par SDL3, pas sur la seule valeur historique du dépôt. Le `targetSdk 36` est maintenu pour la politique Google Play actuelle.
Le pipeline devra aussi vérifier la compatibilité 16 KB des bibliothèques natives finales. AGP 9.4 et NDK r28c fournissent le socle requis, mais le prébuild SDL3 doit être contrôlé dans l'APK/AAB produit.
## Ownership cible
La logique durable doit rester répartie ainsi :
- Cargo/Rust : moteur, gameplay et `game-android-entrypoint` ;
- `Android/common` : glue Java/JNI commune durable ;
- `Android/game-*` : identité et configuration applicative par jeu ;
- `Android/gradle/` : logique de build Android commune, y compris orchestration Rust native et staging des sorties générées ;
- `assets/` : sources d'assets canoniques ;
- `Android/<app>/build/generated/` : outputs jetables de packaging ;
- `scripts/build_android_rust.py` : mécanisme historique à retirer du chemin normal dès que la responsabilité Gradle est prouvée, puis fichier à supprimer seulement lorsque toutes ses responsabilités sont remplacées.
Aucune `.so` générée ne doit être écrite durablement dans `src/main/jniLibs/` par le nouveau chemin.
## Contrat de la logique Gradle native
La future logique commune doit couvrir au minimum :
1. résolution du NDK side-by-side exact déclaré dans `Android/gradle.properties` ;
2. validation de la présence de l'AAR SDL3 attendu ;
3. extraction par ABI de `libSDL3.so` depuis Prefab vers un répertoire de build ;
4. linkage Rust contre la SDL extraite ;
5. invocation de `cargo ndk` avec `CARGO_NDK_PLATFORM=21` ;
6. mapping strict de chaque module vers exactement une feature `snake` ou `reflex` ;
7. build des ABI demandées, `arm64-v8a` et `x86_64` par défaut ;
8. staging de `libSDL3.so` et `libgame_android_entrypoint.so` dans un répertoire `jniLibs` généré ;
9. branchement de ce répertoire à la variante Android avant packaging ;
10. inputs/outputs Gradle assez précis pour un rebuild incrémental ;
11. diagnostics explicites si outil, target, AAR, NDK ou output manque ;
12. absence de secret de signature dans le dépôt.
Le projet Android natif doit acquérir un Gradle Wrapper épinglé à la version compatible AGP afin que `CMD-051` devienne réellement reproductible sans dépendre d'un Gradle global.
## ABI et compatibilité OS
Le support CPU et le support de versions Android restent deux axes séparés.
`arm64-v8a` est la cible productive obligatoire. `x86_64` est la cible AVD obligatoire de la matrice de développement. Ces deux ABI doivent être présentes dans l'APK universal de validation et dans l'AAB tant qu'aucune décision ultérieure ne restreint la distribution.
`armeabi-v7a` n'est pas introduite par défaut : elle ne permet pas de descendre sous API 21 avec SDL3, agrandit la matrice et ne répond à aucun besoin utilisateur mesuré à ce stade.
Le plancher OS candidat est Android 5.0 / API 21. La version doit tenter un smoke sur API 21 si une image exploitable est raisonnablement disponible. À défaut, elle teste la plus ancienne API localement disponible et consigne explicitement la lacune ; elle ne transforme pas un smoke absent en validation fictive.
## Packaging attendu
L'APK Debug de test doit rester universal : un seul fichier installable contient toutes les ABI retenues. La validation inspecte les entrées `lib/<abi>/...` avant les smokes.
L'AAB est l'artefact de distribution. La validation doit vérifier au minimum :
- présence des bibliothèques natives des ABI retenues ;
- absence de secret/keystore embarqué ;
- configuration d'alignement compatible pages mémoire 16 KB ;
- possibilité d'inspecter le bundle avec les outils Android appropriés ;
- distinction documentée entre bundle de distribution et APK installable.
Les APK split ABI ne sont pas générés par défaut dans `0.3.3`.
## Validation par type de jalon
Pendant les tranches d'implémentation, les validations restent ciblées : audits statiques, gates Rust dès qu'un fichier Rust/Cargo change, puis tâche Gradle du module touché.
Les smokes de packaging deviennent plus larges seulement quand le jalon produit un artefact installable :
- APK universal : inspection ARM64/x86_64 + AVD x86_64 + appareil ARM64 ;
- compatibilité basse : AVD API 21 si raisonnablement disponible, sinon plus ancienne API disponible avec écart documenté ;
- AAB : inspection du bundle et des bibliothèques natives, y compris compatibilité 16 KB ;
- beta/RC : gate workspace large planifiée, rebuild reproductible et smokes finaux.
Les builds, tests et smokes finaux restent exécutés et attestés par l'utilisateur.
## Forecast révisé
### `0-pre.1` — cadrage Android natif
Audit complet de `v0.3.1`, règles, pipeline Python historique, Gradle/AGP/NDK/SDL3, ABI/API, minSdk, APK universal, AAB, pages 16 KB, risques, matrice de validation et plan vivant.
Aucune réécriture Gradle productive dans cette tranche.
### `0-pre.2` — ownership Gradle/Cargo sur Snake mono-ABI
Introduire le Gradle Wrapper compatible AGP 9.4 et la logique Gradle commune minimale. Faire de `:game-snake-poc:assembleDebug` le propriétaire du build Rust `arm64-v8a`, de l'extraction/linkage SDL3 et des `jniLibs` générés, sans appel préalable au script Python.
Le delta doit rester borné à une ABI pour valider l'ordre des tâches, les inputs/outputs, le mapping de feature et les diagnostics avant de multiplier les dimensions.
### `0-pre.3` — multi-ABI et APK universal
Étendre la logique commune à `arm64-v8a + x86_64`, produire un APK Debug universal Snake et vérifier mécaniquement les deux couples `libSDL3.so`/`libgame_android_entrypoint.so`.
Ajouter Reflex comme second consommateur dans cette tranche si, et seulement si, la factorisation commune réduit son activation à une configuration de module sans nouvelle architecture.
### `0-pre.4` — AAB, minSdk et fermeture du chemin historique
Ajouter/valider le chemin `bundleRelease` sans secret, inspecter le bundle et la compatibilité 16 KB, exécuter la stratégie de smoke du plancher Android et supprimer `scripts/build_android_rust.py` si toutes ses responsabilités ont effectivement migré.
Mettre à jour les documents Android/JNI/build durables pour décrire le nouveau chemin réel et ajuster l'audit de distribution si le script historique n'est plus un path requis.
### `2-beta.1` — validation large et packaging final
Exécuter la gate Rust/workspace large planifiée et les tâches Android finales pour Snake et Reflex réellement inclus. Reconstruire l'APK universal et l'AAB depuis un état nettoyé raisonnablement, puis revalider AVD x86_64, appareil ARM64, ABI packagées, 16 KB et compatibilité basse disponible.
Corriger uniquement par `2-beta.1.fix.N` si nécessaire ; ne pas ouvrir une beta cérémonielle supplémentaire si la matrice est propre.
### `3-rc.1` — gel et reproductibilité
Geler le scope, consolider `CHANGELOG.md`, documentation finale, historique beta, matrice RC et prompt de la prochaine version. Rejouer uniquement les gates de publication/reproductibilité prévues ; aucune nouvelle capacité.
### `0.3.3` — stable
Promotion mécanique de la RC validée. Aucun changement fonctionnel ou architectural.
## Sizing
Le scope reste raisonnable pour une seule version si les quatre prereleases conservent leurs frontières verticales. Les zones susceptibles de forcer un split de version sont uniquement une incompatibilité profonde de `cargo-ndk` avec AGP/Gradle, une SDL3 AAR non exploitable par Prefab comme prévu, ou une exigence produit nouvelle pour le 32 bits.
Un simple besoin de `.fix.N` après validation ne remet pas ce sizing en cause.
## Gate avant 0-pre.2
La validation utilisateur de `0-pre.1` doit inclure la gate Rust liée au changement de version workspace et l'inventaire frais suivant :
```bash
rustc --version
cargo --version
cargo ndk --version
rustup target list --installed
java -version
printf 'JAVA_HOME=%s\nANDROID_HOME=%s\n' "$JAVA_HOME" "$ANDROID_HOME"
adb version
adb devices -l
emulator -list-avds
(cd Android && gradle --version)
printf 'configured NDK: '; sed -n 's/^androidNdkVersion=//p' Android/gradle.properties
ls -ld "$ANDROID_HOME/ndk/28.2.13676358"
test -f Android/libs/SDL3-3.4.16.aar && sha256sum Android/libs/SDL3-3.4.16.aar
```
L'absence du Gradle global n'est pas destinée à devenir une dépendance durable : `0-pre.2` doit introduire le wrapper. En revanche, l'inventaire demandé par le prompt `004` doit relever l'état actuel avant cette transition.
## Critères d'entrée en RC
`0.3.3` peut entrer en RC lorsque :
- un build Gradle Android natif n'exige plus `scripts/build_android_rust.py` ;
- Snake produit un APK universal ARM64/x86_64 par un seul chemin Gradle ;
- l'AAB de distribution est constructible sans secret embarqué ;
- les bibliothèques natives finales sont vérifiées pour la contrainte 16 KB ;
- le minSdk soutenu et la preuve de smoke disponible sont documentés sans surpromesse ;
- l'appareil ARM64 réel et l'AVD x86_64 passent le smoke prévu ;
- Reflex est soit branché naturellement au pipeline commun, soit explicitement borné selon les résultats de factorisation ;
- le script Python historique est supprimé s'il n'a plus aucune responsabilité durable ;
- les documents Android, build, JNI et validation décrivent le chemin réellement livré ;
- les gates workspace/beta applicables sont propres.

6
docs/studies/000-README.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/studies/000-README.md -->
<!-- version: 10 -->
<!-- version: 11 -->
# Études
@@ -61,3 +61,7 @@ Ces documents étudient les POC à réaliser ; ils ne lancent encore aucune impl
## Étude de cadrage 0.3.1
- [`024-V0_3_1_TAURI_ANDROID_SNAKE_AUDIT.md`](024-V0_3_1_TAURI_ANDROID_SNAKE_AUDIT.md) — audit de la baseline `0.3.0`, réutilisation Web/WASM, référence Tauri existante, environnement Android et sizing du second host Snake.
## Étude de cadrage 0.3.3
- [`025-V0_3_3_ANDROID_NATIVE_MULTI_ABI_AUDIT.md`](025-V0_3_3_ANDROID_NATIVE_MULTI_ABI_AUDIT.md) — audit de la baseline `0.3.1`, toolchain Android native actuelle, choix ABI/API, packaging APK/AAB et contraintes 16 KB.

248
docs/studies/025-V0_3_3_ANDROID_NATIVE_MULTI_ABI_AUDIT.md Normal file
View File

@@ -0,0 +1,248 @@
<!-- file: docs/studies/025-V0_3_3_ANDROID_NATIVE_MULTI_ABI_AUDIT.md -->
<!-- version: 1 -->
# Audit Android SDL3 natif multi-ABI pour 0.3.3
## Statut et objet
Cette étude cadre `0.3.3-0-pre.1` à partir de l'archive taggée `v0.3.1`. Elle reste non normative : les décisions opérationnelles retenues pour la version sont portées par `docs/plans/003-V0_3_3_ANDROID_NATIVE_MULTI_ABI_PLAN.md` et deviendront des responsabilités durables dans les documents Android concernés au moment où l'implémentation les rendra réelles.
L'objectif est de remplacer le chemin historique :
```text
scripts/build_android_rust.py -> cargo ndk -> src/main/jniLibs -> Gradle
```
par un chemin possédé par le build Android :
```text
Gradle -> tâches Rust/cargo-ndk -> jniLibs générés -> APK/AAB
```
sans réintroduire un orchestrateur ad hoc externe.
## Base auditée
L'archive fournie correspond à la stable `0.3.1` et déclare `workspace.package.version = "0.3.1"`.
Avant modification, les contrôles statiques exécutables dans l'environnement de génération donnent :
```text
unzip -t : no errors
General Rust rule audit: clean
Rust export completeness audit: 0 candidate(s)
games.sasedev workspace audit: clean
Markdown table audit: clean (5 table(s), 222 file(s))
Distribution layout audit: clean (48 required path(s), 1 forbidden path(s) absent)
```
L'archive contient 378 fichiers, aucun lien symbolique, aucun fichier vide, aucun `.git`, `target/`, `node_modules/` ou `gen/android/` généré.
La sortie locale fournie par l'utilisateur annonce 230 fichiers Markdown avant son build Tauri, contre 222 dans le ZIP taggé. La baseline taggée reste autoritaire. L'écart est compatible avec la présence locale d'un arbre Tauri `gen/android/` déjà initialisé, que l'archive de tag n'embarque pas ; il ne constitue pas à lui seul une divergence de source tant que les audits restent propres.
## Règles et frontières vérifiées
La revue de `RULES.md` et des règles référencées par le prompt confirme notamment :
- `0-pre.1` doit rester une tranche de cadrage, sizing, recherche, risques, validations et planification ;
- une prerelease non-fix synchronise la version technique même si elle est principalement documentaire ;
- les builds, tests et smokes finaux restent côté utilisateur ; le générateur peut exécuter les audits statiques ;
- tout chemin de build nouveau ou réactivé en `0.3.x` ne doit pas être piloté par Python ;
- les commandes Android ciblées sont préférées et tout changement de répertoire doit rester dans un sous-shell ;
- les sorties générées ne doivent pas devenir des sources versionnées ;
- les tests workspace complets restent des gates rares et planifiées ;
- l'historique d'une tranche n'est ajouté que par la tranche suivante après validation réelle.
Aucune règle ne justifie de réécrire Gradle dans `0-pre.1`. La tranche doit donc produire les décisions et le plan, puis laisser l'implémentation à `0-pre.2` et suivantes.
## Pipeline Android natif hérité
Le projet Android est un multi-module Gradle séparé du workspace Cargo avec :
```text
Android/common
Android/game-reflex-poc
Android/game-snake-poc
```
La configuration source déclare actuellement :
```text
AGP 9.4.0
compileSdk 36
targetSdk 36
minSdk 21
JDK source 17
NDK 28.2.13676358 (r28c)
SDL3 AAR SDL3-3.4.16.aar
```
Le ZIP ne vend pas l'AAR SDL3, conformément au contrat `Android/libs/README.md`. Il vérifie donc le nom/version attendu, pas les octets de l'AAR présent sur une machine de développement.
L'audit relève aussi que `Android/README.md` portait encore un paragraphe de toolchain daté de `0.1.0-0-pre.9`, contradictoire avec le pipeline natif réellement stabilisé ensuite. `0-pre.1` corrige cette description sans toucher au build.
Le projet Android natif ne contient pas encore de Gradle Wrapper. `Android/README.md` attend Gradle 9.6.0 globalement. Comme la reproductibilité devient une responsabilité centrale de `0.3.3`, l'introduction d'un wrapper Gradle épinglé doit être traitée avec le premier vrai changement de pipeline, pas dans le cadrage documentaire.
## Responsabilités du script historique
`scripts/build_android_rust.py` remplit aujourd'hui plusieurs responsabilités qu'il faut transposer explicitement au build Gradle plutôt que supprimer aveuglément :
1. associer un module Android à exactement une feature jeu Rust ;
2. lire le nom de l'AAR SDL3 et la version NDK depuis `Android/gradle.properties` ;
3. extraire `libSDL3.so` de l'AAR Prefab pour chaque ABI afin de fournir la bibliothèque de liaison à Rust ;
4. rendre `libSDL3.so` disponible au runtime Android ;
5. résoudre le NDK side-by-side exact et transmettre son chemin uniquement au sous-processus natif ;
6. fixer le niveau Android de `cargo-ndk` à 21 ;
7. invoquer `cargo ndk` avec exactement une feature `reflex` ou `snake` ;
8. vérifier que `libgame_android_entrypoint.so` a réellement été produit.
Le script écrit actuellement des bibliothèques sous `Android/<app>/src/main/jniLibs/<abi>/`. Ces fichiers sont ignorés mais restent des artefacts de build dans un répertoire source. La cible `0.3.3` doit plutôt enregistrer un répertoire de `jniLibs` généré sous `Android/<app>/build/generated/...`, sur le même principe que le staging d'assets déjà piloté par la Variant API AGP.
## Toolchain actuelle vérifiée
La documentation Android officielle d'AGP 9.4.0, mise à jour le 18 septembre 2026, fixe :
```text
Gradle minimum/default 9.6.0
JDK minimum/default 17
Build Tools default 36.0.0
NDK default 28.2.13676358
API maximale AGP 37
```
Source officielle : <https://developer.android.com/build/releases/agp-9-4-0-release-notes>.
La baseline `AGP 9.4.0 + Gradle 9.6.0 + JDK 17 + NDK r28c` est donc cohérente et ne nécessite pas de montée de version pour lancer `0.3.3`.
La sortie utilisateur fournie pour le POC Tauri Android montre un NDK local `30.0.14904198`. Cette valeur appartient au pipeline Tauri généré et ne remplace pas la version NDK native explicitement épinglée à `28.2.13676358` dans `Android/gradle.properties`.
## SDL3 et plancher Android
La documentation SDL Android actuelle demande :
```text
Android SDK 35 ou ultérieur
Android NDK r28c ou ultérieur
API minimale 21 / Android 5.0
```
Source officielle : <https://github.com/libsdl-org/SDL/blob/main/docs/README-android.md>.
SDL `3.4.16` est la release stable publiée le 2 septembre 2026 et l'asset Android officiel `SDL3-devel-3.4.16-android.zip` est disponible dans la release.
Source officielle : <https://github.com/libsdl-org/SDL/releases/tag/release-3.4.16>.
Le `minSdk 21` historique n'est donc pas retenu par simple inertie : il correspond au plancher actuel documenté de SDL3. Descendre sous API 21 exigerait de changer une dépendance structurante ou de maintenir un fork, ce qui est hors scope. Le candidat `minSdk` de `0.3.3` est donc `21`, sous réserve d'un smoke sur API 21 ou sur la plus ancienne image raisonnablement disponible avec écart explicitement documenté.
## Target SDK et distribution
Google Play exige depuis le 31 août 2026 qu'une nouvelle application ou mise à jour téléphone/tablette cible Android 16, API 36, ou plus récent.
Source officielle : <https://developer.android.com/google/play/requirements/target-sdk>.
Le `targetSdk 36` de la baseline reste donc approprié pour `0.3.3`. Il ne doit pas être confondu avec `minSdk 21` : l'un décrit la cible comportementale/politique de distribution, l'autre le plancher d'installation.
## Pages mémoire 16 KB
Le projet package du code natif Rust et SDL3. Les appareils Android 15+ peuvent utiliser des pages mémoire de 16 KB et Google Play impose la compatibilité 16 KB aux applications ciblant API 35+ sur appareils 64 bits.
La documentation Android précise qu'AGP 8.5.1+ et NDK r28+ fournissent le chemin standard de packaging/alignement 16 KB, NDK r28 alignant les bibliothèques produites sur 16 KB par défaut. Les bibliothèques précompilées restent néanmoins à vérifier, donc `libSDL3.so` doit faire partie du contrôle de l'artefact final.
Source officielle : <https://developer.android.com/guide/practices/page-sizes>.
Cette contrainte renforce le maintien de NDK r28c. La validation AAB doit inclure un contrôle d'alignement/compatibilité des bibliothèques natives, et un smoke 16 KB peut être ajouté si une image d'émulateur adéquate est raisonnablement disponible.
## ABI retenues pour le chemin par défaut
Les deux ABI de base proposées sont :
```text
arm64-v8a
x86_64
```
Raisons :
- `arm64-v8a` couvre la cible productive minimale sur appareil Android moderne ;
- `x86_64` conserve un chemin AVD local rapide et déjà exercé par le POC Tauri ;
- les deux sont des ABI 64 bits et répondent au besoin de supporter les architectures 64 bits pour une application native ;
- Rust fournit les targets `aarch64-linux-android` et `x86_64-linux-android` ;
- le build Tauri fourni par l'utilisateur vient de réussir pour ces deux targets, ce qui confirme au moins la présence récente de ces cibles Rust sur sa machine.
`armeabi-v7a` est différée par défaut. Le 32 bits n'abaisse pas le plancher OS puisque SDL3 reste à API 21, augmente la matrice de build/test et la taille d'un APK universal, et aucun besoin produit concret n'est actuellement démontré. Elle pourra être rouverte à partir de données d'appareils/utilisateurs ou d'un besoin de distribution mesuré.
`x86` 32 bits n'est pas retenue dans la matrice de base.
## APK universal, AAB et splits
Pour les tests locaux, la cible est un APK Debug universal contenant les deux ABI retenues :
```text
lib/arm64-v8a/libSDL3.so
lib/arm64-v8a/libgame_android_entrypoint.so
lib/x86_64/libSDL3.so
lib/x86_64/libgame_android_entrypoint.so
```
Aucun split ABI Gradle ne doit être activé par défaut pour cet artefact : un seul APK doit pouvoir être installé sur l'appareil ARM64 et sur l'AVD x86_64.
Pour la distribution, la cible est un AAB. Le format App Bundle laisse au store la génération des APK optimisés par configuration, notamment par ABI ; un AAB n'est pas lui-même un APK installable.
Source officielle : <https://developer.android.com/guide/app-bundle>.
Les APK split ABI restent une option de diagnostic/distribution directe future, pas un artefact par défaut de `0.3.3`.
## Architecture Gradle/Cargo recommandée
La solution retenue pour l'implémentation est une logique Gradle commune sous `Android/gradle/`, consommée par les applications natives. Elle doit :
- déclarer les ABI retenues dans une propriété/configuration centrale explicite ;
- enregistrer des tâches par variante et, si nécessaire, par ABI ;
- déclarer des inputs/outputs Gradle afin de préserver un rebuild incrémental raisonnable ;
- extraire la bibliothèque SDL3 native de l'AAR vers un répertoire de build pour le linkage Rust sans modifier l'AAR source ;
- invoquer `cargo ndk` avec le NDK r28c configuré et `CARGO_NDK_PLATFORM=21` ;
- sélectionner exactement une feature jeu selon le module consommateur ;
- écrire les bibliothèques natives dans un répertoire `build/generated/...` ;
- enregistrer ce répertoire comme `jniLibs` généré de la variante ;
- vérifier explicitement les deux `.so` attendues par ABI avant packaging ;
- échouer avec un diagnostic déterministe si AAR, NDK, cargo-ndk, target Rust ou output manque.
Cette logique n'est pas un nouveau script externe : elle fait partie du build Android qui possède l'artefact final.
## Snake et Reflex
Snake reste le jeu-sonde initial parce que le prompt le demande et que le POC Tauri a déjà prouvé ARM64 + x86_64 pour ce jeu.
Reflex ne doit pas provoquer une seconde architecture. Une fois la factorisation Gradle commune prouvée avec Snake, Reflex peut devenir le second consommateur dans la même version si l'opération se limite essentiellement au mapping `module -> feature`. Si des besoins spécifiques apparaissent, ils doivent être évalués avant d'élargir le scope.
## Risques identifiés
Les principaux risques à fermer pendant les tranches d'implémentation sont :
- absence de Gradle Wrapper dans le projet Android natif ;
- AAR SDL3 absent du ZIP par conception et donc à inventorier sur la machine de validation ;
- `cargo-ndk` présent mais version non encore relevée dans la sortie fraîche fournie ;
- extraction Prefab SDL3 différente de l'hypothèse historique ;
- dépendances Gradle mal ordonnées entre build Rust et merge/package JNI ;
- cache Gradle incorrect si les inputs Rust/assets/toolchain sont sous-déclarés ;
- production accidentelle de deux features jeu dans le même `cdylib` ;
- compatibilité 16 KB d'une bibliothèque précompilée SDL3 non vérifiée dans l'artefact final ;
- confusion entre NDK 30 du POC Tauri et NDK r28c du pipeline Android natif ;
- impossibilité pratique de créer un AVD API 21 récent, auquel cas l'écart de smoke doit rester explicite.
## Inventaire environnement encore à relever côté utilisateur
La sortie locale fournie confirme déjà :
- `JAVA_HOME=/usr/lib/jvm/temurin-17-jdk-amd64` pour le build présenté ;
- un build Tauri Debug universal réussi pour `aarch64` et `x86_64` ;
- un NDK Tauri local `30.0.14904198` ;
- un `cargo check --workspace` propre sur la stable `0.3.1`.
L'historique validé de `0.3.1` indique Rust/Cargo `1.94.1`, les targets Android ARM64/x86_64, ADB `37.0.1`, un appareil ARM64 réel et plusieurs AVD. Ces valeurs sont utiles comme transmission, mais ne remplacent pas l'inventaire frais demandé par le prompt `004`.
Avant d'ouvrir l'implémentation `0-pre.2`, la gate utilisateur doit donc relever explicitement `rustc`, `cargo`, `cargo ndk`, les targets Rust, Java, `JAVA_HOME`, `ANDROID_HOME`, ADB, appareils, AVD, Gradle natif, NDK r28c installé et AAR SDL3 local.
## Conclusion de cadrage
Le scope tient dans `0.3.3` si chaque tranche reste centrée sur un résultat vertical : ownership Gradle mono-ABI, puis multi-ABI/universal, puis AAB/compatibilité et consolidation. Aucun besoin découvert n'impose aujourd'hui de créer une version supplémentaire avant de commencer l'implémentation.