Skip to content

feat(install): make Flatpak the default one-liner pathway - #56

Merged
hikaps merged 3 commits into
developfrom
feature/install-flatpak-default
Jul 30, 2026
Merged

feat(install): make Flatpak the default one-liner pathway#56
hikaps merged 3 commits into
developfrom
feature/install-flatpak-default

Conversation

@hikaps

@hikaps hikaps commented Jul 30, 2026

Copy link
Copy Markdown
Owner

Problem

We agreed Flatpak is the default GUI (it runs on every distro; the native binary fails on Arch/SteamOS via copy-relocation). But the one-liner (install.sh) contradicted this: on every non-SteamOS distro it ran install_tarball(), installing the native couchplay binary + helper. Only the SteamOS (install_sysext) path actually installed the Flatpak.

So a user running the documented one-liner on Arch/Fedora/Bazzite got the native binary — the exact thing that breaks on Arch/SteamOS.

Change

  • New install_flatpak() pathway is the default for all non-SteamOS distros:
    1. Download + checksum-verify couchplay.flatpak.
    2. Ensure the Flathub remote + org.kde.Platform 6.10 runtime.
    3. flatpak install --user the bundle as the invoking user (Flatpak never runs as root; everything user-scoped goes through sudo -u "$REAL_USER").
    4. Export the privileged helper from the Flatpak (flatpak run … install-helper.sh export) and install it system-wide — the same path documented in the README, which install-helper.sh already detects (flatpak-export layout, line 89-92).
  • main() pathway selection: SteamOS → sysext; --tarball → native (Fedora-family opt-in); default → flatpak. New --flatpak flag to force it.
  • flatpak.yml: generate + publish couchplay.flatpak.sha256 (beta and stable releases) so the one-liner can verify the bundle — previously only the tarball/sysext had checksums. Old releases without the sha are handled gracefully (verification skipped).
  • README: surface the one-liner as Quick install (Flatpak GUI + helper in one command); the manual flatpak/helper steps remain below it.

Verification

  • bash -n scripts/install.sh clean; shellcheck reports zero new findings (only the pre-existing binary_name SC2034).
  • flatpak.yml parses as valid YAML.
  • Confirmed install-helper.sh detects the flatpak-export layout ($SCRIPT_DIR/couchplay-helper + $data/), so the export→install step resolves correctly.
  • Stable releases already ship couchplay.flatpak (via flatpak.yml's v* tag trigger); this PR only adds the checksum.

Notes

  • No C++ changes; the unit suite is unaffected.
  • The stable main one-liner stays on the old installer until the next release cut; this lands on develop (beta) first, as expected.
  • End-to-end flatpak install can't be exercised in CI (needs a real runtime download + bwrap); validated by syntax/lint + structural review following the documented README path.

hikaps added 3 commits July 30, 2026 14:30
The one-liner installed the native couchplay binary by default on every
non-SteamOS distro - the opposite of the agreed 'Flatpak is the default GUI'
decision (the native binary fails on Arch/SteamOS via copy-relocation).

Add install_flatpak() as the default pathway: download + checksum-verify the
flatpak bundle, ensure the Flathub remote + org.kde.Platform 6.10 runtime,
install the bundle as the invoking user, export the privileged helper from the
flatpak, then install it system-wide. SteamOS still auto-selects the sysext;
--tarball opts into the legacy native build.

flatpak.yml now generates + publishes couchplay.flatpak.sha256 (both beta and
stable releases) so the one-liner can verify the bundle - previously only the
tarball/sysext had checksums.

README surfaces the one-liner as 'Quick install' (flatpak GUI + helper).
…teamOS README wording

- install_flatpak: when couchplay.flatpak.sha256 exists in the release but its
  download fails, exit 1 (mirror install_tarball's 'Refusing to install without
  checksum verification'). The graceful skip now applies only to genuinely
  absent assets (old releases), closing a silent integrity-bypass gap.
- README: 'On SteamOS the installer deploys a system extension instead of the
  Flatpak' was wrong - install_sysext installs the Flatpak GUI bundle too.
  Reworded to 'also deploys a system extension for the privileged helper'.
…own section

The --tarball native-binary install was only a passing clause after moving the
one-liner to Quick install. Add a dedicated subsection with the full command +
the Fedora-family caveat, and drop the now-redundant clause from the blockquote.
@hikaps
hikaps merged commit cc1d319 into develop Jul 30, 2026
1 check passed
@hikaps
hikaps deleted the feature/install-flatpak-default branch July 30, 2026 22:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant