---
name: android-build-install
description: Build and install the GameTime Android phone and watch APKs from validated local code. Use when Codex needs to rebuild release APKs, free space in /tmp if needed, route Gradle/Kotlin/Flutter caches to writable directories, and install with adb on connected devices, uninstalling the previous app only if install -r fails.
---
# Android Build Install

Build the phone and watch release APKs from the current validated codebase, using writable cache locations and a compatible JDK.

## Workflow

1. Check free space on `/tmp` and list `gametime-*` temporary folders.
2. If `/tmp` is too full for a build copy, delete only stale `gametime-*` temporary folders created by prior build/archive attempts. Never mass-delete unrelated `/tmp` content.
3. Detect the current git state and decide the build source.
4. If the current worktree already contains the validated fixes to package, use it directly when possible.
5. If integration must combine validated changes from multiple branches that are not merged yet, create a temporary build workspace under `/tmp/gametime-build-<timestamp>` from the chosen base branch or archive, then overlay the validated files or patch set needed for the target build.
6. Copy Android signing files required by the repo into the build workspace when the build runs outside the project root.
7. Force writable tool state before building:
   - `HOME=/home/anthony/Documents/Projects/GameTime/.build-home`
   - `PUB_CACHE=/home/anthony/Documents/Projects/GameTime/.build-home/.pub-cache`
   - `XDG_CONFIG_HOME=/home/anthony/Documents/Projects/GameTime/.build-home/.config`
   - `XDG_CACHE_HOME=/home/anthony/Documents/Projects/GameTime/.build-home/.cache`
   - `XDG_DATA_HOME=/home/anthony/Documents/Projects/GameTime/.build-home/.local/share`
   - `ANDROID_USER_HOME=/home/anthony/Documents/Projects/GameTime/.build-home/.android`
   - `GRADLE_USER_HOME` to a phone- or watch-specific directory under `.build-home`
   - `JAVA_HOME=/usr/lib/jvm/java-21-openjdk`
   - prepend `$JAVA_HOME/bin` to `PATH`
   - `_JAVA_OPTIONS=-Duser.home=/home/anthony/Documents/Projects/GameTime/.build-home -Djava.io.tmpdir=/home/anthony/Documents/Projects/GameTime/.build-home/.tmp -Dkotlin.daemon.enabled=false -Dkotlin.compiler.execution.strategy=in-process`
   - `GRADLE_OPTS=-Dorg.gradle.jvmargs=-Xmx4g -Dkotlin.daemon.enabled=false -Dkotlin.compiler.execution.strategy=in-process -Duser.home=/home/anthony/Documents/Projects/GameTime/.build-home -Djava.io.tmpdir=/home/anthony/Documents/Projects/GameTime/.build-home/.tmp`
   - `FLUTTER_SUPPRESS_ANALYTICS=true`
8. Build the phone APK with `flutter build apk --release` from the app root.
9. Build the watch APK with `flutter build apk --release` from `watch_app/`.
10. Record the final APK paths.

## Installation

1. Run `adb devices -l`.
2. Identify the phone and watch endpoints explicitly before installing.
3. Install the phone APK with `adb -s <serial> install -r <apk>`.
4. Install the watch APK with `adb -s <serial> install -r <apk>`.
5. Only if `install -r` fails for a package upgrade reason, uninstall `com.gametime.app` on that device and retry a plain `adb install <apk>`.
6. Report success or the exact adb error per device.

## Guardrails

- Never delete arbitrary `/tmp` content; only remove targeted `gametime-*` temporary folders that were created for build/archive work.
- Prefer release APKs unless the user explicitly asks for debug builds.
- Keep phone and watch builds on the same validated code snapshot.
- If `adb` shows duplicate watch endpoints, probe them and choose one working endpoint before install.
- If git writes are blocked, avoid forcing repository state changes; use a temporary integrated build workspace instead.
- Report the exact APK output paths after a successful build.
- If build or install fails, report the real failing command and error instead of paraphrasing.