From 15a541d7459d914e19d62396ed590e5f66570c77 Mon Sep 17 00:00:00 2001 From: xXJsonDeruloXx Date: Tue, 29 Sep 2026 08:39:30 -0400 Subject: [PATCH] test: cover the sandbox planner and store helpers; docs: explain Flatpak on DroidDeck --- README.md | 2 +- .../droiddeck/launcher/core/FileUtils.java | 1 + .../launcher/runtime/BwrapSpawner.kt | 2 +- .../launcher/runtime/FlatpakManager.kt | 26 +++- .../launcher/runtime/BwrapSpawnerTest.kt | 127 ++++++++++++++++++ .../launcher/store/FlathubApiTest.kt | 20 +++ docs/development/flatpak.md | 67 +++++++++ tools/proot/PATCHES.md | 7 + 8 files changed, 247 insertions(+), 5 deletions(-) create mode 100644 app/src/test/java/com/droiddeck/launcher/runtime/BwrapSpawnerTest.kt create mode 100644 app/src/test/java/com/droiddeck/launcher/store/FlathubApiTest.kt create mode 100644 docs/development/flatpak.md diff --git a/README.md b/README.md index 664860498..a71461045 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ DroidDeck brings the SteamOS experience to Android: Valve's Steam client in Big ## Requirements and install -Use Android 9 or newer on a supported Adreno device (730 or newer, or 8xx). Mali, Xclipse, PowerVR, and Adreno 710 are unsupported. No root is required. Allow about 3 GB for the runtime and 1.1 GB more for the desktop and emulators. Install the APK from [Releases](https://github.com/The412Banner/DroidDeck/releases), install the Linux runtime, then press **Play** and sign in. Steam downloads on first launch. Install **Desktop & apps** to use the desktop and emulators. +Use Android 9 or newer on a supported Adreno device (730 or newer, or 8xx). Mali, Xclipse, PowerVR, and Adreno 710 are unsupported. No root is required. Allow about 3 GB for the runtime and 1.1 GB more for the desktop and emulators. Install the APK from [Releases](https://github.com/The412Banner/DroidDeck/releases), install the Linux runtime, then press **Play** and sign in. Steam downloads on first launch. Install **Desktop & apps** to use the desktop and emulators. The **Store** installs Linux apps and games from Flathub (ARM64 builds) with Flatpak; see [docs/development/flatpak.md](docs/development/flatpak.md). On Android 12+, if Steam exits without a log, turn off **Restrict child processes** in Developer options. diff --git a/app/src/main/java/com/droiddeck/launcher/core/FileUtils.java b/app/src/main/java/com/droiddeck/launcher/core/FileUtils.java index 42008fb97..8190e2877 100644 --- a/app/src/main/java/com/droiddeck/launcher/core/FileUtils.java +++ b/app/src/main/java/com/droiddeck/launcher/core/FileUtils.java @@ -104,6 +104,7 @@ public final class FileUtils { public static String sizeToString(long bytes) { if (bytes >= 1L << 30) return String.format(java.util.Locale.US, "%.1f GB", bytes / (float) (1L << 30)); if (bytes >= 1L << 20) return String.format(java.util.Locale.US, "%.0f MB", bytes / (float) (1L << 20)); + if (bytes >= 1L << 10) return String.format(java.util.Locale.US, "%.0f KB", bytes / (float) (1L << 10)); return bytes + " B"; } } diff --git a/app/src/main/java/com/droiddeck/launcher/runtime/BwrapSpawner.kt b/app/src/main/java/com/droiddeck/launcher/runtime/BwrapSpawner.kt index f5fc7dc17..4e2f2c826 100644 --- a/app/src/main/java/com/droiddeck/launcher/runtime/BwrapSpawner.kt +++ b/app/src/main/java/com/droiddeck/launcher/runtime/BwrapSpawner.kt @@ -196,7 +196,7 @@ object BwrapSpawner { val link = writable(dest) if (link != null) { link.parentFile?.mkdirs() - if (!Files.isSymbolicLink(link.toPath()) && !link.exists()) Os.symlink(target, link.path) + if (!Files.isSymbolicLink(link.toPath()) && !link.exists()) Files.createSymbolicLink(link.toPath(), java.nio.file.Paths.get(target)) } else { // A link inside the runtime's own tree cannot be made; what it points at is // bound in its place. diff --git a/app/src/main/java/com/droiddeck/launcher/runtime/FlatpakManager.kt b/app/src/main/java/com/droiddeck/launcher/runtime/FlatpakManager.kt index 5813b3793..3f8ec9053 100644 --- a/app/src/main/java/com/droiddeck/launcher/runtime/FlatpakManager.kt +++ b/app/src/main/java/com/droiddeck/launcher/runtime/FlatpakManager.kt @@ -164,13 +164,15 @@ object FlatpakManager { if (!ready(context)) return "Set up Flatpak first" return exclusive("$verb:${id ?: "all"}") { var error: String? = null + // Progress lines carry no ref; they belong to the step the last "op" line started. + var step = "Starting" val argv = listOfNotNull("/usr/bin/python3", HELPER, verb, id) val status = runGuest(context, argv, fakeRoot = false) { line -> val o = runCatching { JSONObject(line) }.getOrNull() if (o == null) { Log.i(TAG, "$verb: $line"); return@runGuest } when (o.optString("e")) { - "op" -> onProgress(stage(o), overall(o, 0)) - "progress" -> onProgress(stage(o), overall(o, o.optInt("percent"))) + "op" -> { step = stage(o); onProgress(step, overall(o, 0)) } + "progress" -> onProgress(step, overall(o, o.optInt("percent"))) "error" -> { error = o.optString("message"); Log.w(TAG, "$verb $id: $error") } "warning" -> Log.w(TAG, "$verb $id: ${o.optString("message")}") } @@ -181,7 +183,7 @@ object FlatpakManager { private fun stage(o: JSONObject): String { val ref = o.optString("ref") - val name = ref.split('/').getOrNull(1)?.substringAfterLast('.') ?: "" + val name = refLabel(ref) val step = if (o.optInt("n") > 1) " (${o.optInt("i")}/${o.optInt("n")})" else "" return when (o.optString("kind")) { "uninstall" -> "Removing $name$step" @@ -190,6 +192,24 @@ object FlatpakManager { }.let { if (ref.isEmpty()) o.optString("status").ifEmpty { "Working" } else it } } + /** A ref in words: "app/org.supertuxproject.SuperTux/aarch64/stable" is "SuperTux". */ + internal fun refLabel(ref: String): String { + val parts = ref.split('/') + val id = parts.getOrNull(1) ?: return ref + if (parts.firstOrNull() == "app") return id.substringAfterLast('.') + val branch = parts.getOrNull(3)?.let { " $it" } ?: "" + return when { + id.endsWith(".Locale") -> "translations" + ".GL." in id || ".GL32." in id -> "graphics drivers" + "codecs" in id.lowercase() || id.endsWith(".ffmpeg-full") -> "media codecs" + id.endsWith(".Platform") -> when (val vendor = id.removeSuffix(".Platform").substringAfterLast('.')) { + "gnome", "kde" -> vendor.uppercase() + else -> vendor.replaceFirstChar { it.uppercase() } + } + " runtime$branch" + else -> id.substringAfterLast('.') + } + } + /** The whole transaction's percentage: steps done, plus this one's share. */ private fun overall(o: JSONObject, percent: Int): Int { val n = o.optInt("n").coerceAtLeast(1) diff --git a/app/src/test/java/com/droiddeck/launcher/runtime/BwrapSpawnerTest.kt b/app/src/test/java/com/droiddeck/launcher/runtime/BwrapSpawnerTest.kt new file mode 100644 index 000000000..364c3ef9e --- /dev/null +++ b/app/src/test/java/com/droiddeck/launcher/runtime/BwrapSpawnerTest.kt @@ -0,0 +1,127 @@ +package com.droiddeck.launcher.runtime + +import android.util.Base64 +import org.robolectric.RuntimeEnvironment +import com.droiddeck.launcher.runtime.BwrapSpawner.Bind +import java.io.File +import java.nio.file.Files +import org.json.JSONArray +import org.json.JSONObject +import org.junit.After +import org.junit.Assert.assertEquals +import org.junit.Assert.assertFalse +import org.junit.Assert.assertTrue +import org.junit.Before +import org.junit.Test +import org.junit.runner.RunWith +import org.robolectric.RobolectricTestRunner + +@RunWith(RobolectricTestRunner::class) +class BwrapSpawnerTest { + private val session = listOf( + Bind("/dev", "/dev"), + Bind("/cache/shm", "/dev/shm"), + Bind("/proc", "/proc"), + Bind("/rootfs/etc/bannerlator/proc/stat", "/proc/stat"), + Bind("/data/files", "/data/files"), + ) + + @Test fun underRespectsPathBoundaries() { + assertTrue(BwrapSpawner.under("/usr/lib", "/usr")) + assertTrue(BwrapSpawner.under("/usr", "/usr")) + assertFalse(BwrapSpawner.under("/usrlocal", "/usr")) + assertTrue(BwrapSpawner.under("/anything", "/")) + } + + @Test fun hostPathGoesThroughTheMostSpecificSessionBind() { + assertEquals("/cache/shm/x", BwrapSpawner.hostPath(session, "/rootfs", "/dev/shm/x")) + assertEquals("/dev/null", BwrapSpawner.hostPath(session, "/rootfs", "/dev/null")) + assertEquals("/data/files/.wayland-rt/wayland-1", BwrapSpawner.hostPath(session, "/rootfs", "/data/files/.wayland-rt/wayland-1")) + } + + @Test fun hostPathFallsBackToTheRootfs() { + assertEquals("/rootfs/root/.local/share/flatpak", BwrapSpawner.hostPath(session, "/rootfs/", "/root/.local/share/flatpak")) + } + + @Test fun bindingDevBringsTheSessionsStandInsAlong() { + val binds = BwrapSpawner.bindsFor(session, "/rootfs", "/dev", "/dev") + assertEquals(Bind("/dev", "/dev"), binds.first()) + assertTrue(Bind("/cache/shm", "/dev/shm") in binds) + assertFalse(binds.any { it.guest.startsWith("/proc") }) + } + + @Test fun nestedBindsFollowARenamedDestination() { + val binds = BwrapSpawner.bindsFor(session, "/rootfs", "/proc", "/newproc") + assertTrue(Bind("/rootfs/etc/bannerlator/proc/stat", "/newproc/stat") in binds) + } + + @Test fun normalizeResolvesDotsLexically() { + assertEquals("/usr/lib/x", BwrapSpawner.normalize("/usr/lib/GL/../x")) + assertEquals("/", BwrapSpawner.normalize("/../..")) + } + + @Test fun bindSpecsRoundTrip() { + assertEquals(Bind("/a", "/b"), Bind.parse("/a:/b")) + assertEquals(Bind("/a", "/a"), Bind.parse("/a")) + assertEquals("/a", Bind("/a", "/a").spec) + assertEquals("/a:/b", Bind("/a", "/b").spec) + } +} + +/** The sandbox a Flatpak request describes, built on disk under a temporary directory. */ +@RunWith(RobolectricTestRunner::class) +class BwrapSpawnerPlanTest { + private lateinit var dir: File + private lateinit var runtime: File + + @Before fun setUp() { + dir = Files.createTempDirectory("bwrap-plan").toFile() + // Flatpak names the runtime by its path inside the rootfs. + runtime = File(LinuxRuntime.rootDir(RuntimeEnvironment.getApplication()), "runtime-files") + File(runtime, "lib").mkdirs() + } + + @After fun tearDown() { + dir.deleteRecursively() + runtime.deleteRecursively() + } + + private fun op(vararg pairs: Pair) = JSONObject().apply { pairs.forEach { (k, v) -> put(k, v) } } + + private fun request(vararg ops: JSONObject) = JSONObject() + .put("argv", JSONArray().put("/app/bin/game")) + .put("env", JSONObject().put("FLATPAK_ID", "org.example.Game")) + .put("cwd", "/app") + .put("ops", JSONArray().apply { ops.forEach { put(it) } }) + + @Test fun buildsTheTreeFlatpakAsksFor() { + val context = RuntimeEnvironment.getApplication() + val info = Base64.encodeToString("[Application]\nname=org.example.Game\n".toByteArray(), Base64.NO_WRAP) + val plan = BwrapSpawner.plan(context, request( + op("t" to "bind", "src" to "/runtime-files", "dest" to "/usr", "ro" to true), + op("t" to "symlink", "target" to "usr/lib", "dest" to "/lib"), + op("t" to "dir", "dest" to "/usr/lib/GL", "empty" to true), + op("t" to "symlink", "target" to "default/lib/libEGL.so", "dest" to "/usr/lib/GL/libEGL.so"), + op("t" to "dir", "dest" to "/tmp"), + op("t" to "file", "dest" to "/.flatpak-info", "data" to info, "perms" to 0x180), + op("t" to "bind", "src" to "/nonexistent-${System.nanoTime()}", "dest" to "/run/x", "try" to true), + ), dir) + + // The runtime is bound at /usr, not written into. + assertTrue(plan.binds.any { it.guest == "/usr" && File(it.host).canonicalPath == runtime.canonicalPath }) + assertFalse(File(runtime, "lib/GL").exists()) + // The tmpfs under /usr is a directory of ours, and the link Flatpak makes inside it lands there. + val gl = plan.binds.single { it.guest == "/usr/lib/GL" } + assertTrue(gl.host.startsWith(dir.path)) + assertEquals("default/lib/libEGL.so", Files.readSymbolicLink(File(gl.host, "libEGL.so").toPath()).toString()) + // Top-level links, directories and files are made in the sandbox root itself. + assertEquals("usr/lib", Files.readSymbolicLink(File(plan.root, "lib").toPath()).toString()) + assertTrue(File(plan.root, "tmp").isDirectory) + assertEquals("[Application]\nname=org.example.Game\n", File(plan.root, ".flatpak-info").readText()) + // A --bind-try whose source is missing is left out. + assertFalse(plan.binds.any { it.guest == "/run/x" }) + assertEquals(listOf("/app/bin/game"), plan.argv) + assertEquals("/app", plan.cwd) + assertEquals("org.example.Game", plan.env["FLATPAK_ID"]) + } +} diff --git a/app/src/test/java/com/droiddeck/launcher/store/FlathubApiTest.kt b/app/src/test/java/com/droiddeck/launcher/store/FlathubApiTest.kt new file mode 100644 index 000000000..5aa2dfc2f --- /dev/null +++ b/app/src/test/java/com/droiddeck/launcher/store/FlathubApiTest.kt @@ -0,0 +1,20 @@ +package com.droiddeck.launcher.store + +import com.droiddeck.launcher.runtime.FlatpakManager +import org.junit.Assert.assertEquals +import org.junit.Test + +class FlathubApiTest { + @Test fun appstreamDescriptionsBecomeLines() { + val html = "

A game & more.

Enjoy

" + assertEquals("A game & more.\n• Fast\n• Free\n\nEnjoy", FlathubApi.plainText(html)) + } + + @Test fun refsReadAsWords() { + assertEquals("SuperTux", FlatpakManager.refLabel("app/org.supertuxproject.SuperTux/aarch64/stable")) + assertEquals("GNOME runtime 50", FlatpakManager.refLabel("runtime/org.gnome.Platform/aarch64/50")) + assertEquals("Freedesktop runtime 26.08", FlatpakManager.refLabel("runtime/org.freedesktop.Platform/aarch64/26.08")) + assertEquals("graphics drivers", FlatpakManager.refLabel("runtime/org.freedesktop.Platform.GL.default/aarch64/26.08")) + assertEquals("translations", FlatpakManager.refLabel("runtime/org.gnome.Platform.Locale/aarch64/50")) + } +} diff --git a/docs/development/flatpak.md b/docs/development/flatpak.md new file mode 100644 index 000000000..4c1d389ee --- /dev/null +++ b/docs/development/flatpak.md @@ -0,0 +1,67 @@ +# Flatpak and the Store + +The Store rail section installs apps from Flathub into the Linux runtime with Flatpak. Only +ARM64 builds are listed. Everything lives in one per-user installation at +`/root/.local/share/flatpak`, so nothing needs Flatpak's system helper or polkit. + +## Putting Flatpak in the runtime + +`bannerlator-flatpak-setup` runs under proot's fake root (`-0`), because pacman and pacman-key +refuse any other uid. The runtime's pacman database lists only the base image. The desktop +and emulator packages were unpacked over it without registering. A plain `pacman -S flatpak` +would therefore reinstall about a hundred packages, Mesa among them, over the runtime's KGSL +Turnip build, and run every hook in the image, mkinitcpio included. So pacman, with a +database of its own under `/var/cache/droiddeck-flatpak`, only downloads the nine packages +Flatpak adds to this image and checks their signatures against the Arch Linux ARM keyring. +The script then unpacks them without hooks and checks what the binaries link. Flathub is added +as a per-user remote. + +## bubblewrap without namespaces + +Android gives apps no user namespaces, so `bwrap` cannot work. Flatpak is pointed at +`bannerlator-bwrap` instead (`FLATPAK_BWRAP`, exported by `bannerlator-session` and by the +store's commands). It reads bwrap's command line, including `--args` fds and the `--file` and +`--bind-data` payloads, and then does one of two things: + +- A sandbox that remaps nothing runs directly. Flatpak's install triggers (`--ro-bind / /`) and + the D-Bus proxy (every top-level directory bound onto itself) are the cases, and they keep the + file descriptors Flatpak handed them. +- Anything else is described to the app over the abstract socket + `com.droiddeck.launcher.bwrap`, which serves only the app's own uid. `BwrapSpawner` builds the + tree under `cache/bwrap/`: a root directory for top-level links, directories and files, + scratch directories for `--tmpfs` inside a bind, and every `--bind` translated from guest + to host paths through the session's own binds. It then starts it as a proot of its own + beside the session's. Output, the pid (for `--info-fd`) and the exit status flow back, and + the stand-in exiting kills the sandbox. + +A proot nested in the session's proot would also work, but every system call then goes +through two tracers, about thirty times slower at a program's start. + +The spawner also adds what the rootfs gives its own programs: + +- **GPU.** Flathub's Mesa has Turnip only for DRM, and Adreno on Android is KGSL. The runtime's + own `libvulkan_freedreno.so` is bound in with the three libraries the Freedesktop runtime + lacks (`libdisplay-info`, SPIRV-Tools). Vulkan uses it, and Mesa's GL runs on it through Zink + (`MESA_LOADER_DRIVER_OVERRIDE=zink`). This is skipped for an app drawing into a desktop + composited by pixman, where Zink cannot present. +- **Controllers.** The libraries in the rootfs's `/etc/ld.so.preload` (the session shim and the + fake evdev reader) go in through `LD_PRELOAD`, with the session's `dev` directory. +- **CPU.** `/proc/cpuinfo` without the cores' part numbers. Snapdragon's ARMv9 cores imply SVE2 + to LLVM, Qualcomm leaves SVE off, and llvmpipe's first shader died with SIGILL. + +## Running apps + +The front end starts an app as a run-mode session of `bannerlator-flatpak-run `, full +screen under gamescope. Under gamescope it passes `--nosocket=wayland --socket=x11`. Otherwise +Flatpak finds the app compositor's `wayland-0` and the window opens behind gamescope. The +launcher also starts a session bus when there is none. On the Linux desktop, the apps' exported +menu entries appear in the LXQt menu. While the desktop is composited by pixman, games are +wrapped through `droiddeck-gpu` like the rootfs's own. + +## The store + +`FlathubApi` reads flathub.org's public API: collections, search filtered to `aarch64`, and +AppStream details. `bannerlator-flatpak` drives libflatpak through PyGObject and prints one +JSON object per line (`op`, `progress`, `error`, `done`). `FlatpakManager` turns those lines +into the store's progress bar. Store commands run in a proot of their own, and +`OrphanReaper` spares them when a session starts. diff --git a/tools/proot/PATCHES.md b/tools/proot/PATCHES.md index aa528b746..6a0d99e0e 100644 --- a/tools/proot/PATCHES.md +++ b/tools/proot/PATCHES.md @@ -44,3 +44,10 @@ Ported from WinNative (`main`, 53836ca9, "Fix/performance and vac"): - `0009-tracee-relatives-sweep.patch` - tracees count their children, so a terminating thread with no children or ptracees no longer walks every tracee; the per-stop memory collector is emptied instead of freed and reallocated. + +Added for Flatpak: + +- `0010-new-mount-api-enosys.patch` - `open_tree`, `move_mount`, `fspick` and `mount_setattr` + answer `ENOSYS`. They take paths proot never translated, so libglnx's `open_tree(AT_FDCWD, "/")` + handed Flatpak a descriptor for the host's root and it tried to create directories there + (`mkdirat(root): Operation not permitted`); unsupported, libglnx falls back to `openat`.