Files

T

mollusk 69ddc58133 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>

2026-05-28 16:29:05 -04:00

3.4 KiB

Raw Blame History

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/:

# 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.

3.4 KiB Raw Blame History