From c548155dd91aa1ef35077e9e7defd1aef604b0b4 Mon Sep 17 00:00:00 2001 From: enricobuehler Date: Sun, 14 Jun 2026 11:43:48 +0000 Subject: [PATCH] feat(packaging/arch): Arch + SteamOS install target (PKGBUILD + sysext) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add packaging/arch: a PKGBUILD mirroring the rpm/deb artifact set (binary, udev rule, 32MB sysctl, systemd USER units with ExecStart rewritten, headless helpers, env templates, openapi), a pacman .install scriptlet, a systemd-sysext builder for immutable SteamOS, and a README. Builds the working tree via PF_SRCDIR (CI/dev) or a git tag (AUR). Arch's stock ffmpeg already ships NVENC, so deps collapse to ~10 packages with nvidia-utils/compositors as optdepends (never hard-depend on the driver, same invariant as rpm/deb). SteamOS delivery is a **systemd-sysext** (overlays /usr read-only from writable /var/lib/extensions/, survives A/B OS updates, no steamos-readonly disable) — pacman/distrobox/flatpak are all unsuitable for a host that needs uinput/uhid, the host PipeWire socket, the GPU node, and to spawn a compositor. KNOWN GAP, documented prominently: encode is NVENC-only (src/encode/linux.rs has no VAAPI backend), so this works on Arch+NVIDIA (and bazzite-deck-nvidia) but an AMD Steam Deck installs yet cannot encode until a hevc_vaapi backend is written — a code change, not packaging. Co-Authored-By: Claude Opus 4.8 (1M context) --- packaging/arch/PKGBUILD | 98 +++++++++++++++++++++++++++ packaging/arch/README.md | 70 +++++++++++++++++++ packaging/arch/build-sysext.sh | 39 +++++++++++ packaging/arch/punktfunk-host.install | 25 +++++++ 4 files changed, 232 insertions(+) create mode 100644 packaging/arch/PKGBUILD create mode 100644 packaging/arch/README.md create mode 100755 packaging/arch/build-sysext.sh create mode 100644 packaging/arch/punktfunk-host.install diff --git a/packaging/arch/PKGBUILD b/packaging/arch/PKGBUILD new file mode 100644 index 0000000..00b0ce1 --- /dev/null +++ b/packaging/arch/PKGBUILD @@ -0,0 +1,98 @@ +# Maintainer: unom +# +# Arch Linux / SteamOS package for the punktfunk streaming HOST. Mirrors the artifact +# set of packaging/rpm/punktfunk.spec and packaging/debian/build-deb.sh exactly. +# +# Two build modes: +# - AUR / standalone: makepkg in this dir (fetches the git tag below). +# - In-tree / CI: PF_SRCDIR=$(git rev-parse --show-toplevel) makepkg --holdver +# (builds the working tree instead of the tagged source — see build()). +# +# IMPORTANT: encode is NVENC-only (crates/punktfunk-host/src/encode/linux.rs). This package is +# functional on NVIDIA hosts (nvidia-utils + Arch's NVENC-enabled ffmpeg). On an AMD Steam Deck +# it installs but CANNOT encode until a VAAPI (hevc_vaapi) backend exists — see packaging/arch/README.md. +pkgname=punktfunk-host +pkgver=0.0.1 +pkgrel=1 +pkgdesc="Low-latency desktop/game streaming host (Moonlight-compatible + punktfunk/1)" +arch=('x86_64') +url="https://git.unom.io/unom/punktfunk" +license=('MIT OR Apache-2.0') + +# Runtime libs the binary links or drives. NVENC + GPU EGL/CUDA come from the NVIDIA driver +# (nvidia-utils) — kept an optdepend, never a hard dep, exactly as the RPM (__requires_exclude +# libcuda) and deb (shlibdeps grep-filter) do: the driver is installed out of band. +depends=( + 'ffmpeg' # libavcodec/format/util — Arch's ffmpeg ships hevc_nvenc/av1_nvenc + 'pipewire' # capture + audio transport + 'pipewire-pulse' # desktop audio bridge + 'wireplumber' # PipeWire session manager + 'opus' # GameStream/punktfunk Opus audio + 'libei' # input injection (RemoteDesktop portal / EIS) + 'mesa' # libgbm (+ EGL on non-NVIDIA) + 'libglvnd' # libGL/libEGL loader + 'libxkbcommon' # virtual keyboard keymap + 'wayland' # wayland-client (vdisplay backends) +) +optdepends=( + 'nvidia-utils: NVENC hardware encode + GPU EGL/CUDA zero-copy (REQUIRED to encode on NVIDIA)' + 'gamescope: per-session nested compositor backend (no desktop login needed) — needs >=3.16.22' + 'kwin: stream a KDE Plasma desktop (kwin VirtualDisplay backend)' + 'mutter: stream a GNOME desktop (Mutter RecordVirtual backend)' + 'sway: stream a wlroots desktop (Sway VirtualDisplay backend)' + 'xdg-desktop-portal-kde: portal for the headless KDE session helper' + 'xdg-desktop-portal-wlr: portal for the headless Sway session helper' +) +makedepends=('rust' 'cargo' 'clang' 'cmake' 'nasm' 'pkgconf' 'git') + +# AUR source (a tagged release). For an in-tree CI build, set PF_SRCDIR to the repo root and +# build() uses it instead; see the README. +source=("git+https://git.unom.io/unom/punktfunk.git#tag=v${pkgver}") +sha256sums=('SKIP') +install="${pkgname}.install" + +_repo() { printf '%s' "${PF_SRCDIR:-$srcdir/punktfunk}"; } + +build() { + cd "$(_repo)" + export RUSTUP_TOOLCHAIN=stable CARGO_TARGET_DIR="$srcdir/target" + # The zero-copy FFI link-needs libcuda at build time; nvidia-utils provides it on an NVIDIA + # builder. On a GPU-less builder, symlink the CUDA stub into the link path first (same caveat + # the RPM documents): ln -s "$(find / -name libcuda.so -path '*stubs*' | head -1)" /usr/lib/ + cargo build --release --locked -p punktfunk-host +} + +package() { + local R; R="$(_repo)"; local T="$srcdir/target/release" + + install -Dm0755 "$T/punktfunk-host" "$pkgdir/usr/bin/punktfunk-host" + + # /dev/uinput + /dev/uhid -> input group (virtual gamepads + DualSense UHID) + install -Dm0644 "$R/scripts/60-punktfunk.rules" "$pkgdir/usr/lib/udev/rules.d/60-punktfunk.rules" + # 32 MB UDP socket buffers (send-side headroom at high bitrate) + install -Dm0644 "$R/scripts/99-punktfunk-net.conf" "$pkgdir/usr/lib/sysctl.d/99-punktfunk-net.conf" + + # systemd USER units (the host runs in the graphical session, not as root); the source units + # point at the dev tree — repoint ExecStart at the installed paths (mirrors rpm/deb). + install -Dm0644 "$R/scripts/punktfunk-host.service" "$pkgdir/usr/lib/systemd/user/punktfunk-host.service" + sed -i 's#%h/punktfunk/target/release/punktfunk-host#/usr/bin/punktfunk-host#' \ + "$pkgdir/usr/lib/systemd/user/punktfunk-host.service" + install -Dm0644 "$R/scripts/punktfunk-kde-session.service" "$pkgdir/usr/lib/systemd/user/punktfunk-kde-session.service" 2>/dev/null || true + [ -f "$pkgdir/usr/lib/systemd/user/punktfunk-kde-session.service" ] && \ + sed -i 's#%h/punktfunk/scripts/headless/run-headless-kde.sh#/usr/share/punktfunk/headless/run-headless-kde.sh#' \ + "$pkgdir/usr/lib/systemd/user/punktfunk-kde-session.service" + + # headless session helpers + env templates + OpenAPI doc + install -Dm0755 "$R/scripts/headless/run-headless-kde.sh" "$pkgdir/usr/share/punktfunk/headless/run-headless-kde.sh" + install -Dm0755 "$R/scripts/headless/run-headless-sway.sh" "$pkgdir/usr/share/punktfunk/headless/run-headless-sway.sh" + install -Dm0644 "$R/scripts/headless/kde-authorized" "$pkgdir/usr/share/punktfunk/headless/kde-authorized" + install -Dm0644 "$R/scripts/headless/punktfunk-sink.conf" "$pkgdir/usr/share/punktfunk/headless/punktfunk-sink.conf" + install -Dm0644 "$R/scripts/host.env.example" "$pkgdir/usr/share/punktfunk/host.env.example" + install -Dm0644 "$R/packaging/bazzite/host.env" "$pkgdir/usr/share/punktfunk/host.env.bazzite" + install -Dm0644 "$R/packaging/kde/host.env" "$pkgdir/usr/share/punktfunk/host.env.kde" + install -Dm0644 "$R/docs/api/openapi.json" "$pkgdir/usr/share/punktfunk/openapi.json" + + install -Dm0644 "$R/LICENSE-MIT" "$pkgdir/usr/share/licenses/$pkgname/LICENSE-MIT" + install -Dm0644 "$R/LICENSE-APACHE" "$pkgdir/usr/share/licenses/$pkgname/LICENSE-APACHE" + install -Dm0644 "$R/README.md" "$pkgdir/usr/share/doc/$pkgname/README.md" +} diff --git a/packaging/arch/README.md b/packaging/arch/README.md new file mode 100644 index 0000000..c6eb9d3 --- /dev/null +++ b/packaging/arch/README.md @@ -0,0 +1,70 @@ +# punktfunk on Arch Linux / SteamOS + +Packaging for the punktfunk streaming **host** on Arch and Arch-derived immutable distros +(SteamOS 3, etc.). Mirrors the artifact set of `packaging/rpm/punktfunk.spec` and +`packaging/debian/build-deb.sh`. + +> ⚠️ **Encode is NVENC-only today.** `crates/punktfunk-host/src/encode/linux.rs` implements +> `hevc_nvenc`/`av1_nvenc`/`h264_nvenc` and a CUDA zero-copy path — there is **no VAAPI backend**. +> So this package is functional on **Arch + NVIDIA** (the realistic target). On an **AMD Steam +> Deck it installs but cannot encode** until a `hevc_vaapi`/`av1_vaapi` encoder is added in +> `src/encode/` — a code change, not a packaging one. (`bazzite-deck-nvidia`, i.e. SteamOS-style +> images running on NVIDIA hardware, work fine — they're NVIDIA.) + +## Arch Linux (mutable) + +```sh +cd packaging/arch +# Build the working tree (CI / dev) — no git fetch: +PF_SRCDIR="$(git rev-parse --show-toplevel)" makepkg -f --holdver +# …or build the tagged release the AUR way: +makepkg -si +``` +Then the standard first-run (printed by the install scriptlet): +```sh +sudo usermod -aG input "$USER" # virtual gamepads; re-login after +mkdir -p ~/.config/punktfunk +cp /usr/share/punktfunk/host.env.bazzite ~/.config/punktfunk/host.env # gamescope backend +systemctl --user enable --now punktfunk-host +``` +NVENC/EGL come from the NVIDIA driver: `sudo pacman -S --needed nvidia-utils`. Arch's stock +`ffmpeg` already has NVENC built in — no RPM-Fusion-style swap needed (unlike Fedora). + +### Runtime dependency map (Fedora/Debian → Arch) + +| Need | Arch package | +|------|--------------| +| FFmpeg + NVENC | `ffmpeg` (NVENC built in) | +| PipeWire + Pulse + session mgr | `pipewire` `pipewire-pulse` `wireplumber` | +| Opus / input injection | `opus` `libei` | +| GL/EGL + gbm + xkb + wayland | `libglvnd` `mesa` `libxkbcommon` `wayland` | +| NVIDIA driver (NVENC/EGL/CUDA) | `nvidia-utils` *(optdepend — never a hard dep)* | +| Compositor backends | `gamescope` (≥3.16.22) / `kwin` / `mutter` / `sway` *(optdepends)* | + +## SteamOS 3 (immutable) — use a systemd-sysext + +SteamOS has a **read-only `/usr` on A/B partitions**, and every OS update reimages the rootfs — +so `steamos-readonly disable` + `pacman` (and flatpak/distrobox) are fragile or unusable for a +host that needs `/dev/uinput`, `/dev/uhid`, the host PipeWire socket, the GPU render node, and the +right to spawn a compositor. The update-survivable, SteamOS-blessed mechanism is a +**systemd-sysext**: an overlay image merged read-only over `/usr` at boot, living in the writable +`/var/lib/extensions/` (so it persists across A/B updates, no readonly-disable). + +Build the package, then wrap its `/usr` payload into a sysext image: +```sh +# 1. build the pacman package (needs an Arch environment / container) +cd packaging/arch && PF_SRCDIR="$(git rev-parse --show-toplevel)" makepkg -f --holdver +# 2. turn it into a sysext .raw (extracts the package's /usr into an image + extension-release) +bash build-sysext.sh punktfunk-host-*.pkg.tar.zst +# 3. on the SteamOS box: +sudo cp punktfunk-host.raw /var/lib/extensions/ +sudo systemctl enable --now systemd-sysext # merges it; survives OS updates +systemctl --user enable --now punktfunk-host # the user unit is now under /usr/lib +``` +The udev rule, sysctl, and systemd **user** unit all live under `/usr/lib`, so the merged sysext +exposes them. `systemd-sysext refresh` re-merges after a reboot. + +## Files +- `PKGBUILD` — the package recipe (builds the working tree via `PF_SRCDIR`, or a git tag for AUR). +- `punktfunk-host.install` — pacman scriptlet (udev reload + sysctl + first-run hint), mirrors RPM `%post`. +- `build-sysext.sh` — wraps a built `.pkg.tar.zst` into a `systemd-sysext` `.raw` for SteamOS. diff --git a/packaging/arch/build-sysext.sh b/packaging/arch/build-sysext.sh new file mode 100755 index 0000000..5219fb8 --- /dev/null +++ b/packaging/arch/build-sysext.sh @@ -0,0 +1,39 @@ +#!/usr/bin/env bash +# Wrap a built punktfunk-host pacman package into a systemd-sysext image — the update-survivable +# way to add the host to an immutable Arch-derived distro (SteamOS 3): the .raw overlays /usr +# read-only from the writable /var/lib/extensions/, so it persists across A/B OS updates with no +# `steamos-readonly disable`. Needs `bsdtar`/`tar`, `squashfs-tools` (mksquashfs). +# +# Usage: bash build-sysext.sh +# Output: punktfunk-host.raw +set -euo pipefail + +PKG="${1:?usage: build-sysext.sh }" +[ -f "$PKG" ] || { echo "no such package: $PKG" >&2; exit 1; } +NAME=punktfunk-host + +STAGE="$(mktemp -d)" +trap 'rm -rf "$STAGE"' EXIT + +# A pacman package is a (zstd) tarball; a sysext only carries /usr (the host /etc, /var are the +# system's). Extract just usr/ from the payload. +if command -v bsdtar >/dev/null 2>&1; then + bsdtar -C "$STAGE" -xf "$PKG" usr +else + tar -C "$STAGE" -xf "$PKG" usr +fi + +# The marker systemd-sysext requires to merge the image. ID=_any merges onto ANY host os-release +# (SteamOS, Arch, Bazzite); ARCHITECTURE pins it to x86-64 so it's never merged on the wrong arch. +install -d "$STAGE/usr/lib/extension-release.d" +cat > "$STAGE/usr/lib/extension-release.d/extension-release.$NAME" </dev/null || true + udevadm trigger --subsystem-match=misc 2>/dev/null || true + # Apply the UDP socket-buffer tuning now (also auto-applied at boot by systemd-sysctl). + sysctl -p /usr/lib/sysctl.d/99-punktfunk-net.conf >/dev/null 2>&1 || true + cat <<'MSG' +punktfunk-host installed. + 1. Add yourself to the 'input' group for virtual gamepads: + sudo usermod -aG input "$USER" # then re-login + 2. Pick a backend config (gamescope is the no-desktop default on SteamOS/Deck): + mkdir -p ~/.config/punktfunk + cp /usr/share/punktfunk/host.env.bazzite ~/.config/punktfunk/host.env + 3. Enable the host: + systemctl --user enable --now punktfunk-host + +NOTE: encode is NVENC-only. Install 'nvidia-utils' on an NVIDIA host. An AMD Steam Deck is NOT + yet supported — it needs a VAAPI (hevc_vaapi) encoder backend (see packaging/arch/README.md). +MSG +} + +post_upgrade() { + udevadm control --reload-rules 2>/dev/null || true + sysctl -p /usr/lib/sysctl.d/99-punktfunk-net.conf >/dev/null 2>&1 || true +}