davideandClaude Sonnet 5
6eb84a18e5
Nuovi docs/emulatore.md e docs/testing.md; CLAUDE.md e README.md aggiornati con i riferimenti. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
122 lines
4.4 KiB
Markdown
122 lines
4.4 KiB
Markdown
# Emulatore Android — installazione e uso (Ubuntu)
|
|
|
|
Guida per chi sviluppa BitePlan su Ubuntu (nativo o WSL2) e deve installare ed usare
|
|
l'emulatore Android in locale. Per i requisiti generali del progetto vedi [README](../README.md);
|
|
per la build via Docker vedi [CLAUDE.md](../CLAUDE.md).
|
|
|
|
## 1. Prerequisiti
|
|
|
|
- **KVM** per l'accelerazione hardware: senza, l'emulatore è troppo lento per essere usabile.
|
|
|
|
```bash
|
|
ls /dev/kvm # deve esistere
|
|
groups | grep kvm # il tuo utente deve essere nel gruppo kvm
|
|
```
|
|
|
|
Se il gruppo manca:
|
|
|
|
```bash
|
|
sudo usermod -aG kvm $USER
|
|
# poi rilogin (o riavvia la sessione) perché il gruppo sia effettivo
|
|
```
|
|
|
|
Su **WSL2** serve un kernel con KVM abilitato (le versioni recenti lo hanno di serie).
|
|
La finestra dell'emulatore compare tramite WSLg.
|
|
|
|
- **Java 17+**: `sudo apt install openjdk-21-jdk`
|
|
- Strumenti di base: `git curl unzip`, e ~15 GB di spazio libero per SDK + system image.
|
|
|
|
## 2. Installare Android SDK command-line tools
|
|
|
|
```bash
|
|
mkdir -p ~/android-sdk/cmdline-tools
|
|
cd ~/android-sdk/cmdline-tools
|
|
curl -O https://dl.google.com/android/repository/commandlinetools-linux-11076708_latest.zip
|
|
unzip commandlinetools-linux-11076708_latest.zip && mv cmdline-tools latest
|
|
rm commandlinetools-linux-11076708_latest.zip
|
|
|
|
cat >> ~/.bashrc <<'EOF'
|
|
export ANDROID_HOME="$HOME/android-sdk"
|
|
export PATH="$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/platform-tools:$ANDROID_HOME/emulator:$PATH"
|
|
EOF
|
|
source ~/.bashrc
|
|
```
|
|
|
|
## 3. Installare i pacchetti SDK e accettare le licenze
|
|
|
|
```bash
|
|
sdkmanager "platform-tools" "emulator" \
|
|
"platforms;android-34" "build-tools;34.0.0" \
|
|
"system-images;android-34;google_apis;x86_64"
|
|
yes | sdkmanager --licenses
|
|
```
|
|
|
|
## 4. Creare l'AVD `biteplan`
|
|
|
|
Il progetto usa un AVD dedicato (Pixel 6, Android 14, `google_apis`/x86_64) — non riusare
|
|
AVD di altri progetti.
|
|
|
|
```bash
|
|
echo "no" | avdmanager create avd -n biteplan \
|
|
-k "system-images;android-34;google_apis;x86_64" -d pixel_6
|
|
```
|
|
|
|
Verifica che tutto sia a posto con `flutter doctor` (la voce "Android toolchain" deve
|
|
risultare ✓).
|
|
|
|
## 5. Avviare l'emulatore
|
|
|
|
```bash
|
|
emulator -avd biteplan &
|
|
```
|
|
|
|
Il primo boot richiede 1-2 minuti; quelli successivi sono più veloci grazie allo snapshot
|
|
automatico dello stato. Per lo sviluppo con hot reload, dalla root del progetto:
|
|
|
|
```bash
|
|
flutter run # r = hot reload, R = hot restart
|
|
```
|
|
|
|
### Opzioni utili
|
|
|
|
```bash
|
|
emulator -list-avds # elenca gli AVD disponibili
|
|
emulator -avd biteplan -no-snapshot-load # forza un cold boot (ignora lo stato salvato)
|
|
emulator -avd biteplan -wipe-data # resetta l'AVD allo stato di fabbrica
|
|
```
|
|
|
|
## 6. Comandi `adb` quotidiani
|
|
|
|
```bash
|
|
adb devices # emulatori/device collegati
|
|
adb wait-for-device # attende che l'emulatore sia raggiungibile
|
|
adb shell 'while [ "$(getprop sys.boot_completed)" != "1" ]; do sleep 1; done' # attende il boot completo
|
|
|
|
adb install -r dist/biteplan-debug.apk # installa/reinstalla un APK già buildato
|
|
adb shell monkey -p com.davide.biteplan -c android.intent.category.LAUNCHER 1 # avvia l'app
|
|
|
|
adb logcat --pid=$(adb shell pidof -s com.davide.biteplan) # log in tempo reale dell'app
|
|
|
|
adb uninstall com.davide.biteplan # disinstalla
|
|
```
|
|
|
|
> Per lo sviluppo iterativo usa `flutter run` (hot reload); la sequenza `adb install` sopra
|
|
> serve a validare l'APK esatto che verrà distribuito, senza passare da `flutter run`.
|
|
|
|
## 7. Chiudere l'emulatore
|
|
|
|
```bash
|
|
adb -s emulator-5554 emu kill # spegnimento pulito (salva lo snapshot)
|
|
# oppure chiudi la finestra dell'emulatore
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
| Sintomo | Causa probabile | Soluzione |
|
|
|---|---|---|
|
|
| `emulator: ERROR: x86_64 emulation currently requires hardware acceleration` | KVM non accessibile | Verifica `/dev/kvm` e l'appartenenza al gruppo `kvm` (§1) |
|
|
| Emulatore lentissimo, UI a scatti | KVM non attivo, o system image ARM su host x86_64 | Usa una system image `x86_64` come da §3, verifica KVM |
|
|
| Boot bloccato su logo Android per minuti | Cold boot dopo `-wipe-data`, oppure macchina sotto carico | Attendi, è normale al primo avvio; se persiste prova `-no-snapshot-load` |
|
|
| Finestra emulatore non compare su WSL2 | WSLg non attivo o kernel senza supporto grafico | Aggiorna WSL (`wsl --update`), verifica `echo $DISPLAY` |
|
|
| `adb: no devices/emulators found` | Emulatore non ancora avviato o non ancora bootato | `adb wait-for-device`, poi ricontrolla con `adb devices` |
|