Files
DroidDeck/tools/ubuntu/README.md
T
MaxsTechReview 2b790a8a71 fix(runtime): keep the Linux desktop installed across a runtime update (#2021)
* fix(runtime): keep the Linux desktop installed across a runtime update

A runtime update replaces the whole runtime tree, and the desktop pack
is built against one runtime, so every update removed the installed
desktop. Since the runtime started updating by itself, this happened
without the user doing anything: the next Open showed "Install & open"
and downloaded the whole desktop again.

When the desktop was installed before the update, the same update job
now installs the new runtime's desktop pack right after the runtime,
with the update's progress. If that install fails, the runtime update
still counts as done and Open offers the install as before. A repair
from the session no longer installs the desktop a second time when the
runtime install already did.

* fix(runtime): roll back a failed desktop restore after a runtime update

If putting the desktop back fails after its archive started unpacking,
the install journal stayed behind, and every later launch, Steam
included, tried to resume it and stopped when that failed. The update
now rolls back the partial desktop with the desktop removal, which
restores the runtime's own files and clears the journal. Open then
offers the desktop install as before.

Whether the desktop was installed is now checked on its own, so a
repair of a damaged runtime also restores it.

* fix(session): do not install the desktop again after resuming it

Opening the desktop with an interrupted desktop install resumed that
install and then installed the desktop a second time. The second
install is now skipped when the resume already completed the desktop.
2026-11-02 21:20:18 -05:00

50 lines
3.8 KiB
Markdown

# The Linux runtime (Ubuntu)
DroidDeck's Linux runtime: Ubuntu 26.04 LTS for arm64, with Kubuntu's Plasma desktop as a separate download, set up as
SteamOS's desktop mode (Valve's Vapor theme, the Steam Deck wallpaper, "Return to Gaming Mode" and
Steam on the desktop). The app installs it into `files/linuxfs` and runs it under its patched proot.
- `build-debs.sh` (run in an `ubuntu:26.04` container on an arm64 runner) rebuilds two Ubuntu source
packages: Mesa with `-Dfreedreno-kmds=msm,kgsl`, so Turnip and freedreno reach Android's
`/dev/kgsl-3d0`, and KWin with `patches/kwin` (nested desktop scale, an explicit render node,
scroll source/discrete forwarding). Both get a `+droiddeck` version. `patches/mesa` adds KGSL
UBWC 5/6 (backported from upstream Mesa) and the KGSL device numbers for WSI (from
[Droid-Deck/Drivers](https://github.com/Droid-Deck/Drivers)).
- The runtime's built-in Vulkan driver is DroidDeck's DD-Turnip Linux build (`DD_TURNIP_URL` and
`DD_TURNIP_SHA256` in `base.env`): Ubuntu's Turnip is diverted to `libvulkan_freedreno.so.distrib`
because it lacks the Adreno 8xx fixes. Zink, EGL and llvmpipe stay Ubuntu's.
- `build.sh` verifies Ubuntu's base image (`base.env`: signed `SHA256SUMS` from cdimage plus the
pinned hash), chroots into it and runs `setup.sh` twice. The `runtime` stage is everything gaming
mode needs; it is packed as `<tag>.tar.zst`. The `desktop` stage then adds Plasma on top, and
`desktop-pack.py` packs only what that stage added or changed as `<tag>-desktop.tar.zst`, so the
desktop shares every runtime file instead of shipping its own copy. The runtime carries
`usr/share/droiddeck/desktop-pack.json` (tag, URL, hash, size) naming its matching desktop pack.
- `setup.sh runtime` installs `packages-runtime.txt` without recommends and the `+droiddeck` debs from
a local repository in `/var/lib/droiddeck/apt` (pinned at 1001 and held), then builds the
`droiddeck-runtime` package from `overlay-runtime/`. `setup.sh desktop` installs
`packages-desktop.txt`, Firefox from Mozilla's apt repository (`mozilla.asc`, fingerprint
35BAA0B33E9EB396F59CA838C0BA5CE6DC6315A3) and builds `droiddeck-desktop` from `overlay-desktop/`.
Both packages are Protected, depend on `protected-*.txt`, own our files and divert any Ubuntu file
they replace, so apt neither removes the essentials nor overwrites our settings on upgrade.
- The desktop pack's `usr/share/droiddeck/desktop/files.tsv.gz` lists each path the desktop added
(N), changed (C) or removed (R), and `originals/` keeps the runtime's copies of changed and removed
files. Removing the desktop restores those and deletes the added files the user has not changed;
a runtime update replaces the tree, so when the desktop was installed the update installs the new
runtime's desktop pack right after it.
At run time:
- `sudo`, `su`, `pkexec` and apt/aptitude (for commands that change the system) go through
`droiddeck-root`: the app runs them in a separate proot with `-0 --link2symlink`, passing the
caller's terminal, so dpkg gets root ownership emulation and hard links while the desktop keeps
the fast path. PackageKit (Discover) and polkit are started the same way by the session's system
bus (`/usr/share/droiddeck/system-services`).
- `apt/remember` (a `DPkg::Post-Invoke` hook) keeps the packages, sources and keys the user added in
`~/.local/share/droiddeck/apt`; `apt/restore` (autostarted) puts them back after a runtime update.
- The installer turns the image's hard links into proot's link2symlink layout, and proot shows the
linked name as `/proc/self/exe` (patch 0020), so Ubuntu's multi-call coreutils work.
`.github/workflows/build-ubuntu-runtime.yml` builds it and, run with a new tag (`ubuntu-rN`),
publishes the runtime and its desktop pack in Droid-Deck/DroidDeck-Components; `linuxfs-ubuntu.json` there names the release the
app installs.