A rootless Android app that boots Alpine Linux: run containers (Podman/Docker/LXC) and GUI desktop apps.
docs(contributing): correct the stale parts and state the unwritten rules
ExTv188181beced0
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 1cee7ad..5f9d856 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -23,24 +23,29 @@ You will need:`build-all.sh` orchestrates every component:```sh-./build-all.sh kernel # custom Linux 6.6.87 (~5–10 min, Docker-cached)+./build-all.sh kernel # custom Linux kernel (~5-10 min, Docker-cached)./build-all.sh initramfs # kernel + minimal initramfs-./build-all.sh rootfs # Alpine 3.23 squashfs (~30 s, Docker-cached)-./build-all.sh qemu # QEMU 11 + podroid-bridge (~30 min first run)-./build-all.sh termux # libtermux.so via local NDK-./gradlew installDebug # build + install the APK+./build-all.sh rootfs # Alpine squashfs (~30 s, Docker-cached)+./build-all.sh qemu # QEMU + podroid-bridge (~30 min first run)+./build-all.sh termux # terminal-emulator JNI via local NDK+./build-all.sh apk # Android APK via Gradle+./build-all.sh all # everything+./build-all.sh deploy # all + install + launch+./build-all.sh test # deploys APK, polls console.log for "Ready!"```-Or, for the common case where you only changed Kotlin / UI code:+Component versions are pinned in one place each, so read the pin rather than trusting a number written in prose:-```sh-./gradlew installDebug-```+| Component | Pinned in |+|---|---|+| Linux kernel | `podroidKernelVersion` in `gradle.properties` |+| QEMU | `podroidQemuVersion` in `gradle.properties` |+| Alpine | `ARG ALPINE_RELEASE` in `build-rootfs/Dockerfile.rootfs` |-To validate a full rebuild end-to-end:+Or, for the common case where you only changed Kotlin / UI code:```sh-./build-all.sh test # deploys APK, polls console.log for "Ready!"+./gradlew installDebug```## Reporting bugs@@ -55,13 +60,60 @@ It bundles app version, device model + Android version, settings, and full logcaadb shell run-as com.excp.podroid.debug cat files/console.log```+Note that `run-as` works on debug builds only. Release builds are not `run-as`-able, so use the in-app export there.+## Submitting changes1. Fork the repository and create a topic branch (`fix/issue-42`, `feature/whatever`).2. Keep pull requests focused: one fix or one feature per PR.-3. Test on a real arm64 device before submitting. Emulators do not exercise the QEMU + native binary path the way real hardware does. If your change touches the engine boundary or AVF, note that only a device reporting `android.software.virtualization_framework` (`adb shell pm list features | grep virtualization`) can exercise the AVF backend at all; see [Proving a change on a device](CLAUDE.md#proving-a-change-on-a-device) for the grant sequence and for which backend needs which device. Say in the PR which backends you actually tested on.-4. If your change is user-facing, update [`README.md`](README.md). If it changes the architecture, boot pipeline, terminal layer, or kernel options, update [`CLAUDE.md`](CLAUDE.md) too.-5. Match the existing code style of the file you are editing.+3. Work through the checklist below before opening the PR.+4. Match the existing code style of the file you are editing.++### Before you open a PR++**Run the unit tests.** Use the `:app:` form; the bare task name does not behave the same way.++```sh+./gradlew :app:testDebugUnitTest+```++**Test on a real arm64 device.** Emulators do not exercise the QEMU and native-binary path the way real hardware does. Unit tests cover pure logic only, so anything touching VM behaviour, the engine boundary, or a user-visible flow is unproven until it runs on hardware.++If your change touches the engine boundary or AVF, note that the two backends need two different devices: only a device reporting `android.software.virtualization_framework` can exercise AVF at all.++```sh+adb shell pm list features | grep virtualization+```++See [Proving a change on a device](CLAUDE.md#proving-a-change-on-a-device) for the grant sequence and which backend needs which device. **Say in the PR which backends you actually tested on.** Backend asymmetry is the most common source of bugs here, so a QEMU-only test is the easiest way to ship a regression.++**Add both translations for any user-facing string.** Every string needs an entry in `app/src/main/res/values/strings.xml` and `app/src/main/res/values-zh/strings.xml`, and must be referenced with `stringResource`. Do not hardcode user-facing text.++**Never rename a DataStore key without a migration.** Saved user state has to survive every release, since updates install in place. The Kotlin identifier is free to change, but the string literal is an on-disk contract: renaming it orphans the stored value and the setting silently reverts to its default on the user's next launch. `DataStoreKeyContractTest` will fail if you change one. If the rename is deliberate, ship a migration that reads the old key and writes the new one, and update the expectation in the same commit.++**Update the docs your change affects.** If it is user-facing, update [`README.md`](README.md). If it changes the architecture, boot pipeline, terminal layer, or kernel options, update [`CLAUDE.md`](CLAUDE.md) too.++### Commit messages++This repository uses [Conventional Commits](https://www.conventionalcommits.org/): `type(scope): summary`, all lowercase.++```+fix(avf): distinguish an absent GPU API from a failed declaration+docs(site): explain how to reach the desktop from another computer+test(data): pin the persisted DataStore key literals+```++The body should explain **why** the change is needed, not restate what the diff does. A reader six months from now needs the reasoning, not a summary they could get from `git show`.++Avoid `fixes #N` or `closes #N` unless you intend the issue to close when the commit lands, since those keywords close issues automatically. Use `for #N` or `addresses #N` to reference without closing.++## Code style++- Kotlin: follow the [official conventions](https://kotlinlang.org/docs/coding-conventions.html).+- Keep it simple. No premature abstractions.+- Match the surrounding file's style. Consistency beats personal preference.+- Comments explain *why*, not *what*. Self-documenting names go further than prose.+- No emoji, and no em dashes, in code, comments, commit messages, or documentation. Use hyphens, commas, colons, or restructure the sentence.## Project layout@@ -70,33 +122,41 @@ Podroid/├── app/ Android application (Jetpack Compose, Hilt)│ └── src/main/│ ├── java/com/excp/podroid/-│ │ ├── engine/ PodroidQemu, QmpClient, VmState-│ │ ├── service/ Foreground service + boot-stage notification-│ │ ├── data/repository/ DataStore-backed settings & port forwards+│ │ ├── engine/ VmEngine interface + both backends+│ │ │ ├── VmEngine.kt the backend contract+│ │ │ ├── EngineHolder.kt Hilt binding; picks and routes to a backend+│ │ │ ├── QemuEngine.kt QEMU/TCG backend, buildCommand()+│ │ │ ├── QmpClient.kt QMP: port forwards + USB+│ │ │ ├── avf/ AVF/pKVM backend (reflection, vsock, 9p)+│ │ │ ├── hostbridge/ guest to Android bridge+│ │ │ └── usb/ USB passthrough (QEMU only)+│ │ ├── service/ Foreground service owning the VM lifecycle+│ │ ├── data/repository/ DataStore-backed settings, port forwards,+│ │ │ updates, language, backups, container stats+│ │ ├── util/ Network, shell quoting, host metrics+│ │ ├── x11/ X11/VNC viewer engine│ │ └── ui/ Compose screens + theme-│ ├── jniLibs/arm64-v8a/ QEMU, podroid-bridge, libslirp, libtermux+│ ├── res/values, res/values-zh/ strings (English + Chinese, keep in sync)+│ ├── jniLibs/arm64-v8a/ QEMU, podroid-bridge, podroid-launcher, libslirp│ └── assets/ kernel, initramfs, squashfs, fonts, themes+├── terminal-view/, terminal-emulator/ vendored Termux fork (local Gradle modules)├── init-podroid Minimal initramfs script (~45 lines)-├── podroid-bridge.c Native PTY ↔ virtio-console relay+├── podroid-bridge.c Native PTY <-> virtio-console relay+├── podroid-launcher.c exec wrapper tying QEMU's lifetime to the app├── Dockerfile Kernel + initramfs + QEMU build pipeline├── build-tools/ Static assets used during Docker builds-│ └── cross-android-aarch64.ini Meson cross-compilation config for aarch64-android26+│ └── cross-android-aarch64.ini Meson cross-compilation config├── build-rootfs/ Alpine squashfs build pipeline│ ├── Dockerfile.rootfs│ ├── build-rootfs.sh+│ ├── vsock-agent/ AVF control/forward agent+│ ├── host-bridge/ guest to Android bridge daemon│ └── files/ OpenRC services baked into the squashfs├── build-all.sh Unified build / deploy script├── podroid_kernel.config Custom kernel Kconfig fragment└── docs/ GitHub Pages site```-## Code style--- Kotlin: follow the [official conventions](https://kotlinlang.org/docs/coding-conventions.html).-- Keep it simple. No premature abstractions.-- Match the surrounding file's style. Consistency beats personal preference.-- Comments explain *why*, not *what*. Self-documenting names go further than prose.-## LicenseBy contributing, you agree that your work will be licensed under the **GNU General Public License v2.0**, the same license as the project.