A rootless Android app that boots Alpine Linux: run containers (Podman/Docker/LXC) and GUI desktop apps.
fix(build): fix devtmpfs boot panic, Dockerfile heredoc parse error, and Android 8 docs
Vitor Soares580fb26e1dbc
diff --git a/CLAUDE.md b/CLAUDE.mdindex 6cbb97c..f2576a7 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -4,7 +4,7 @@ Guidance for Claude Code (and any AI assistant or new contributor) working in th## What Is This-Podroid is an Android app that runs a real **Alpine 3.23** Linux VM on stock Android 9+ (arm64) to provide rootless **Podman / Docker / LXC** containers and an in-app **X11 desktop** - no root, no custom recovery.+Podroid is an Android app that runs a real **Alpine 3.23** Linux VM on stock Android 8+ (arm64) to provide rootless **Podman / Docker / LXC** containers and an in-app **X11 desktop** - no root, no custom recovery.- **Two interchangeable VM backends** behind one interface (`VmEngine`):- **QEMU (TCG)** - software emulation, the default, needs no special permission.@@ -18,7 +18,7 @@ Podroid is an Android app that runs a real **Alpine 3.23** Linux VM on stock And|---|---|| Package | `com.excp.podroid` (debug: `com.excp.podroid.debug`) || Version | `versionName` / `versionCode` in `app/build.gradle.kts` |-| Min / target SDK | 28 (Android 9) / 36 |+| Min / target SDK | 26 (Android 8) / 36 || Architecture | arm64 (`aarch64`) only || Guest | Alpine 3.23 squashfs + persistent ext4 overlay, OpenRC PID 1 || Kernel | custom Linux, version pinned by `podroidKernelVersion` in `gradle.properties` |@@ -166,6 +166,8 @@ Single-activity Compose app: `ui/navigation/NavGraph.kt` routes `setup → home├── podroid-bridge.c # PTY <-> virtio-console relay -> libpodroid-bridge.so├── podroid-launcher.c # exec wrapper that ties QEMU's lifetime to the app -> libpodroid-launcher.so├── Dockerfile # kernel + initramfs + QEMU build+├── build-tools/ # static assets used during Docker builds+│ └── cross-android-aarch64.ini # Meson cross-compilation config for aarch64-android26├── build-rootfs/│ ├── Dockerfile.rootfs, build-rootfs.sh│ ├── vsock-agent/ # podroid-vsock-agent.c (AVF control/forward agent)@@ -207,6 +209,9 @@ In `QemuEngine.buildCommand()`: `tcg,thread=multi`, larger `tb-size` for ≥2GB## Quirks & gotchas+- **`CONFIG_DEVTMPFS_MOUNT=y` pre-mounts `/dev` before `/init` runs.** `init-podroid` must use `mount ... || true` for the devtmpfs line — the kernel's pre-populated `/dev` is sufficient and a second `mount(2)` returns EBUSY. Also: `size=` is not valid for devtmpfs in kernels where it is ramfs-backed (causes EINVAL). Either failure exits util-linux with `MNT_EX_FAIL=32`; `set -e` propagates `exit(32)`, encoded as `exitcode=0x00002000` ("Attempted to kill init!"). Always keep the `|| true`.+- **util-linux `mount` stops option parsing at the first non-option argument** when `POSIXLY_CORRECT` is set. Put `-o` flags *before* device and mountpoint (`mount -t proc -o noexec,nosuid,nodev proc /proc`), not after. Options placed after the mountpoint are silently dropped, causing `mount(2)` to be called with `flags=0` and returning EPERM — which util-linux prints as "must be superuser to use mount" even for root.+- **`Dockerfile` heredoc gotcha.** Docker BuildKit's parser treats `[section]` lines inside `RUN ... << 'EOF'` heredocs as unknown Dockerfile instructions and aborts the parse. Instead of using shell heredocs in `RUN` for multi-line config files, use `COPY build-tools/<file>` from the build context. The Meson cross-compilation config lives in `build-tools/cross-android-aarch64.ini` for this reason.- **Backend asymmetry is the #1 source of bugs.** QEMU = SLIRP + QMP + virtio-console (TTY); AVF = DHCP + vsock (raw sockets). Test both. The host bridge's `cfmakeraw` on hvc2 (above) is a concrete example.- **Boot detection** scans a rolling buffer, not per-read chunks (fast devices split markers).- **Bridge stderr is silenced** (`dup2(/dev/null, STDERR)`): it runs as a `TerminalSession` subprocess whose stderr IS the PTY. Never add `fprintf(stderr, ...)` to `podroid-bridge.c`.diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 36f8ff6..9f48e58 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -79,6 +79,8 @@ Podroid/├── init-podroid Minimal initramfs script (~45 lines)├── podroid-bridge.c Native PTY ↔ virtio-console relay├── 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├── build-rootfs/ Alpine squashfs build pipeline│ ├── Dockerfile.rootfs│ ├── build-rootfs.shdiff --git a/Dockerfile b/Dockerfileindex 06d9624..27e74ce 100644--- a/Dockerfile+++ b/Dockerfile@@ -227,28 +227,7 @@ RUN printf '#!/bin/sh\nexport PKG_CONFIG_LIBDIR=/opt/deps/lib/pkgconfig\nexport> /usr/local/bin/aarch64-android-pkg-config && chmod +x /usr/local/bin/aarch64-android-pkg-config \&& ln -s /usr/local/bin/aarch64-android-pkg-config ${LLVM}/bin/llvm-pkg-config-RUN cat > /opt/cross-android-aarch64.ini << 'EOF'-[binaries]-c = '/opt/ndk/toolchains/llvm/prebuilt/linux-x86_64/bin/aarch64-linux-android26-clang'-cpp = '/opt/ndk/toolchains/llvm/prebuilt/linux-x86_64/bin/aarch64-linux-android26-clang++'-ar = '/opt/ndk/toolchains/llvm/prebuilt/linux-x86_64/bin/llvm-ar'-strip = '/opt/ndk/toolchains/llvm/prebuilt/linux-x86_64/bin/llvm-strip'-ranlib = '/opt/ndk/toolchains/llvm/prebuilt/linux-x86_64/bin/llvm-ranlib'-nm = '/opt/ndk/toolchains/llvm/prebuilt/linux-x86_64/bin/llvm-nm'-pkg-config = '/usr/local/bin/aarch64-android-pkg-config'-[properties]-sys_root = '/opt/ndk/toolchains/llvm/prebuilt/linux-x86_64/sysroot'-pkg_config_libdir = ['/opt/deps/lib/pkgconfig']-c_args = ['--sysroot=/opt/ndk/toolchains/llvm/prebuilt/linux-x86_64/sysroot', '-target', 'aarch64-linux-android26', '-I/opt/deps/include', '-fPIC', '-O2', '-march=armv8-a']-cpp_args = ['--sysroot=/opt/ndk/toolchains/llvm/prebuilt/linux-x86_64/sysroot', '-target', 'aarch64-linux-android26', '-I/opt/deps/include', '-fPIC', '-O2', '-march=armv8-a']-c_link_args = ['--sysroot=/opt/ndk/toolchains/llvm/prebuilt/linux-x86_64/sysroot', '-target', 'aarch64-linux-android26', '-L/opt/deps/lib', '-Wl,-z,max-page-size=16384']-cpp_link_args = ['--sysroot=/opt/ndk/toolchains/llvm/prebuilt/linux-x86_64/sysroot', '-target', 'aarch64-linux-android26', '-L/opt/deps/lib', '-Wl,-z,max-page-size=16384']-[host_machine]-system = 'linux'-cpu_family = 'aarch64'-cpu = 'aarch64'-endian = 'little'-EOF+COPY build-tools/cross-android-aarch64.ini /opt/cross-android-aarch64.ini# Deps (pcre2, libffi, libiconv, glib, pixman, libattr, libucontext)RUN wget -q https://github.com/PCRE2Project/pcre2/releases/download/pcre2-10.44/pcre2-10.44.tar.gz && tar xf pcre2-10.44.tar.gz && cd pcre2-10.44 && ./configure --host=aarch64-linux-android --prefix=${PREFIX} --enable-static --disable-shared CC="${CC}" && make -j$(nproc) installdiff --git a/README.md b/README.mdindex 4fe1b55..f7e225b 100644--- a/README.md+++ b/README.md@@ -12,7 +12,7 @@ A real Alpine Linux VM with its own kernel - not a chroot or proot trick - so **[](https://github.com/ExTV/Podroid/releases)[](https://github.com/ExTV/Podroid/stargazers)[](LICENSE)-+[**Website**](https://extv.github.io/Podroid/) · [**Documentation**](https://extv.github.io/Podroid/guide/) · [**Download APK**](https://github.com/ExTV/Podroid/releases/latest)@@ -35,7 +35,7 @@ A real Alpine Linux VM with its own kernel - not a chroot or proot trick - so **- **In-app terminal** - full xterm-256color, 122 color themes, 13 fonts, live resize- **X11 desktop** - run GUI Linux apps in a built-in viewer with touch, keyboard, mouse and audio- **USB passthrough**, **SSH**, **port forwarding** and a **guest-to-Android bridge**-- **English and 中文**, no root, any arm64 device on Android 9++- **English and 中文**, no root, any arm64 device on Android 8+## Quick startdiff --git a/build-tools/cross-android-aarch64.ini b/build-tools/cross-android-aarch64.ininew file mode 100644index 0000000..db70048--- /dev/null+++ b/build-tools/cross-android-aarch64.ini@@ -0,0 +1,20 @@+[binaries]+c = '/opt/ndk/toolchains/llvm/prebuilt/linux-x86_64/bin/aarch64-linux-android26-clang'+cpp = '/opt/ndk/toolchains/llvm/prebuilt/linux-x86_64/bin/aarch64-linux-android26-clang++'+ar = '/opt/ndk/toolchains/llvm/prebuilt/linux-x86_64/bin/llvm-ar'+strip = '/opt/ndk/toolchains/llvm/prebuilt/linux-x86_64/bin/llvm-strip'+ranlib = '/opt/ndk/toolchains/llvm/prebuilt/linux-x86_64/bin/llvm-ranlib'+nm = '/opt/ndk/toolchains/llvm/prebuilt/linux-x86_64/bin/llvm-nm'+pkg-config = '/usr/local/bin/aarch64-android-pkg-config'+[properties]+sys_root = '/opt/ndk/toolchains/llvm/prebuilt/linux-x86_64/sysroot'+pkg_config_libdir = ['/opt/deps/lib/pkgconfig']+c_args = ['--sysroot=/opt/ndk/toolchains/llvm/prebuilt/linux-x86_64/sysroot', '-target', 'aarch64-linux-android26', '-I/opt/deps/include', '-fPIC', '-O2', '-march=armv8-a']+cpp_args = ['--sysroot=/opt/ndk/toolchains/llvm/prebuilt/linux-x86_64/sysroot', '-target', 'aarch64-linux-android26', '-I/opt/deps/include', '-fPIC', '-O2', '-march=armv8-a']+c_link_args = ['--sysroot=/opt/ndk/toolchains/llvm/prebuilt/linux-x86_64/sysroot', '-target', 'aarch64-linux-android26', '-L/opt/deps/lib', '-Wl,-z,max-page-size=16384']+cpp_link_args = ['--sysroot=/opt/ndk/toolchains/llvm/prebuilt/linux-x86_64/sysroot', '-target', 'aarch64-linux-android26', '-L/opt/deps/lib', '-Wl,-z,max-page-size=16384']+[host_machine]+system = 'linux'+cpu_family = 'aarch64'+cpu = 'aarch64'+endian = 'little'