llimphi/android/LEEME.md

Llimphi · Android

Port nativo de Llimphi a Android. Una NativeActivity en C que delega al android_main que android-activity exporta desde la .so Rust, idéntico patrón que un binario main() en desktop.

Estado

crate	estado
clear-screen-android	✓ APK firmado v2, instalable en Android 7+
resto de apps Llimphi	pendientes — el patrón es reusar android_main

Tesis

El motor Llimphi (HAL + raster + layout + text + ui) no se toca. Lo único nuevo por target Android es:

1. Entry-point #[no_mangle] android_main(app: AndroidApp) en vez de fn main().
2. Construir el EventLoop con with_android_app(app) para que winit reciba Resumed / Suspended / InputAvailable desde el Looper de Android.
3. Recrear la Surface en cada Resumed: Android invalida la NativeWindow al pasar a background. El App::state: Option<State> ya está estructurado para eso.

Las apps existentes que viven sobre Llimphi compilan sin cambios — lo que se reescribe es el lifecycle wrapper, no la lógica de render ni los widgets.

Cómo construir

Una sola pasada — el script wrapper:

./scripts/build-android.sh clear-screen-android

Resultado: target/x/release/android/clear-screen-android.apk firmado con APK Signature Scheme v2, listo para adb install -r <apk>.

Setup inicial (una vez por máquina)

# Targets Rust
rustup target add aarch64-linux-android x86_64-linux-android

# Wrapper de build de Rust mobile (binario `x`)
cargo install xbuild

# NDK r27c (~640 MB descomprimido, ~1.5 GB)
curl -L -o /tmp/ndk.zip \
  https://dl.google.com/android/repository/android-ndk-r27c-linux.zip
unzip /tmp/ndk.zip -d $HOME/
export ANDROID_NDK_HOME=$HOME/android-ndk-r27c

# SDK (sólo build-tools + platform-tools, no se necesita la plataforma
# completa porque el APK se genera con aapt2 + apksigner del SDK).
# En Artix viene del paquete `android-sdk-build-tools`.

El script build-android.sh genera automáticamente un PEM RSA2048 self-signed en ~/.local/share/llimphi-android/debug.pem la primera vez que corre. Para firma de release usar un PEM propio y exportarlo en LLIMPHI_PEM.

Estructura del APK generado

clear-screen-android.apk
├── AndroidManifest.xml          ← xbuild genera; NativeActivity
└── lib/arm64-v8a/
    └── libclear_screen_android.so  ← 7.5 MB sin strip, ~2 MB stripped

Sin assets, sin recursos, sin Java/Kotlin. Todo el "código" de la app es la .so Rust. El bootstrap Java de NativeActivity lo provee el framework Android.

Apps por portar (orden de menor a mayor fricción)

Las apps que menos se modifican al portar son las que ya tienen poca interacción con teclado/mouse y mucho rendering:

1. mirada-image-viewer-llimphi — visor de imágenes, gestos = ok
2. nahual-text-viewer-llimphi — sólo scroll + zoom
3. nahual-image-viewer-llimphi — idem
4. pluma-md-reader — visor markdown, mismo patrón que la web
5. chasqui-explorer-llimphi — listas y tarjetas, taps obvios
6. shuma-shell-llimphi — teclado virtual, ya casi no usa shortcuts
7. mirada-app-llimphi — el compositor; touch desktop = problema UX

Las apps con paleta de comandos (nada, pluma-app full) son las últimas porque su UX core (Ctrl+Shift+P, multi-pane splitter, file picker) necesita ser repensada para touch.

Próximos hitos

• Tier 1.5: hello-world con vello rasterizando un texto + figura (smoke test del stack raster completo en Android).
• Tier 2: portar mirada-image-viewer-llimphi — primer APK funcional con UI real.
• Tier 3: input handling proper (touch events, soft keyboard, back button), theming responsivo (dpi/density).
• Tier 4: distribución (Play Store internal track, F-Droid build reproducible).