Android: 휴대폰 또는 에뮬레이터

프로젝트 노트

각 프로젝트는 .claude/android-emulator.md 파일에 에뮬레이터와 앱 정보를 기록합니다: AVD 이름, 앱 ID(UI 랩 앱이 있다면 그것도), 그리고 프로젝트 자체 실행 스크립트. 이 파일을 먼저 읽으세요. 없으면 $ANDROID_HOME/emulator/emulator -list-avds를 실행하여 프로젝트 이름의 AVD를 선택하고, 없으면 소유자에게 물어본 후 노트를 작성하세요.

도구: sdk="${ANDROID_HOME:-$HOME/Library/Android/sdk}", adb="$sdk/platform-tools/adb". Gradle은 JDK가 필요합니다: JAVA_HOME, 없으면 Homebrew의 openjdk@21 (/opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home), 없으면 Android Studio에 번들된 것 (/Applications/Android Studio.app/Contents/jbr/Contents/Home).

기기 선택

소유자의 휴대폰이 최우선입니다: adb devices에서 emulator-로 시작하지 않는 시리얼(USB 또는 무선 디버깅)로 표시됩니다. 휴대폰이 없으면 프로젝트의 에뮬레이터를 사용하세요. 소유자가 둘 중 하나를 요청할 수 있습니다; DEVICE=phone, DEVICE=emulator 또는 DEVICE=<시리얼>이 프로젝트 스크립트에서 사용하는 선택 방식입니다.

기기를 선택한 후에는 항상 -s <시리얼>을 adb에 전달하세요. 다른 기기가 중간에 연결될 수 있기 때문입니다.

에뮬레이터

에뮬레이터는 필요할 때만 시작하고 작업이 끝나면 종료하세요. 수 GB의 메모리를 차지합니다. 프로젝트에 scripts/emulator.sh가 있으면 그것을 사용하고, 없으면 이 스킬의 scripts/emulator.sh(스킬 기본 디렉토리에 있으며, 스킬 로드 시 표시됨)를 사용하며, 노트의 AVD=<이름>을 함께 전달합니다:

AVD=<이름> <스킬 디렉토리>/scripts/emulator.sh up       # 헤드리스; Android 부팅 후 시리얼 출력
AVD=<이름> <스킬 디렉토리>/scripts/emulator.sh status
AVD=<이름> <스킬 디렉토리>/scripts/emulator.sh down     # 퀵부트 스냅샷 저장, 다음 시작 시 몇 초 소요

up은 먼저 실행 중인 다른 에뮬레이터를 종료합니다(스크립트와 adb가 첫 번째 에뮬레이터를 선택하기 때문); KEEP_OTHERS=1로 유지 가능; WINDOW=1로 창을 표시하여 소유자가 볼 수 있습니다. 빌드가 동시에 진행될 수 있을 때는 up을 백그라운드에서 실행하세요. 실패 시 로그는 ${TMPDIR:-/tmp}/emulator-<avd>.log에 있습니다.

빌드, 설치, 실행

프로젝트 스크립트를 우선 사용하세요(노트에 지정된 실행 스크립트, UI 랩 스크립트). 수동으로 할 경우:

프로젝트가 지원한다면 기기의 ABI만 빌드하세요 (-Pabi=$(adb -s <시리얼> shell getprop ro.product.cpu.abi) 또는 프로젝트 스크립트용 ABI=): 네이티브 라이브러리 때문에 전체 APK는 무선 디버깅으로 전송 시 느립니다.
adb -s <시리얼> install -r <apk>. -r은 앱 데이터를 유지합니다; 소유자의 휴대폰에서 앱을 삭제하거나 pm clear를 하지 마세요. 실제 데이터가 있기 때문입니다.
adb -s <시리얼> shell am start --user current -S -f 0x10008000 -n <앱 ID>/<액티비티>로 실행하세요: -S는 이전 프로세스를 중지하여 새 빌드가 실행되도록 하고, --user current는 Secure Folder가 있는 휴대폰에서 필요하며, 플래그(새 태스크, 이전 태스크 제거)는 Android가 이전 화면을 재개하지 못하게 합니다.

확인

스크린샷: adb -s <시리얼> exec-out screencap -p > <파일>.png, 그런 다음 파일을 확인하세요. 휴대폰에서 검은 화면이면 잠겨 있는 것입니다: 소유자에게 잠금 해제를 요청하세요.
흐름을 위한 탭 및 입력: adb -s <시리얼> shell input tap <x> <y>, input text <텍스트>, input keyevent KEYCODE_BACK; 좌표는 adb -s <시리얼> exec-out uiautomator dump /dev/tty로 찾으세요.
로그: adb -s <시리얼> logcat -d --pid=$(adb -s <시리얼> shell pidof <앱 ID>), 또는 태그별로 -s <태그>. 충돌: adb -s <시리얼> logcat -d -b crash.
엣지 케이스를 위한 다크 모드 및 로케일: adb -s <시리얼> shell cmd uimode night yes|no; 로케일은 에뮬레이터에서만 변경하고 소유자의 휴대폰에서는 변경하지 마세요.

각 결과가 어떤 기기에서 나왔는지 소유자에게 알리세요. 완료 후 변경한 사항(예: 다크 모드)을 원복하고, 시작한 에뮬레이터를 종료하세요.

android-emulator