feat(packaging): honour CARGO_TARGET_DIR + document distrobox build

build-appimage.sh now reads the binary from CARGO_TARGET_DIR when set, so a
broad-compat build inside an old-glibc distrobox can use an isolated target
dir without clobbering the host's. README documents the Ubuntu 24.04
distrobox recipe and why older bases don't work (the pipewire crate needs
PW >= ~1.0 headers; and a PipeWire/portal app can't run on ancient distros
anyway). Resulting baseline: glibc 2.39 (the only 2.39 symbols are weak
pidfd refs from Rust std; everything else is <= 2.35).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

packaging/appimage/README.md

@@ -33,9 +33,40 @@ The AppImage runs on any reasonably current glibc-based distro that has:
 These are the same dependencies the Arch package lists; the AppImage just spares
 you the Rust toolchain.
 
+## Building for broad compatibility (lower glibc baseline)
+
+An AppImage requires a host glibc **at least as new** as the build host's. Built
+straight on a rolling distro (e.g. CachyOS, glibc 2.43) the AppImage only runs
+on equally-new systems. Build inside an older base for wider reach. The script
+honours `CARGO_TARGET_DIR`, so an isolated toolchain won't clobber your host's
+`target/`:
+
+```sh
+# One-time: an Ubuntu 24.04 distrobox (docker or podman backend).
+distrobox create --yes --image ubuntu:24.04 --name pixelpass-build
+distrobox enter pixelpass-build -- sudo apt-get update
+distrobox enter pixelpass-build -- sudo apt-get install -y \
+  build-essential cmake clang libclang-dev pkg-config \
+  libpipewire-0.3-dev libspa-0.2-dev curl ca-certificates file
+# Install rustup inside the box (edition 2024 needs rustc >= 1.85), then:
+distrobox enter pixelpass-build -- env \
+  CARGO_TARGET_DIR=~/.cache/pixelpass-ubuntu/target \
+  ./packaging/appimage/build-appimage.sh
+```
+
+**Why Ubuntu 24.04 and not something older:** PixelPass's `pipewire` crate
+binds the system's PipeWire headers via bindgen, and anything older than ~PW 1.0
+(e.g. Ubuntu 22.04's 0.3.48) fails to compile (missing struct fields / wrong
+types). And since PixelPass *is* a PipeWire/portal/Wayland app, it can only run
+on distros new enough to have modern PipeWire anyway — so an ancient glibc base
+buys nothing. 24.04 (glibc 2.39, PW 1.0.5) is the sweet spot.
+
+The 24.04-built binary's baseline is **glibc 2.39** — and the only 2.39 symbols
+are two *weak* `pidfd_*` references from Rust std's process spawning (everything
+else is ≤ 2.35). That covers Ubuntu 24.04+, Debian 13+, Fedora 40+, and current
+rolling distros.
+
 ## Caveats
 
-- **Built on a bleeding-edge glibc** (CachyOS), so the AppImage requires a host
-  glibc at least that new. For broad compatibility, rebuild on an older base.
 - **Hardware encode (VAAPI `vah264enc`)** uses the host GPU driver; it can't be
   bundled. The software path (`--no-hwencode`, x264) always works.

packaging/appimage/build-appimage.sh

@@ -25,7 +25,9 @@ export VERSION
 
 echo ">> building release binary (--features gui)"
 ( cd "$repo" && cargo build --release --features gui )
-bin="$repo/target/release/pixelpass"
+# Honour CARGO_TARGET_DIR so an isolated build (e.g. inside an old-glibc
+# distrobox) doesn't have to clobber the host's target/.
+bin="${CARGO_TARGET_DIR:-$repo/target}/release/pixelpass"
 
 echo ">> fetching linuxdeploy"
 ld="$tools/linuxdeploy-x86_64.AppImage"