emulador-android

Android: telefone ou emulador

Notas do projeto

Cada projeto nomeia seu emulador e aplicativo em .claude/android-emulator.md: o nome do AVD, o ID do aplicativo (e o do laboratório de UI, se houver) e os scripts de execução próprios do projeto. Leia-o primeiro. Sem ele, execute $ANDROID_HOME/emulator/emulator -list-avds e escolha o AVD com o nome do projeto; se não houver nenhum, pergunte ao proprietário e depois escreva as notas.

Ferramentas: sdk="${ANDROID_HOME:-$HOME/Library/Android/sdk}", adb="$sdk/platform-tools/adb". O Gradle precisa de um JDK: JAVA_HOME, senão o openjdk@21 do Homebrew (/opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home), senão o que vem com o Android Studio (/Applications/Android Studio.app/Contents/jbr/Contents/Home).

Qual dispositivo

O telefone do proprietário vem primeiro: adb devices lista-o como um serial que não começa com emulator- (depuração USB ou sem fio). Sem telefone, use o emulador do projeto. O proprietário pode pedir qualquer um; DEVICE=phone, DEVICE=emulator ou DEVICE=<serial> é como os scripts do projeto recebem essa escolha.

Sempre passe -s <serial> para o adb depois que um dispositivo for escolhido, pois outro pode conectar-se enquanto isso.

O emulador

Inicie-o apenas quando necessário e pare-o quando a tarefa estiver concluída, pois ele consome vários GB de memória. Use o scripts/emulator.sh do projeto quando existir; caso contrário, use o scripts/emulator.sh desta habilidade (no diretório base da habilidade, mostrado quando a habilidade é carregada), com AVD=<nome> das notas:

AVD=<nome> <dir da habilidade>/scripts/emulator.sh up       # sem interface; aguarda o Android inicializar, imprime o serial
AVD=<nome> <dir da habilidade>/scripts/emulator.sh status
AVD=<nome> <dir da habilidade>/scripts/emulator.sh down     # salva o snapshot de inicialização rápida, para que a próxima inicialização leve segundos

up desliga outros emuladores em execução primeiro, porque scripts e adb escolhem o primeiro (KEEP_OTHERS=1 mantém-nos); WINDOW=1 mostra sua janela, que o proprietário pode querer assistir. Execute up em segundo plano quando a compilação puder continuar enquanto isso. Se falhar, seu log estará em ${TMPDIR:-/tmp}/emulator-<avd>.log.

Compilar, instalar, abrir

Prefira os scripts do projeto (as notas os nomeiam: um script de execução, o script do laboratório de UI). Feito manualmente:

1. Compile apenas a ABI do dispositivo quando o projeto suportar (-Pabi=$(adb -s <serial> shell getprop ro.product.cpu.abi), ou ABI= para o script do projeto): as bibliotecas nativas tornam um APK completo lento para enviar via depuração sem fio.
2. adb -s <serial> install -r <apk>. -r mantém os dados do aplicativo; nunca desinstale ou execute pm clear no aplicativo do proprietário no telefone dele sem perguntar, pois contém dados reais.
3. Abra-o com adb -s <serial> shell am start --user current -S -f 0x10008000 -n <id do app>/<activity>: -S para o processo antigo para que a nova compilação execute, --user current é necessário em um telefone com Pasta Segura, e as flags (nova tarefa, limpando a antiga) impedem o Android de retomar uma tela anterior.

Observá-lo

• Captura de tela: adb -s <serial> exec-out screencap -p > <arquivo>.png, depois veja o arquivo. Tela preta no telefone significa que está bloqueado: peça ao proprietário para desbloqueá-lo.
• Toque e digite para um fluxo: adb -s <serial> shell input tap <x> <y>, input text <texto>, input keyevent KEYCODE_BACK; encontre coordenadas com adb -s <serial> exec-out uiautomator dump /dev/tty.
• Logs: adb -s <serial> logcat -d --pid=$(adb -s <serial> shell pidof <id do app>), ou -s <tag> para uma tag. Crash: adb -s <serial> logcat -d -b crash.
• Modo escuro e localidade para casos extremos: adb -s <serial> shell cmd uimode night yes|no; altere a localidade apenas no emulador, não no telefone do proprietário.

Informe ao proprietário de qual dispositivo cada resultado veio. Reverta qualquer alteração que você fez no telefone dele (modo escuro, por exemplo) ao finalizar e pare o emulador se você o iniciou.