108 lines
3.0 KiB
Markdown
108 lines
3.0 KiB
Markdown
<!-- file: docs/development/006-ANDROID_RUST_NATIVE_BUILD.md -->
|
|
<!-- version: 2 -->
|
|
|
|
# Build Rust Android natif
|
|
|
|
## Contrat SDL
|
|
|
|
`SDLActivity` charge `SDL3`, puis `game_android_entrypoint`, et invoque le symbole `SDL_main`.
|
|
|
|
Le crate Rust `game-android-entrypoint` est un `cdylib`. Il est compilé avec exactement une feature métier lors du packaging d'une application :
|
|
|
|
- `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`.
|
|
|
|
## SDL3 AAR et Prefab
|
|
|
|
L'AAR officiel SDL3 expose ses bibliothèques natives avec Prefab.
|
|
|
|
Pour `arm64-v8a`, la structure attendue est notamment :
|
|
|
|
```text
|
|
prefab/modules/SDL3/libs/android.arm64-v8a/libSDL3.so
|
|
```
|
|
|
|
Le script `scripts/build_android_rust.py` accepte cette structure officielle et conserve un fallback `jni/<abi>/libSDL3.so` pour compatibilité.
|
|
|
|
Pour chaque application, le script :
|
|
|
|
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.
|
|
|
|
## 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 :
|
|
|
|
```text
|
|
r28c = 28.2.13676358
|
|
```
|
|
|
|
Avec le SDK manager :
|
|
|
|
```bash
|
|
"${ANDROID_HOME}/cmdline-tools/latest/bin/sdkmanager" "ndk;28.2.13676358" "platform-tools"
|
|
```
|
|
|
|
`cargo-ndk` détecte un NDK installé par Android Studio ou utilise `ANDROID_NDK_HOME` lorsqu'il est défini.
|
|
|
|
Pour utiliser directement `adb` :
|
|
|
|
```bash
|
|
export PATH="${ANDROID_HOME}/platform-tools:${PATH}"
|
|
```
|
|
|
|
Cet export peut être ajouté au fichier de configuration shell local de la machine.
|
|
|
|
## Build
|
|
|
|
Depuis la racine :
|
|
|
|
```bash
|
|
python3 scripts/build_android_rust.py reflex
|
|
python3 scripts/build_android_rust.py snake
|
|
```
|
|
|
|
Puis :
|
|
|
|
```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.
|
|
|
|
## Smoke appareil
|
|
|
|
Préflight :
|
|
|
|
```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.
|
|
|
|
## Exception FFI Rust
|
|
|
|
Rust 2024 exige un attribut unsafe pour imposer un nom de symbole d'export. Le projet autorise donc exclusivement `#[unsafe(export_name = "SDL_main")]` dans `game-android-entrypoint`. Cette exception ne permet ni bloc `unsafe`, ni fonction `unsafe`, ni déréférencement des pointeurs `argc/argv`.
|