# 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:

```bash
./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`