build(android): make release buildable and instrumented testing possible
Four gaps that made "ship it" and "test it on hardware" impossible. RELEASE SIGNING. assembleRelease was silently producing app-release-unsigned.apk because there was no signingConfigs block at all — the failure mode where you only notice at install time. Credentials now resolve from keystore.properties, then local.properties, then WEBTERM_RELEASE_* env; nothing is created or committed, and keystore.properties.example is the template. The degradation is ENFORCED, not documented. The signingConfig is only created when credentials actually resolve — an empty config is precisely what makes AGP emit an unsigned artifact quietly — and a guard on packageRelease throws with an actionable message, distinguishing "not configured" from "credentials found but the keystore file is missing: <path>". It hooks the PACKAGE task on purpose: R8 has already run and reported by then, so a developer without a keystore still gets the full shrink result rather than an early abort. Verified: minifyReleaseWithR8 completes, packageRelease fails loudly, and no unsigned APK is written. VERSIONING. Was still the scaffold 1 / "0.1.0". Now 1 / "0.1.0-alpha01", where the suffix is a factual claim about device verification rather than decoration: alpha means device QA is essentially unstarted, beta means the A34/A35 checklist blocks pass on hardware, and plain 0.1.0 means the whole checklist is ticked. versionCode stays 1 because no artifact has ever left the build machine. MINIFICATION. release had isMinifyEnabled = false and an empty rules file — so nothing had ever exercised R8 on this app, and the first release build would have been the experiment. Now minify + resource shrinking, with a deliberately short rules file: the actual artifacts were checked, and kotlinx.serialization, Tink, Hilt, FCM, OkHttp, Compose and CameraX all ship their own consumer rules, so none are re-declared. The termux packages are kept whole because the JitPack artifacts ship no rules and :terminal-view binds to non-API internals — it writes the public TerminalView.mEmulator field and calls TerminalRenderer.getFontWidth()/getFontLineSpacing(). Getting that wrong yields a build that crashes only in production. lintVitalRelease also passes now, the two pre-existing lint ERRORS having been fixed earlier this session. ANDROID TEST ENABLEMENT. :app had no androidTest source set and no instrumentation runner, which is the mechanical reason A34/A35 have no code at all. The runner (Hilt-aware) and dependencies are wired, and a :macrobenchmark module exists. The tests themselves are a separate change. Verified: ./gradlew test :app:assembleDebug :app:assembleDebugAndroidTest :app:assembleBenchmark :macrobenchmark:assembleBenchmark :app:lintVitalRelease koverVerify -> BUILD SUCCESSFUL; 901 JVM tests, 0 failures on a forced re-execution with test-results deleted and --no-build-cache.
This commit is contained in:
Yaojia Wang
@@ -9,6 +9,13 @@ This directory is a **Gradle multi-module** project. The module set mirrors the
|
||||
SPM package set and inherits its rule: *dependencies only flow down; nothing points
|
||||
upward* (ARCHITECTURE §1).
|
||||
|
||||
> **State, honestly:** the app builds, minifies, signs (given a keystore) and cold-starts
|
||||
> to the pairing screen on an emulator. It has **never talked to a real WebTerm host from
|
||||
> a device**, and almost nothing in
|
||||
> [`DEVICE_QA_CHECKLIST.md`](DEVICE_QA_CHECKLIST.md) is ticked. Version is
|
||||
> `0.1.0-alpha01` for exactly that reason. Read that checklist before calling anything
|
||||
> here done.
|
||||
|
||||
## Build environment (SDK installed — all modules build)
|
||||
|
||||
The Android SDK **is installed** and every module — pure Kotlin/JVM and Android-framework
|
||||
@@ -19,10 +26,12 @@ against SDK 35/36.
|
||||
`:client-tls`, `:test-support`, `:transport-okhttp`.
|
||||
- **Android-framework (online in [`settings.gradle.kts`](settings.gradle.kts)):**
|
||||
`:app`, `:terminal-view`, `:host-registry`, `:client-tls-android`.
|
||||
- **Instrumented-only:** `:macrobenchmark` (`com.android.test`; assembles here, runs only
|
||||
on a device/emulator).
|
||||
|
||||
Setup: `local.properties` → `sdk.dir=/usr/local/share/android-commandlinetools`;
|
||||
`google()` is in `pluginManagement`/`dependencyResolutionManagement`. Green gate:
|
||||
`./gradlew test :app:assembleDebug koverVerify`.
|
||||
`./gradlew test :app:assembleDebug :app:assembleDebugAndroidTest koverVerify`.
|
||||
|
||||
## Module map (mirror of the iOS SPM packages — plan §3)
|
||||
|
||||
@@ -37,10 +46,15 @@ Setup: `local.properties` → `sdk.dir=/usr/local/share/android-commandlinetools
|
||||
| HostRegistry | `:host-registry` | Android (DataStore) | ✅ built |
|
||||
| SwiftTerm host view | `:terminal-view` | Android (Termux wrap) | ✅ built |
|
||||
| App/WebTerm | `:app` | Android app (Compose/Hilt/FCM)| ✅ built |
|
||||
| — (no iOS counterpart) | `:macrobenchmark` | `com.android.test` harness | ⬜ scaffolded, no sources |
|
||||
|
||||
> Not yet scaffolded: `:transport-okhttp` (OkHttp `TermTransport`/`HttpTransport`
|
||||
> impls, JVM) is owned by task **A7** and will be added then. The iOS
|
||||
> `URLSession*Transport`s consolidate into it (plan §3 framing note).
|
||||
`:macrobenchmark` (A35) is the one module with no iOS counterpart. It is a
|
||||
`com.android.test` module — a **separate APK** that drives `:app` out of process via
|
||||
UiAutomator, which is the only way startup/frame timings are real. It therefore cannot
|
||||
violate "dependencies only flow down": nothing depends on it, and it reaches `:app`
|
||||
through `targetProjectPath`, not a `project()` dependency. It instruments `:app`'s
|
||||
`benchmark` variant (see "Build types" below). The benchmark sources themselves are not
|
||||
written yet.
|
||||
|
||||
### Dependency graph (arrows = "depends on")
|
||||
|
||||
@@ -82,15 +96,124 @@ JUnit Platform (`tasks.test { useJUnitPlatform() }`).
|
||||
|
||||
```bash
|
||||
# Use the committed wrapper for everything.
|
||||
./gradlew help # sanity: the build configures
|
||||
./gradlew projects # lists the 5 pure modules
|
||||
./gradlew build # compile all pure modules
|
||||
./gradlew test # run JVM unit tests (JUnit5 + coroutines-test + Turbine + MockK)
|
||||
./gradlew help # sanity: the build configures
|
||||
./gradlew projects # lists every module
|
||||
./gradlew test # JVM unit tests (JUnit5 + coroutines-test + Turbine + MockK)
|
||||
./gradlew :app:assembleDebug # the installable debug APK
|
||||
./gradlew koverVerify # the ≥80% gate on the pure modules
|
||||
|
||||
# Release path (needs a keystore — see "Release signing")
|
||||
./gradlew :app:assembleRelease # R8 + resource shrinking + signing
|
||||
./gradlew :app:lintVitalRelease # the release-blocking lint subset; must be clean
|
||||
|
||||
# Minified build WITHOUT a keystore — the practical way to test R8 keep rules
|
||||
./gradlew :app:assembleBenchmark # same shrinking as release, debug-signed → installable
|
||||
```
|
||||
|
||||
> Testing target: **≥80% Kover coverage** on the pure modules (`:wire-protocol`,
|
||||
> `:session-core`, `:api-client`, `:client-tls` pure half). TDD, immutable data,
|
||||
> small focused files — same discipline as the rest of the repo.
|
||||
>
|
||||
> **Do not use `--rerun-tasks` in a release gate.** It trips an AGP lint/K2 internal bug
|
||||
> (`FirDeclaration was not found for class KtProperty, fir is null`, on
|
||||
> `ThumbnailPipeline.kt`). `lintVitalRelease` passes normally and from a cold lint state.
|
||||
|
||||
## Build types
|
||||
|
||||
| Type | Minified | Shrunk res | Debuggable | Signed with | Purpose |
|
||||
|---|---|---|---|---|---|
|
||||
| `debug` | no | no | yes | debug key | development; stable applicationId for deep-link tests (A32) |
|
||||
| `release` | **yes** | **yes** | no | **release key (required)** | the shipping artifact |
|
||||
| `benchmark` | **yes** | **yes** | no | debug key | `initWith(release)` + `isProfileable`; what `:macrobenchmark` measures, and the only way to exercise R8 without a keystore |
|
||||
|
||||
`benchmark` exists because a benchmark must measure the code that actually ships. It sets
|
||||
`isProfileable = true`, which makes AGP inject `<profileable android:shell="true"/>` into
|
||||
the merged manifest — done there rather than in `AndroidManifest.xml` so the shipping
|
||||
manifest carries no benchmark-only tag.
|
||||
|
||||
## Versioning
|
||||
|
||||
Current: `versionCode = 1`, `versionName = "0.1.0-alpha01"`.
|
||||
|
||||
- **`versionCode`** is a plain monotonic counter — **+1 for every artifact handed to anyone**
|
||||
(a Play track, an APK sent to a tester, an archived benchmark build). It is deliberately
|
||||
NOT derived from `versionName`; keeping them independent is what lets a hotfix ship
|
||||
without renumbering. It is still `1` because no artifact has ever left the build machine;
|
||||
the first distributed build takes `2`.
|
||||
- **`versionName`** is `<server-line>-alphaNN`. The client tracks the server's `0.1.x` line
|
||||
(root `package.json` is `0.1.0`). The `-alpha01` suffix is a factual claim about device
|
||||
verification, not marketing:
|
||||
- `-alphaNN` — builds, minifies, JVM-tested; **device QA essentially unstarted**. ← today
|
||||
- `-betaNN` — the A34/A35 blocks of `DEVICE_QA_CHECKLIST.md` pass on real hardware.
|
||||
- `0.1.0` — the whole checklist is ticked.
|
||||
|
||||
Bump the suffix on any user-visible change while still in alpha; move to `0.1.1-alphaNN`
|
||||
only when the server line moves.
|
||||
|
||||
## Release signing
|
||||
|
||||
There is **no keystore in this repository and there must never be one.** Credentials are
|
||||
read at configuration time from the first of these that has them:
|
||||
|
||||
1. `android/keystore.properties` — the conventional path. Copy
|
||||
[`keystore.properties.example`](keystore.properties.example).
|
||||
⚠️ **Confirm `keystore.properties` is listed in `android/.gitignore` before creating it.**
|
||||
The existing rules cover `*.jks` / `*.keystore` / `*.p12` but not this filename.
|
||||
2. `android/local.properties` — already gitignored, so it needs no new rule. Same four keys.
|
||||
3. `WEBTERM_RELEASE_STORE_FILE` / `_STORE_PASSWORD` / `_KEY_ALIAS` / `_KEY_PASSWORD` — for CI.
|
||||
|
||||
Keys: `webterm.release.storeFile` (absolute, or relative to `android/`),
|
||||
`.storePassword`, `.keyAlias`, `.keyPassword`.
|
||||
|
||||
**Degradation contract:** with no credentials, `debug`, `benchmark`, `assembleDebugAndroidTest`
|
||||
and every test still work, and `:app:assembleRelease` **fails at `packageRelease`** with
|
||||
instructions. It fails at *packaging*, deliberately after R8, so an unconfigured machine
|
||||
still gets a full, verifiable R8 run. It never silently emits `app-release-unsigned.apk`
|
||||
(which is exactly what it used to do).
|
||||
|
||||
**Archive `app/build/outputs/mapping/release/mapping.txt` with every distributed artifact** —
|
||||
release builds keep line numbers but obfuscate names, so without the mapping file a crash
|
||||
report cannot be retraced.
|
||||
|
||||
### R8 / keep rules
|
||||
|
||||
`app/proguard-rules.pro` is deliberately short and every rule is justified in place; most
|
||||
of the stack (kotlinx.serialization, Hilt, Tink, Firebase, OkHttp, Compose, CameraX)
|
||||
ships its own consumer rules and must not be re-declared. Two rules are load-bearing and
|
||||
were both derived from **observed** failures, not guesswork:
|
||||
|
||||
- `com.termux.**` is kept whole, because `:terminal-view` binds to non-API internals of the
|
||||
pinned v0.118.0 (the public `TerminalView.mEmulator` field, `TerminalRenderer.getFontWidth()`)
|
||||
and the JitPack artifacts ship no consumer rules.
|
||||
- `implements com.google.firebase.components.ComponentRegistrar { <init>(); }`, because
|
||||
without it R8 strips the reflectively-invoked constructors of ML Kit's registrars and
|
||||
**QR scanning silently stops working in release builds only**.
|
||||
|
||||
Before adding a rule, read the merged configuration R8 actually used:
|
||||
`app/build/outputs/mapping/<variant>/configuration.txt`. To validate rules, install the
|
||||
`benchmark` APK and exercise the feature — a wrong keep rule is invisible in debug.
|
||||
|
||||
## Instrumented tests
|
||||
|
||||
`:app` has an androidTest classpath (androidx.test + Espresso + Compose UI test +
|
||||
`hilt-android-testing` with `kspAndroidTest`) and `testInstrumentationRunner` is set to
|
||||
`wang.yaojia.webterm.HiltTestRunner`.
|
||||
|
||||
⚠️ **That runner class does not exist yet** — it is the first file the A34 author must write,
|
||||
into `app/src/androidTest/java/wang/yaojia/webterm/HiltTestRunner.kt`:
|
||||
|
||||
```kotlin
|
||||
class HiltTestRunner : AndroidJUnitRunner() {
|
||||
override fun newApplication(cl: ClassLoader?, name: String?, context: Context?): Application =
|
||||
super.newApplication(cl, HiltTestApplication::class.java.name, context)
|
||||
}
|
||||
```
|
||||
|
||||
A custom runner is **required**, not stylistic: `newApplication` is the only hook that can
|
||||
replace the app-under-test's `Application` with the generated `HiltTestApplication`. Setting
|
||||
`android:name` in the androidTest manifest cannot do it — that manifest is merged into the
|
||||
*test* APK, not into the app under test. `assembleDebugAndroidTest` builds fine without the
|
||||
class (the runner name is just a manifest value); an actual instrumentation *run* needs it.
|
||||
|
||||
## Android SDK setup (proven working)
|
||||
|
||||
@@ -127,5 +250,32 @@ AGP library module compiled against SDK 35 and produced an AAR):
|
||||
`android.application` + `kotlin.plugin.compose` + `ksp` + `dagger.hilt.android` (NEVER
|
||||
`kotlin.android`). Bump these together with `compileSdk 37` once platform 37 is installable.
|
||||
|
||||
To add more SDK pieces later (e.g. an emulator image for instrumented tests):
|
||||
- **A `com.android.test` module cannot use a versioned plugin alias.** The root build
|
||||
script already puts AGP on the classpath via the `android.library`/`android.application`
|
||||
aliases, so a third versioned request for the same artifact fails with *"plugin is already
|
||||
on the classpath with an unknown version"*. `:macrobenchmark` therefore applies
|
||||
`id("com.android.test")` bare — same as `:terminal-view` with `com.android.library`. The
|
||||
version is still pinned once, as `agp` in the catalog.
|
||||
|
||||
## Emulator (installed)
|
||||
|
||||
An AVD named **`webterm`** exists (android-35, arm64, software GPU) and is what produced the
|
||||
on-device evidence recorded in [`DEVICE_QA_CHECKLIST.md`](DEVICE_QA_CHECKLIST.md):
|
||||
|
||||
```bash
|
||||
export ANDROID_HOME=/usr/local/share/android-commandlinetools
|
||||
$ANDROID_HOME/emulator/emulator -avd webterm -gpu swiftshader_indirect &
|
||||
$ANDROID_HOME/platform-tools/adb devices -l
|
||||
|
||||
# validate the MINIFIED build (this is what catches bad keep rules)
|
||||
./gradlew :app:assembleBenchmark
|
||||
adb install -r app/build/outputs/apk/benchmark/app-benchmark.apk
|
||||
adb logcat -c && adb shell am start -W -n wang.yaojia.webterm/.MainActivity
|
||||
adb logcat -d --pid=$(adb shell pidof wang.yaojia.webterm) | grep -E "FATAL|NoSuchMethod|NoClassDefFound"
|
||||
```
|
||||
|
||||
Note it is a **software-GPU** emulator: it is fine for crash/keep-rule/route validation and
|
||||
useless for performance numbers. Real macrobenchmark figures need physical hardware.
|
||||
|
||||
To add more SDK pieces later:
|
||||
`sdkmanager "system-images;android-35;google_apis;arm64-v8a" "emulator"`.
|
||||
|
||||
Reference in New Issue
Block a user