mice/ARM_APPIMAGE_PLAN.md

Piano di distribuzione ARM con AppImage

Questo repository ora e pronto per essere portato dentro un bundle AppImage senza dipendere dalla directory corrente e senza scrivere nel filesystem montato in sola lettura dell'AppImage.

Stato attuale

• Le risorse di runtime vengono risolte a partire dal root del progetto tramite MICE_PROJECT_ROOT.
• I dati persistenti (scores.txt, user_profiles.json) vengono scritti in una directory utente persistente:
  • MICE_DATA_DIR, se impostata.
  • altrimenti ${XDG_DATA_HOME}/mice.
  • fallback: ~/.local/share/mice.
• E presente uno scaffold di packaging in packaging/.

Strategia consigliata

1. Costruire l'AppImage su una macchina aarch64 reale o in una chroot/container ARM.
2. Creare dentro AppDir un ambiente Python copiato localmente con python -m venv --copies.
3. Installare le dipendenze Python da requirements.txt dentro quel Python locale.
4. Copiare il gioco e gli asset in AppDir/usr/share/mice.
5. Bundlare le librerie native richieste da SDL2 e dai wheel Python dentro AppDir/usr/lib.
6. Usare AppRun per esportare LD_LIBRARY_PATH, MICE_PROJECT_ROOT e MICE_DATA_DIR prima del lancio di rats.py.
7. Generare il file finale con appimagetool.

Perche costruire nativamente su ARM

• Un AppImage deve contenere binari della stessa architettura del target.
• PySDL2, numpy e Pillow portano con se librerie native o dipendenze native.
• Il cross-build da x86_64 a aarch64 e possibile, ma aumenta molto il rischio di incompatibilita su glibc, libSDL2 e wheel Python.

Comando di build

Da una macchina Linux aarch64 con python3, rsync, ldd, ldconfig e appimagetool disponibili:

./packaging/build_appimage_aarch64.sh

Output previsto:

• dist/AppDir
• dist/Mice-aarch64.AppImage

Dipendenze host richieste al builder ARM

Serve un sistema di build ARM con almeno:

• python3
• python3-venv
• rsync
• glibc userland standard
• appimagetool
• librerie di sviluppo/runtime installate sul builder, in particolare:
  • libSDL2
  • libSDL2_ttf

Test minimi da fare sul target ARM

1. Avvio del gioco da shell.
2. Caricamento font e immagini.
3. Riproduzione audio WAV.
4. Salvataggio punteggi in ~/.local/share/mice/scores.txt.
5. Creazione e lettura profili in ~/.local/share/mice/user_profiles.json.
6. Cambio livello da assets/Rat/level.dat.

Rischi residui

• La relocazione di un venv copiato dentro AppImage e pratica, ma va verificata sul target reale.
• Se il target ARM ha un userland molto vecchio, conviene costruire l'AppImage su una distro ARM con glibc piu vecchia del target.
• Se emergono problemi di relocazione del Python del venv, il passo successivo corretto e passare a un Python relocatable tipo python-build-standalone mantenendo invariato il launcher.

File introdotti

• runtime_paths.py
• packaging/appimage/AppRun
• packaging/appimage/mice.desktop
• packaging/build_appimage_aarch64.sh