mollusk
69ddc58133
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>
73 lines
3.4 KiB
Markdown
73 lines
3.4 KiB
Markdown
# PixelPass AppImage
|
|
|
|
A "thin" AppImage: the gui-enabled `pixelpass` binary, a launcher (`AppRun`),
|
|
and the desktop entry + icon. Run `./build-appimage.sh` to produce
|
|
`pixelpass-<version>-x86_64.AppImage`.
|
|
|
|
## Why thin
|
|
|
|
`pixelpass` is an orchestrator — it links almost nothing (only `libpipewire`,
|
|
which is excludelisted because it must match the host daemon) and instead
|
|
**shells out** to `gst-launch-1.0`, `pactl`, and a player (`mpv`/`vlc`) found on
|
|
the host `PATH`. The GUI's graphics libraries (`libGL`, `libwayland-*`,
|
|
`libxkbcommon`, X11) are dlopen'd at runtime and are likewise on the AppImage
|
|
excludelist — every desktop already has a matching set. So there is nothing
|
|
useful to bundle, and bundling the graphics stack would only risk driver
|
|
mismatches. The AppImage therefore carries just the binary.
|
|
|
|
This also explains why PixelPass suits AppImage better than Flatpak: the
|
|
no-sandbox model lets the bundled binary freely spawn the host's `gst-launch`,
|
|
`pactl`, and player, which a Flatpak sandbox would block.
|
|
|
|
## Host requirements
|
|
|
|
The AppImage runs on any reasonably current glibc-based distro that has:
|
|
|
|
- **GStreamer + plugins** — `gst-launch-1.0`/`gst-inspect-1.0` plus base,
|
|
good/bad/ugly, libav, and the PipeWire plugin (the binary tells you the exact
|
|
package names for your distro if something is missing).
|
|
- **PipeWire** (with the PulseAudio shim, for `pactl`).
|
|
- **A player** — `mpv` (preferred) or `vlc` — for the viewer side.
|
|
- For X11 single-window capture: `xwininfo`.
|
|
|
|
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
|
|
|
|
- **Hardware encode (VAAPI `vah264enc`)** uses the host GPU driver; it can't be
|
|
bundled. The software path (`--no-hwencode`, x264) always works.
|