Conversation
hikaps
added a commit
that referenced
this pull request
Jun 29, 2026
The install documentation — including the AppImage section — is consolidated into PR #29 so the two PRs cannot conflict on README. This PR is now build-only (scripts + workflow).
Resolve two install failures reported in #28: 1. couchplay-helper.service failed to start (Type=dbus unit exited 1). install-helper.sh masked D-Bus config-reload failures with || true, so the helper's ownership policy was never loaded and it could not register its service name. reload_dbus() now retries via SIGHUP on the pid file, failures are surfaced (not masked), and a failed start dumps the last 30 journalctl lines. 2. Flatpak export wrote to the sandbox home (~/.var/app/...) while the README/host command looked in ~/.local/share/couchplay, so the host-side install found nothing. The manifest now grants --filesystem=home and export resolves the real host home from /etc/passwd. README adds an older-build fallback path. Refs #28
Follow-up to the #28 install fixes based on reporter feedback: - Flatpak export was still wrong: writing to $HOME/.local/share inside the sandbox vanishes (the sandbox home is not persisted to the host). Stage to $XDG_DATA_HOME instead, which Flatpak persists to ~/.var/app/<id>/data (host-visible, no extra permission needed). Reverts the unnecessary --filesystem=home (and the profiles behavior change it would introduce). README now points at ~/.var/app/.../data. - The helper service crash on minimal Arch is an exec/load failure: the tarball bundles no runtime libraries, so the Qt6/KF6/Polkit/PipeWire- linked helper can't start where those are missing. install.sh now ldd- checks the helper and aborts with the missing sonames + per-distro install commands instead of an opaque service failure. Refs #28
The release tarball's couchplay-helper is dynamically linked against system Qt6/Polkit/PipeWire but bundles none, so on minimal distros (e.g. Arch) it fails to start — the opaque exit / ERRNO 2 from #28. Bundle the helper's non-glibc runtime libs into lib/couchplay with a $ORIGIN-relative RPATH via patchelf: - scripts/bundle-libs.sh: ldd-gather deps (excluding glibc/ld-linux), copy, patchelf --set-rpath $ORIGIN/../lib/couchplay - release.yml: add patchelf, run bundle-libs.sh in the Package step - install-helper.sh: install/uninstall lib/couchplay to $PREFIX/lib/couchplay The helper now starts with zero system Qt6. glibc/ld-linux stay system-provided, so the binary still has the build container's glibc floor. The GUI still needs system Qt6 — a portable GUI is the AppImage's job (#30). Refs #28
…e priority Lead the install section with a 'which method should I use?' table and order the methods by broad suitability: Flatpak (universal) -> tarball (curl one-liner + manual/Bazzite) -> AppImage (portable GUI). Consolidate the curl quick-install and manual tarball steps under one Tarball section, and fold the AppImage docs in here so this PR owns all install documentation. Refs #28
CouchPlay's entire function depends on the privileged root helper, which cannot run from an AppImage mount and always needs a system install. That nullifies AppImage's core 'just download and run' promise for this app, and Flatpak already covers the universal/portable case (without AppImage's glibc floor). Keep Flatpak + tarball/curl only.
…e() path Address code-review findings on PR #29: - bundle-libs.sh: add --force-rpath so the helper gets DT_RPATH (transitive), not DT_RUNPATH. Without it the bundled transitive libs (Qt6Core's libpcre2/libdouble-conversion/libzstd) are unreachable on minimal systems and the helper still fails to load — defeating the #28 fix. - install-helper.sh: guard the bundled-lib install with compgen -G so an empty lib dir doesn't abort the root install mid-way under set -e (partial install). - install-helper.sh: usage() now prints the resolved $EXPORT_DIR instead of the stale hardcoded ~/.local/share/couchplay (which doesn't exist on host in Flatpak). Finding C (install derefs symlinks) is N/A: bundle-libs.sh uses cp -L upstream, so lib/couchplay holds flattened real files, no symlinks reach the install step.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Fixes the two install failures reported in #28 (reporter is on the stable release from
main; these fixes land ondevelopand flow tomainon the next release).1.
couchplay-helper.servicefails to start (curl/tarball method)The systemd unit is
Type=dbus, so systemd reports "control process exited with error code" when the binary exits non-zero before takingBusName. That phrasing rules out a timeout and203/EXEC(missing lib) — it is the helper's ownreturn 1inhelper/main.cpp, almost certainlyregisterService()being denied because the ownership policy in/etc/dbus-1/system.d/was never loaded.Root cause:
install-helper.shransystemctl reload dbus 2>/dev/null || true, masking the reload failure. Worked on Bazzite (the dev distro); failed on CachyOS.Fix (
scripts/install-helper.sh):reload_dbus(): triessystemctl reload dbus, falls back toSIGHUPvia/run/dbus/pid(or/var/run/dbus/pid); no more|| truemasking.install_helper: warns loudly on reload failure; onsystemctl restartfailure, dumps the last 30journalctllines + the exact follow-up command — so the next reporter sees the cause instead of a bare "Helper installation failed".uninstall_helper: uses the samereload_dbushelper.2. Flatpak
exportcopies nothing to~/.local/share(Flatpak method)CONFIRMED, deterministic. The manifest had no
--filesystem=home, so inside the sandbox$HOME=~/.var/app/io.github.hikaps.couchplay.exportwrote there, but the README's next command (sudo ~/.local/share/couchplay/install-helper.sh install) found an empty dir.Fix:
io.github.hikaps.couchplay.json: added"--filesystem=home"tofinish-argsso$HOMEresolves to the real host home.scripts/install-helper.sh:EXPORT_DIRnow resolves the real host home from/etc/passwdwhen running inside a Flatpak (robust whether or not$HOMEis remapped).README.md: documents whereexportwrites, with an older-build fallback (sudo ~/.var/app/io.github.hikaps.couchplay/.local/share/couchplay/install-helper.sh install) for users on the current stable build.Verification
bash -n scripts/install-helper.shclean;python3 -m json.toolon the manifest valid.awkresolution returns/home/notaname==$HOMEexactly.reload_dbusfallback exercised: withsystemctl reloadstubbed to fail and a live pid in the pidfile, it SIGHUPs the pid and returns0(signal delivery confirmed).Behavior-change note
--filesystem=homemeans the Flatpak now reads/writes the real~/.local/share/couchplay/profiles/instead of the sandboxed copy, consistent with the non-Flatpak install. Previously-created Flatpak profiles won't carry over — worth a release note.Notes
return 1branch for bug 1 is ~90% likelyregisterService()but is not 100% pinned without the reporter'sjournalctl. The fix is correct-and-diagnostic either way: the reload+fallback handles the leading cause, and the journal dump nails any other.Refs #28