0.3.3-0-pre.3
This commit is contained in:
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/development/006-ANDROID_RUST_NATIVE_BUILD.md -->
|
||||
<!-- version: 2 -->
|
||||
<!-- version: 4 -->
|
||||
|
||||
# Build Rust Android natif
|
||||
|
||||
@@ -12,95 +12,95 @@ Le crate Rust `game-android-entrypoint` est un `cdylib`. Il est compilé avec ex
|
||||
- `reflex` ;
|
||||
- `snake`.
|
||||
|
||||
Le même nom de bibliothèque native peut être utilisé dans les deux APK puisque chaque module Android possède son propre répertoire `jniLibs`.
|
||||
Le même nom de bibliothèque native peut être utilisé dans les deux APK puisque chaque module Android possède son propre ensemble de `jniLibs` générés.
|
||||
|
||||
## SDL3 AAR et Prefab
|
||||
|
||||
L'AAR officiel SDL3 expose ses bibliothèques natives avec Prefab.
|
||||
|
||||
Pour `arm64-v8a`, la structure attendue est notamment :
|
||||
L'AAR officiel SDL3 expose ses bibliothèques natives avec Prefab. Pour chaque ABI, la logique Gradle commune cherche d'abord :
|
||||
|
||||
```text
|
||||
prefab/modules/SDL3/libs/android.arm64-v8a/libSDL3.so
|
||||
prefab/modules/SDL3/libs/android.<abi>/libSDL3.so
|
||||
```
|
||||
|
||||
Le script `scripts/build_android_rust.py` accepte cette structure officielle et conserve un fallback `jni/<abi>/libSDL3.so` pour compatibilité.
|
||||
Elle accepte aussi `jni/<abi>/libSDL3.so`, puis un fallback Prefab univoque. Pour chaque ABI elle :
|
||||
|
||||
Pour chaque application, le script :
|
||||
1. extrait `libSDL3.so` depuis l'AAR dans un répertoire temporaire de linkage ;
|
||||
2. stage `libSDL3.so` dans les `jniLibs` générés du variant ;
|
||||
3. lance `cargo ndk` avec exactement une feature jeu ;
|
||||
4. stage `libgame_android_entrypoint.so` dans le même arbre généré ;
|
||||
5. vérifie la présence des deux bibliothèques avant de rendre l'output au variant AGP.
|
||||
|
||||
1. extrait `libSDL3.so` depuis l'AAR ;
|
||||
2. l'utilise comme bibliothèque de liaison pour le build Rust ;
|
||||
3. copie `libSDL3.so` dans le `jniLibs/<abi>/` du module Android ;
|
||||
4. lance `cargo ndk` ;
|
||||
5. vérifie la présence de `libgame_android_entrypoint.so`.
|
||||
|
||||
Ainsi, `SDLActivity` dispose au runtime de `libSDL3.so` et de la bibliothèque Rust applicative.
|
||||
Les `jniLibs` générés sont déclarés à la Variant API via `variant.sources.jniLibs.addGeneratedSourceDirectory`. Gradle possède ainsi la dépendance entre le packaging Android et le build natif au lieu d'exiger une commande préalable séparée.
|
||||
|
||||
## Toolchain
|
||||
|
||||
SDL Android requiert actuellement SDK 35 ou ultérieur, NDK r28c ou ultérieur et API minimale 21. La baseline projet conserve `compileSdk 36`, `minSdk 21` et l'AAR SDL3 3.4.16.
|
||||
|
||||
Installer au minimum :
|
||||
|
||||
```bash
|
||||
rustup target add aarch64-linux-android
|
||||
cargo install cargo-ndk
|
||||
```
|
||||
|
||||
NDK de référence :
|
||||
Le contrat projet utilise :
|
||||
|
||||
```text
|
||||
r28c = 28.2.13676358
|
||||
AGP 9.4.0
|
||||
Gradle minimum 9.6.0
|
||||
JDK runtime >= 17, fourni par l'environnement
|
||||
Java source/target 17
|
||||
compileSdk 36
|
||||
minSdk 21
|
||||
NDK 28.2.13676358 / r28c
|
||||
SDL3 AAR 3.4.16
|
||||
cargo-ndk requis côté développeur
|
||||
```
|
||||
|
||||
Avec le SDK manager :
|
||||
`Android/settings.gradle` compare `GradleVersion.current()` au minimum projet `9.6.0`. Le projet n'épingle donc pas une distribution Gradle : un Gradle local plus récent est accepté tant qu'il satisfait le minimum.
|
||||
|
||||
```bash
|
||||
"${ANDROID_HOME}/cmdline-tools/latest/bin/sdkmanager" "ndk;28.2.13676358" "platform-tools"
|
||||
Le projet Android natif n'impose pas `JAVA_HOME`. Le JDK courant du shell/IDE exécute Gradle ; `java -version` et `gradle --version` sont relevés pendant les gates. Le niveau de bytecode/source Java de la glue reste explicitement `17`, indépendamment du JDK de build.
|
||||
|
||||
`cargo-ndk` détecte le NDK désigné pour le sous-processus via `ANDROID_NDK_HOME`. La tâche Gradle résout cette valeur à partir de `ANDROID_HOME` ou `ANDROID_SDK_ROOT` et de `androidNdkVersion`; aucun `ANDROID_NDK_HOME` global n'est requis.
|
||||
|
||||
## État 0.3.3-0-pre.3
|
||||
|
||||
La preuve mono-ABI de `0-pre.2` a validé que `assembleDebug` déclenche correctement le build Rust/SDL3 ARM64 sans orchestrateur Python préalable.
|
||||
|
||||
`0-pre.3` élargit ce même graphe à :
|
||||
|
||||
```text
|
||||
arm64-v8a
|
||||
x86_64
|
||||
```
|
||||
|
||||
`cargo-ndk` détecte un NDK installé par Android Studio ou utilise `ANDROID_NDK_HOME` lorsqu'il est défini.
|
||||
pour Snake et Reflex :
|
||||
|
||||
Pour utiliser directement `adb` :
|
||||
|
||||
```bash
|
||||
export PATH="${ANDROID_HOME}/platform-tools:${PATH}"
|
||||
```text
|
||||
:<game>:assembleDebug
|
||||
-> buildDebugSasedevRustArm64V8a
|
||||
-> buildDebugSasedevRustX8664
|
||||
-> deux sources jniLibs générées
|
||||
-> APK Debug universal
|
||||
```
|
||||
|
||||
Cet export peut être ajouté au fichier de configuration shell local de la machine.
|
||||
Chaque arbre ABI contient :
|
||||
|
||||
## Build
|
||||
```text
|
||||
build/generated/sasedevNative/debug/<abi>/jniLibs/<abi>/
|
||||
├── libSDL3.so
|
||||
└── libgame_android_entrypoint.so
|
||||
```
|
||||
|
||||
Depuis la racine :
|
||||
|
||||
```bash
|
||||
python3 scripts/build_android_rust.py reflex
|
||||
python3 scripts/build_android_rust.py snake
|
||||
java -version
|
||||
(cd Android && gradle --version)
|
||||
(cd Android && gradle :game-snake-poc:assembleDebug)
|
||||
(cd Android && gradle :game-reflex-poc:assembleDebug)
|
||||
```
|
||||
|
||||
Puis :
|
||||
Il ne faut pas appeler `scripts/build_android_rust.py` avant ces tâches. Le script Python historique reste temporairement versionné jusqu'à la fermeture complète du chemin natif en `0-pre.4`.
|
||||
|
||||
```bash
|
||||
cd Android
|
||||
gradle :game-reflex-poc:assembleDebug
|
||||
gradle :game-snake-poc:assembleDebug
|
||||
cd ..
|
||||
```
|
||||
|
||||
Les bibliothèques générées sous `Android/*/src/main/jniLibs/` sont des artefacts de build et ne sont pas versionnées.
|
||||
Les outputs natifs restent sous `Android/<module>/build/` et ne sont jamais versionnés.
|
||||
|
||||
## Smoke appareil
|
||||
|
||||
Préflight :
|
||||
Le premier APK universal doit être inspecté mécaniquement avant installation. Il doit contenir exactement les couples attendus pour `arm64-v8a` et `x86_64`, sans dépendre de `armeabi-v7a` ou `x86`.
|
||||
|
||||
```bash
|
||||
adb version
|
||||
adb devices
|
||||
```
|
||||
|
||||
Puis installation/lancement des APK si un appareil ou émulateur est disponible.
|
||||
|
||||
L'absence de `adb` ou d'appareil n'est pas un défaut fonctionnel du projet ; elle bloque uniquement le smoke appareil.
|
||||
Le plan prévoit ensuite un smoke sur l'AVD x86_64 disponible et sur l'appareil ARM64 réel. Ces smokes attestent le packaging multi-ABI ; ils ne changent pas le `minSdk`, qui reste un axe séparé et sera consolidé avec l'AAB/compatibilité dans `0-pre.4`.
|
||||
|
||||
## Exception FFI Rust
|
||||
|
||||
|
||||
Reference in New Issue
Block a user