Merge pull request #1820 from 1Jamie/app-image-fixes

feat(linux): ship raw x86 AppImage, Flatpak bundle, and dual-env curl

docs/linux-appimage.md

@@ -0,0 +1,58 @@
+# Linux AppImage packaging
+
+Releases ship raw AppImages (no zip wrapper):
+
+- `gen1recomp-<version>-linux-x86_64.AppImage`
+- `gen1recomp-<version>-linux-arm64.AppImage`
+
+```sh
+chmod +x gen1recomp-*-linux-x86_64.AppImage
+./gen1recomp-*-linux-x86_64.AppImage
+```
+
+Flatpak users should prefer the `.flatpak` bundle (see
+[linux-flatpak.md](linux-flatpak.md)); it avoids host glibc / FUSE / curl
+mismatches on immutable desktops.
+
+## Common failure modes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Won't start / `libfuse.so.2` | No FUSE | `sudo apt install libfuse2` (or `libfuse2t64`) **or** `./app.AppImage --appimage-extract-and-run` |
+| Update check / mods / save sync fail | Host `curl` missing or broken by AppImage `LD_LIBRARY_PATH` | Install curl; current builds scrub `LD_LIBRARY_PATH` for **host** curl and keep it for a bundled AppDir curl |
+| Settings / sync reset after quit | Portable mode next to a read-only AppImage parent (`/opt`, system dir) | Remove `portable.txt` or move the AppImage to a writable folder; the game falls back to the XDG save dir when the probe write fails |
+| "Download AppImage update" | Shell/`minShell` gate needs a full native package | Download the new `.AppImage`, `chmod +x`, replace the old file |
+| Steam / Game Mode weirdness after update | Overlay `LD_PRELOAD` / PID change | HostShell unsets `LD_PRELOAD` for children and `execv`s `$APPIMAGE` on restart |
+
+## Network transport (HostShell)
+
+Desktop Linux fetches go through host or bundled `curl`:
+
+1. Flatpak `/app/bin/curl` (bundled, keep sandbox libs)
+2. `$APPDIR/usr/bin/curl` or `$APPDIR/bin/curl` (keep `$APPDIR` on `LD_LIBRARY_PATH`)
+3. Host `curl` (`env -u LD_LIBRARY_PATH`, and always `-u LD_PRELOAD`)
+
+## Portable mode
+
+Drop `portable.txt` beside the `.AppImage` to keep saves next to the binary.
+The launcher probes writability with a unique `.write_probe_<time>_<rand>.tmp`
+file. Read-only parents fail soft and use `love.filesystem` XDG saves instead.
+Flatpak ignores `portable.txt`.
+
+## Auto-update
+
+In-place updates download `gen1recomp-X.Y.Z.love` into the save directory.
+Full shell bumps open the matching AppImage (or Flatpak) download URL — there
+is no silent in-place AppImage replace yet.
+
+## Building
+
+```sh
+# x86_64 (macOS or Linux host with squashfs-tools)
+scripts/build.sh linux --version X.Y.Z
+
+# arm64 (aarch64 host + docker/podman)
+scripts/build_linux_arm64.sh --version X.Y.Z
+```
+
+See [linux-arm64-build.md](linux-arm64-build.md) for the arm64 builder.

docs/linux-arm64-build.md

@@ -1,10 +1,11 @@
 # Linux arm64 (aarch64) AppImage
 
 Releases ship `gen1recomp-<version>-linux-arm64.AppImage` alongside the
-existing x86_64 `gen1recomp-<version>-linux.zip`. It targets 64-bit ARM
+existing x86_64 `gen1recomp-<version>-linux-x86_64.AppImage`. It targets 64-bit ARM
 desktop Linux: Raspberry Pi 4/5 running Raspberry Pi OS, Armbian and other
 SBC distros, arm64 VMs on Apple Silicon, Ampere/Graviton desktops, and the
-aarch64 handhelds that run a full distro.
+aarch64 handhelds that run a full distro. See also
+[linux-appimage.md](linux-appimage.md) for shared AppImage failure modes.
 
 > The Anbernic RG34XXSP has its own PortMaster-style pack
 > (`gen1recomp-*-rg34xxsp-stockos64-mod.zip`, see

docs/linux-flatpak.md

@@ -0,0 +1,51 @@
+# Linux Flatpak
+
+Releases may ship `gen1recomp-<version>-linux.flatpak` (x86_64 bundle).
+
+## Install
+
+```sh
+flatpak install --user ./gen1recomp-<version>-linux.flatpak
+flatpak run com.theboisclub.gen1recomp
+```
+
+Or open the `.flatpak` in Discover / GNOME Software. AppStream metainfo
+includes a `<releases>` entry so those UIs can show the version.
+
+## Permissions
+
+The manifest requests:
+
+- network (updater, mods, save sync)
+- X11 / Wayland / DRI / PulseAudio
+- `--device=all` (SDL2 gamepads, rumble, gyro via evdev/hidraw)
+- `--filesystem=home` (ROM import)
+
+Curl is bundled at `/app/bin/curl` so the game does not need host curl.
+
+## Updates
+
+Lua/engine payloads still use the in-app `.love` updater. A native shell bump
+points at the new `.flatpak` asset (`Download Flatpak update`).
+
+After a `.love` payload download, restart uses `love.event.quit("restart")`
+(`execv` of `/proc/self/exe` inside bwrap). If a restart hangs after an
+update, fully quit and relaunch — PhysFS can retain a lock on the previous
+payload across a bad handoff.
+
+## Building
+
+```sh
+scripts/build_flatpak.sh --version X.Y.Z
+# → dist/flatpak/gen1recomp-X.Y.Z-linux.flatpak
+```
+
+Requires `flatpak` + `flatpak-builder` and the Freedesktop 24.08 runtime from
+Flathub (installed automatically on first build).
+
+Release CI builds the bundle on `ubuntu-24.04` (`linux-flatpak` job) from the
+shared `game.love` payload and publishes `gen1recomp-<ver>-linux.flatpak`
+alongside the AppImages. PR CI path-gates the same script when `flatpak/` or
+`scripts/build_flatpak.sh` change.
+
+Flathub store submission is out of scope for the GitHub bundle channel.

docs/updater.md

@@ -63,8 +63,9 @@ mounted or deleted as stale; the launcher directs the player to a full package.
 ## Release assets
 
 Each tagged release `vX.Y.Z` carries the existing per-platform archives
-(`gen1recomp-X.Y.Z-macos.zip`, `-windows.zip`, `-linux.zip`,
-`-linux-arm64.AppImage`, `-android.apk`, `-ios.ipa`, `-switch.zip`, Xbox and
+(`gen1recomp-X.Y.Z-macos.zip`, `-windows.zip`,
+`-linux-x86_64.AppImage`, `-linux-arm64.AppImage`, `-linux.flatpak`,
+`-android.apk`, `-ios.ipa`, `-switch.zip`, Xbox and
 PortMaster archives) plus two assets the updater itself consumes:
 
 - `gen1recomp-X.Y.Z.love` - the payload, matched by the exact pattern