# 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 | @ `. 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: ```sh 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.