# Testing an Android build on a device

Notes from driving real devices over adb. Most of what follows is not about Android being hard, but
about ways the tooling quietly answers a question you did not ask - you measure the wrong build, or
measure garbage that has not been collected yet, and get a confident wrong answer.

## Install the build you think you are testing

`versionCode` is derived from the git commit count (see `gitVersionCode` in
`android/build.gradle.kts`), so a feature branch has a *lower* code than a longer branch. Installing
one over the other fails:

    adb: failed to install ...: Failure [INSTALL_FAILED_VERSION_DOWNGRADE]

`-r` does not permit downgrades; `-d` does. Use `adb install -r -d <apk>`.

Do not pipe the install through `tail -1` or `grep Success` and move on. The failure is a single
line and easy to swallow, and the device then keeps running whatever was there before - every
measurement afterwards describes the wrong binary, including A/B comparisons where both arms end up
being the same build and therefore agree with each other.

Verify after every install, not just when something looks odd:

    adb shell dumpsys package org.ppsspp.ppsspp | grep versionName

A second, independent check is worth it when a result is surprising: grep the log for a symbol that
exists only on the branch under test (a renamed class or log tag, say).

The version string itself can also lie. The Android build regenerates `git-version.cpp` but does not
always recompile it, so the APK can carry the previous build's string while containing current code.
When the version matters:

    find android/.cxx -name git-version.cpp.o -delete

## Forcing an activity recreate without touching the device

- `adb shell settings put system font_scale 1.15`, then back. `fontScale` is not in the activity's
  `configChanges`, so each change destroys and recreates the activity. Independent of orientation.
- `adb shell wm density <n>` also recreates - but only while `density` is absent from
  `configChanges`.
- `adb shell settings put system user_rotation 1` does **not** rotate PPSSPP. The activity follows
  the sensor, so this needs a physical rotation (or a cooperative device).

Put back whatever you changed: `font_scale`, `accelerometer_rotation`, `user_rotation`.

`wm density reset` is actively wrong on a device with a resolution override - a Galaxy S8 running
1080x2220 on a 1440x2960 panel resets to the *physical* panel's density and leaves the UI oversized.
Read the original with `wm density` first and set it back explicitly.

## Measuring retained activities

`adb shell dumpsys meminfo <pkg>` prints an Objects block with `Activities` and `AppContexts`.

The counts include objects that are garbage but not yet collected. Read it straight after N
recreates and you will see roughly N whether or not anything leaks, which looks exactly like a leak.
Force collection instead:

    adb shell am send-trim-memory org.ppsspp.ppsspp COMPLETE

then wait around eight seconds and read. Repeat until two readings agree - three or four rounds is
normal, and a single trim is not enough.

The protocol that gives an answer you can trust: cold start and read the baseline, do N recreates,
trim until stable, compare. A sound build returns to the baseline; a leaking one sits at baseline+N
and stays there.

Worked example, Galaxy S8 on Android 9, same device and protocol, both builds confirmed by
`versionName`. Before the activity handover fix: 13 recreates left 13 Activities and 18 AppContexts,
stable across repeated trims. After: the same 13 recreates settled back to 1 and 6.

A JNI global reference is a GC root, so an activity pinned by one shows up here. This is a usable
check for JNI ownership bugs, not only Java ones.

## logcat on a noisy device

Filter to the process, since the tag alone is not enough:

    adb logcat -d --pid=$(adb shell pidof org.ppsspp.ppsspp)

On a device with a chatty system - a Quest especially - the ring buffer can rotate the app's lines
away within seconds, which reads as "logging stopped" rather than "logging was lost". Start a stream
*before* launching the app instead:

    adb logcat -c && adb logcat -s PPSSPP:V PpssppActivity:V   # in the background, then start the app

## VR (Quest)

- The VR flavor is a separate package: `./gradlew :android:assembleVrDebug`, installing as
  `org.ppsspp.ppssppvr`. It can sit alongside the normal build.
- `adb exec-out screencap` returns solid black for an immersive app - it captures the 2D panel
  layer, which such an app does not have. Use the runtime's own line instead: a logcat entry like
  `VrApi: FPS=73/72 ... App=2.67ms` proves frames are being submitted and how much GPU time the app
  spent on them. Zero app time means the render loop is not producing.
- `am start` makes the activity `topResumedActivity`, but the shell keeps focus, so the app never
  gets a surface and the render loop does not restart. Re-entering an immersive app has to be done
  from inside the headset. A fresh `am start -S` after a `force-stop` does work.
- `debuggerd -b <tid>` needs root, so no native stacks from a retail headset.

## Check which paths the device actually exercises

Before concluding that a test covered something:

    adb shell grep -E '^(MemStickDirectory|GraphicsBackend)' /storage/emulated/0/PSP/SYSTEM/ppsspp.ini

A plain filesystem path for the memstick means the SAF/content-URI code
(`Common/File/AndroidStorage.cpp`, `ContentUri.java`) is never entered, so a run on that device says
nothing about it - a recents list full of plain paths says the same. The VR flavor reads
`ppssppvr.ini`, not `ppsspp.ini`.