142 lines
6.5 KiB
Markdown
142 lines
6.5 KiB
Markdown
<!-- file: Android/README.md -->
|
|
<!-- version: 14 -->
|
|
|
|
# Android
|
|
|
|
Le frontend Android natif est un projet Gradle multi-module séparé du workspace Cargo.
|
|
|
|
## Modules
|
|
|
|
```text
|
|
Android/
|
|
├── common/
|
|
├── game-reflex-poc/
|
|
└── game-snake-poc/
|
|
```
|
|
|
|
`common` est une Android Library Java qui fournit la frontière commune. Elle compile contre l'AAR SDL3 avec une dépendance `compileOnly` afin que son propre AAR reste valide.
|
|
|
|
Chaque module `game-*` est une application Android indépendante ; il dépend du module `common` et package directement l'AAR SDL3 dans son APK via `implementation`.
|
|
|
|
## Toolchain de référence
|
|
|
|
Le pipeline Android natif `0.3.3` utilise :
|
|
|
|
- Android Gradle Plugin `9.4.0` ;
|
|
- Gradle `>= 9.6.0`, résolu depuis l'environnement de développement ;
|
|
- JDK `>= 17` pour exécuter Gradle/AGP, sans `JAVA_HOME` imposé par le projet ;
|
|
- niveau Java source/target `17` pour la glue Android ;
|
|
- `compileSdk 36` ;
|
|
- `targetSdk 36` ;
|
|
- `minSdk 21` ;
|
|
- NDK `28.2.13676358` (`r28c`) ;
|
|
- SDL3 Android AAR `3.4.16`.
|
|
|
|
`Android/settings.gradle` déclare `minimumGradleVersion = 9.6.0` et refuse explicitement une version plus ancienne. Une version système plus récente reste autorisée et devient la version réellement utilisée pour le build.
|
|
|
|
Le JDK n'est pas épinglé par le projet Android natif. Le shell/IDE fournit le JDK courant ; la gate doit afficher `java -version` et `gradle --version` afin de consigner la combinaison réellement validée. Le POC Tauri Android historique conserve ses propres contraintes de JDK et de wrapper sous sa crate ; elles ne pilotent pas le chemin SDL3 natif.
|
|
|
|
## Commandes Gradle
|
|
|
|
Depuis la racine du dépôt :
|
|
|
|
```bash
|
|
java -version
|
|
(cd Android && gradle --version)
|
|
```
|
|
|
|
Le build natif normal utilise directement le Gradle de l'environnement :
|
|
|
|
```bash
|
|
(cd Android && gradle :game-snake-poc:assembleDebug)
|
|
(cd Android && gradle :game-reflex-poc:assembleDebug)
|
|
(cd Android && gradle :game-snake-poc:bundleRelease)
|
|
(cd Android && gradle :game-reflex-poc:bundleRelease)
|
|
```
|
|
|
|
`bundleRelease` ne requiert aucun secret dans le dépôt. Sans configuration de signature externe, il produit un AAB de validation non destiné à être téléversé tel quel sur un store.
|
|
|
|
Le dépôt ne versionne pas de Gradle Wrapper pour le projet Android natif. Le minimum est un contrat de compatibilité, pas une version exacte imposée à toutes les machines.
|
|
|
|
## SDL3 AAR
|
|
|
|
L'archive n'est pas vendorizée dans le dépôt. Placer :
|
|
|
|
```text
|
|
SDL3-3.4.16.aar
|
|
```
|
|
|
|
dans :
|
|
|
|
```text
|
|
Android/libs/
|
|
```
|
|
|
|
Le module `common` compile contre cet artefact et `SaseGameActivity` étend `org.libsdl.app.SDLActivity`.
|
|
|
|
## Rust Android natif
|
|
|
|
Le crate `game-android-entrypoint` produit `libgame_android_entrypoint.so`. `Android/gradle/sasedev-rust-android.gradle` transfère au graphe Gradle les responsabilités historiques d'extraction SDL3, de résolution NDK, de `cargo ndk`, de sélection de feature et de staging `jniLibs`.
|
|
|
|
À `0.3.3-0-pre.5`, Snake et Reflex utilisent tous deux le même pipeline commun avec les quatre ABI Android encore supportées par la toolchain retenue :
|
|
|
|
```text
|
|
arm64-v8a
|
|
armeabi-v7a
|
|
x86_64
|
|
x86
|
|
```
|
|
|
|
Les ABI historiques supprimées des toolchains Android modernes, notamment `armeabi`, `mips` et `mips64`, ne font pas partie du contrat. Le support maximal signifie ici toutes les ABI encore supportées simultanément par Android NDK/SDL3/Rust, et non des architectures abandonnées par l'écosystème.
|
|
|
|
Chaque variante Android déclenche, pour chaque ABI, un build `cargo ndk` avec exactement la feature du module concerné. La variante Debug utilise le profil Cargo `dev`; la variante Release ajoute `--release`. Les outputs sont placés sous :
|
|
|
|
```text
|
|
Android/<game>/build/generated/sasedevNative/<variant>/<abi>/jniLibs/<abi>/
|
|
├── libSDL3.so
|
|
└── libgame_android_entrypoint.so
|
|
```
|
|
|
|
AGP fusionne ces sources `jniLibs` générées dans l'APK Debug universal ou dans l'AAB Release. Aucune copie durable n'est faite dans `src/main/jniLibs`.
|
|
|
|
Le builder historique `scripts/build_android_rust.py` est supprimé en `0-pre.5` : toutes ses responsabilités durables (résolution NDK, extraction SDL3, linkage, sélection de feature, `cargo ndk`, profil release et staging) appartiennent désormais au graphe Gradle.
|
|
|
|
## Compatibilité 16 KB et minSdk
|
|
|
|
Le plancher Android reste `minSdk 21` / Android 5.0, qui correspond au minimum Android documenté par SDL3. Le niveau Rust transmis à `cargo ndk` reste également `21`.
|
|
|
|
La baseline utilise AGP `9.4.0` et NDK `r28c`. Pour la contrainte Google Play 16 KB sur appareils 64 bits, les bibliothèques `arm64-v8a` et `x86_64` doivent être compatibles 16 KB ; SDL3 étant fourni sous forme précompilée, `libSDL3.so` est vérifiée au même titre que `libgame_android_entrypoint.so`. La gate `0-pre.5` a confirmé des segments ELF `LOAD` alignés au moins à `2**14` pour ces deux ABI, puis un `zipalign -P 16` réussi sur les APK.
|
|
|
|
Les ABI 32 bits `armeabi-v7a` et `x86` restent supportées pour compatibilité matérielle ancienne ; leurs segments observés à `2**12` ne contredisent pas l'exigence Play 16 KB, qui s'applique aux appareils 64 bits. L'AAB doit néanmoins contenir les deux bibliothèques pour les quatre ABI sous `base/lib/<abi>/`. Si `bundletool` est disponible dans l'environnement de validation, `bundletool dump config --bundle=<aab>` peut compléter le contrôle du bundle.
|
|
|
|
La preuve runtime `0-pre.5` couvre également Android 5.0/API 21 sur x86 et Android 15/API 35 x86_64 avec `getconf PAGE_SIZE=16384` sur une image `ps16k`.
|
|
|
|
## Bridge JNI et tactile
|
|
|
|
`SaseGameActivity` vérifie au démarrage la version du bridge Java/JNI chargé depuis la bibliothèque Rust.
|
|
|
|
Les touch events standards restent traités via SDL3 et ne transitent pas par JNI.
|
|
|
|
## Packaging des assets
|
|
|
|
Chaque variante Android enregistre une tâche `stage<Variant>SasedevAssets` via la Variant API AGP.
|
|
|
|
La tâche générée compose les sources :
|
|
|
|
```text
|
|
assets/common/ -> assets/common/
|
|
assets/<game>/ -> assets/game/
|
|
```
|
|
|
|
dans un répertoire généré sous `Android/<module>/build/generated/sasedevAssets/<variant>/`.
|
|
|
|
Aucune ressource source n'est copiée durablement dans un module Android ou une crate Rust.
|
|
|
|
## Version NDK du projet
|
|
|
|
`Android/gradle.properties` définit `androidNdkVersion=28.2.13676358`.
|
|
|
|
Gradle utilise cette valeur comme `ndkVersion`. La tâche Rust Android résout la même version sous `${ANDROID_HOME}/ndk/` ou `${ANDROID_SDK_ROOT}/ndk/` et définit `ANDROID_NDK_HOME` uniquement pour le sous-processus `cargo ndk`.
|
|
|
|
Aucun `ANDROID_NDK_HOME` global n'est requis ; plusieurs NDK peuvent rester installés côte à côte.
|