Files
DroidDeck/docs/lab-builds.md
T
KeegantheVeganat0r 2953739f1e fix(lab): target the active app package and repair build setup (#2494)
* fix(lab): handle SDK licenses and cache Gradle planning

* fix(lab): target the package owning the agent session

* fix(lab): preserve package overrides across build handoff
2026-11-11 20:55:33 -05:00

4.1 KiB

Lab builds

A Lab build is DroidDeck app code and resources built on the device itself, by the on-device agent or by hand, and loaded over the installed APK at the next start. Nothing is reinstalled or re-signed, so a tester on a release build keeps their games, sign-ins and settings while trying a change.

How it works

  • tools/agent/dd-lab-build builds the checkout with Gradle on the device (processReleaseResources and mergeDexRelease), packs the linked resources and dex files into overlay.apk, writes overlay.json, and stages both in the app's files/lab/next. It then recompiles the app without an app image and restarts DroidDeck.
  • Run by the app's own agent (DD_AGENT set), it writes files/agent/lab-request instead, and the app runs the build in a process of its own, logging to ~/.cache/dd-lab-build.log; the agent's copy follows that log and exits with the build. A turn's processes end with the turn, so a build started there would otherwise die when the agent stops or finishes early.
  • At start, LabOverlay (called from App.attachBaseContext) promotes next to active, checks that the build was made for this install, puts its dex files ahead of the APK's, and adds its resources through ResourcesLoader to the app and every activity. Contexts made from them (presentations on the second screen) inherit the loader.
  • The watermark shows LAB | <branch> @ <commit>. When the app comes back on a new build it posts a "Lab build installed" notification, so the restart does not look like a crash.
  • A build that is replaced, turned off or refused is kept in files/lab/builds (the newest 12). Updates lists them under Lab builds: the one in use can be turned off, one built for this install can be used again, and any can be deleted.

The build targets the package owning DD_AGENT_INBOX when run from the Agent tab. For a manual build of another package, set DROIDDECK_PACKAGE, for example DROIDDECK_PACKAGE=com.tencent.ig dd-lab-build. This also selects the control provider, Lab storage, and package to restart.

What a Lab build cannot change

The manifest, native code (cpp, jniLibs, Rust), Gradle files, App, AppLanguage, and LabOverlay itself: they are loaded before a Lab build can be, or are not part of it. dd-lab-build refuses those changes; they need a new APK.

Safety

  • A build is only used on the install it was built for: overlay.json carries the APK's commit (apkCommit in droiddeckctl state) and the APK's path, which changes with every install and update. A build for another install is turned off.
  • Two starts in a row that do not reach a resumed activity for 10 seconds turn the build off.
  • It needs Android 11 or later (ResourcesLoader) and no app image (classes in one load before the Lab build). dd-lab-build runs cmd package compile -m verify before restarting. Android's background optimization can bring an app image back; the build is then paused, a notification says so, and Restart in Updates recompiles through the app's wireless debugging pairing.

Setting up a device

From the DroidDeck terminal, in a checkout of this repository:

tools/agent/setup

It installs Claude Code, git, gh and loopback adb, plus the build toolchain: JDK 17, the Android SDK platform, and Google's x86-64 aapt2 run under qemu-user. The first Lab build compiles the whole app and takes about 8 minutes on a Snapdragon 865; later ones compile only what changed. That needs the Kotlin daemon: Kotlin's in-process compiles always redo the whole app. BuildConfig is given the installed commit, so committing a change does not change it. Setup does that first build ahead of time with dd-lab-build --prepare, which compiles the installed commit without making a Lab build. ~/.cache/dd-lab-build.json reports the stage, the current task, progress in thousandths and the seconds left, estimated from how long each task took the last time (~/.cache/dd-lab-build-times). ~/.cache/dd-lab-build-base holds the installed commit the last successful build compiled, so the Agent tab can offer to prepare again after DroidDeck updates.