# Building and Running the kat5200 Flatpak (Linux)

This document covers building, installing, and packaging kat5200 as a
self-hosted Linux Flatpak. No system BIOS or game ROMs are bundled
(copyright); the user supplies their own.

- **App ID:** `io.github.madjacket.kat5200`
- **Manifest:** `flatpak/io.github.madjacket.kat5200.yml` (source is the
  repo root, via `path: ..`)
- **Runtime:** `org.freedesktop.Platform` 25.08. SDL3 and SDL3_image are
  bundled at 3.4.x for GPU shader-preview support; zlib, libjpeg, libpng,
  Mesa, libcurl and the desktop stack still come from the runtime.

## Prerequisites

```bash
# Flatpak itself, plus the Flathub remote
flatpak remote-add --if-not-exists flathub \
    https://flathub.org/repo/flathub.flatpakrepo

# The build tool (run as a Flatpak app)
flatpak install -y flathub org.flatpak.Builder

# The runtime + SDK (Builder will offer to pull these automatically too)
flatpak install -y flathub org.freedesktop.Platform//25.08 \
    org.freedesktop.Sdk//25.08
```

## Build via CMake (recommended)

CMake wraps the flatpak-builder invocations so there are no long commands
to remember. From the repository root:

```bash
cmake -B build
cmake --build build --target flatpak-install   # build + install (user)
cmake --build build --target flatpak-bundle     # shareable .flatpak
```

`flatpak-install` builds and installs into your user Flatpak (then run with
`flatpak run io.github.madjacket.kat5200`); `flatpak-bundle` writes
`build/dist/kat5200-<version>.flatpak`. Scratch output lands in the build tree
under `flatpak-build/`, `flatpak-repo/`, and `flatpak-state/` (all gitignored).

To build the native Release app, Flatpak, and source archive together:

```bash
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --target kat5200-release -j4
```

The release artifacts are written to `build/dist/`:

- `kat5200-<version>.flatpak`
- `kat5200-<version>-src.zip`

These targets require `flatpak` on `PATH` and `org.flatpak.Builder`
installed (see Prerequisites). They are developer-convenience only and do
not replace the native toolchain: `cmake -B build` itself still needs the
native SDL3/SDL3_image/OpenGL/zlib dev packages to configure.

## Manual build and install (fallback)

Run from the `flatpak/` directory (the manifest's source is `path: ..`, the
repo root):

```bash
cd /path/to/kat5200-1.0.2/flatpak
flatpak run org.flatpak.Builder --user --install --force-clean \
    build-flatpak io.github.madjacket.kat5200.yml
```

Then run it:

```bash
flatpak run io.github.madjacket.kat5200
```

`build-flatpak/` is the scratch build directory; `--force-clean` resets it
each run.

## Build a shareable single-file bundle (manual)

```bash
cd /path/to/kat5200-1.0.2/flatpak

# 1. Build into a local OSTree repo
flatpak run org.flatpak.Builder --repo=repo --force-clean \
    build-flatpak io.github.madjacket.kat5200.yml

# 2. Export the repo to a single .flatpak file
flatpak build-bundle repo kat5200-<version>.flatpak io.github.madjacket.kat5200
```

The versioned output is written to the current directory. It is larger than
older bundles because SDL3 and SDL3_image are included.

Anyone can install it with:

```bash
flatpak install --user kat5200-<version>.flatpak
flatpak run io.github.madjacket.kat5200
```

They need the `org.freedesktop.Platform//25.08` runtime; Flatpak normally
offers to pull it automatically.

## Where things live

| What | Location |
|------|----------|
| Binary | `/app/bin/kat5200` (inside sandbox) |
| Seed config + profiles | `/app/share/kat5200/` (inside sandbox) |
| User config (first-run seeded copy) | `~/.config/kat5200/` |
| BIOS / ROMs | anywhere under `$HOME` (granted via `--filesystem=home`) |

On first launch kat5200 seeds a fresh `~/.config/kat5200` from
`/app/share/kat5200`. The seed directory is set at build time via the
`KAT_DATADIR` CMake option (`-DKAT_DATADIR=/app/share/kat5200` in the
manifest); a plain FHS build defaults to `/etc/kat5200`.

## Sandbox permissions

Defined in `finish-args` in the manifest:

- `--device=dri` — GPU / OpenGL
- `--device=input` — game controllers / joysticks
- `--socket=wayland`, `--socket=fallback-x11`, `--share=ipc` — display
- `--socket=pulseaudio` — audio
- `--filesystem=home` — BIOS/ROM access and config storage

The bundled SDL3 build keeps the PulseAudio and X11 backends enabled to match
those sandbox permissions. ALSA, OSS and SNDIO are disabled because the Flatpak
does not use those audio paths.

## Notes / gotchas

- The build is out-of-source; the manifest's `skip:` list excludes local
  build trees (`build*`, `out`, and Flatpak scratch dirs) so stray
  in-source `CMakeCache.txt` files and old artifacts don't get re-packaged.
- `*.flatpak` and the Flatpak scratch dirs are gitignored.
- The project builds via CMake only (the old autotools files have been
  removed).
