Skip to content

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.md
index 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.md
index 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.sh
diff --git a/Dockerfile b/Dockerfile
index 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) install
diff --git a/README.md b/README.md
index 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 **
[![Downloads](https://img.shields.io/github/downloads/ExTV/Podroid/total?style=flat-square&color=brightgreen)](https://github.com/ExTV/Podroid/releases)
[![Stars](https://img.shields.io/github/stars/ExTV/Podroid?style=flat-square&color=yellow)](https://github.com/ExTV/Podroid/stargazers)
[![License](https://img.shields.io/github/license/ExTV/Podroid?style=flat-square)](LICENSE)
-![Android 9+](https://img.shields.io/badge/Android-9%2B-3DDC84?style=flat-square&logo=android&logoColor=white)
+![Android 8+](https://img.shields.io/badge/Android-8%2B-3DDC84?style=flat-square&logo=android&logoColor=white)
![arm64](https://img.shields.io/badge/arch-arm64-orange?style=flat-square)
[**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 start
diff --git a/build-tools/cross-android-aarch64.ini b/build-tools/cross-android-aarch64.ini
new file mode 100644
index 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'