# Installation

## Installing (end users)

- **Windows** — run the Inno Setup installer, or unzip the portable package
  anywhere and run `kat5200.exe`.
- **Linux** — install your distro's package if available, or build and install
  from source (below). A **Flatpak** is also supported.
- **macOS** — open the `.dmg` and drag `kat5200.app` to Applications.
- **Android** — install the APK. Phones, tablets, Android TV / Google TV, and
  Fire TV devices are supported.

### Android APK installs

kat5200 is distributed as a directly installable APK, not through the Play Store.
The APK is still signed for Android installation, but Android treats it as an
unknown-app install because it did not come from the Play Store. Android may ask
you to allow the app that opens the APK, such as your browser or file manager,
to install unknown apps.

On most phones and tablets, this is under:

```text
Settings > Apps > Special app access > Install unknown apps
```

Choose the browser or file manager you are using, then allow installs from that
source. Developer mode is usually not required for normal APK sideloading. It is
only needed for USB/ADB installs on devices that require USB debugging. On
Android TV / Google TV and Fire TV devices, the setting name and location vary
by vendor; look for **Unknown sources**, **Install unknown apps**, or enable
Developer options only if you are installing with ADB.

## Building from source

CMake is the single source of truth on every platform. **Out-of-source** builds
are required (build into a separate directory such as `build/`). Install the
[required libraries](requirements.md) — SDL3, SDL3_image, zlib (and optionally a
ROM-download backend) — before configuring.

### Linux

```bash
cmake -B build -DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_BUILD_TYPE=Release
cmake --build build -j4
sudo cmake --install build
```

The install step places the `kat5200` binary in `bin/`, the seed config / shader
bundles / generated `profiles.zip` in `${KAT_DATADIR}` (default
`<prefix>/share/kat5200`), and the icon, `.desktop` entry, and `.metainfo.xml`
in the standard XDG locations.

Flatpak developer convenience targets (not part of the default build):

```bash
cmake --build build --target flatpak-install   # install to user Flatpak
cmake --build build --target flatpak-bundle    # shareable .flatpak
```

!!! tip "Development environment"
    Any Linux distribution with the required libraries installed should work.
    On older distros SDL3 may need to be built from source.

### Windows (MSYS2 UCRT64)

Use the UCRT64 MSYS2 environment. Install the toolchain and libraries with
pacman (`mingw-w64-ucrt-x86_64-` packages for `gcc`, `cmake`, `ninja`,
`pkgconf`, `SDL3`, `SDL3_image`, `zlib`), then:

```bash
cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build -j4
```

Build a portable package (bundles the MinGW runtime DLLs):

```bash
cmake --build build --target kat5200-portable-package
# -> build/dist/kat5200-<ver>-win64-portable/   (and a matching .zip)
```

The installer is built by compiling `kat5200.iss` with Inno Setup (64-bit only).

### macOS

Requires the Xcode Command Line Tools and SDL3 / SDL3_image from Homebrew.

```bash
cmake -B build && cmake --build build -j4
open build/src/kat5200.app
```

For a self-contained, relocatable `.app` plus a compressed `.dmg` (bundles the
SDL3 dylibs and re-signs ad-hoc):

```bash
cmake --build build --target kat5200-macos-dmg
# -> build/dist/kat5200-<ver>-macos.dmg
```

The bundle is only ad-hoc signed — Apple Developer ID signing and notarization
remain a manual step before distributing off-machine.

### Android

Toolchain: Android SDK (compileSdk 35), NDK 27.3.13750724, JDK 17, and Gradle.
The APK supports Android phones and tablets, Android TV / Google TV, and Fire TV
devices. Native code is packaged for the `arm64-v8a`, `armeabi-v7a`, and
`x86_64` ABIs with minSdk 21; `x86_64` is mainly for Android emulator images.
From `android-project/`:

```bash
cd android-project
./fetch-sdl-aars.sh        # download SDL3 + SDL3_image .aar into app/libs/
./gradlew assembleDebug    # or assembleRelease / build
```

The same APK has both launcher and leanback launcher entries, so it appears on
phone/tablet launchers and Android TV home screens.

## Configuration file

kat5200 stores all of its settings in a single **TOML** file named `kat5200.conf`.
On Linux this lives at:

```
~/.config/kat5200/kat5200.conf
```

On first run, a default `kat5200.conf` is seeded from the installed data
directory if one does not already exist. You normally edit settings through the
[GUI menus](options/index.md); the file is written automatically when you save.
The current configuration directory is shown in **Misc -> Configuration**.

## Portable mode

On Windows and Linux, kat5200 can run fully self-contained, keeping its files
next to the executable instead of in your home directory. (There is intentionally
no portable mode on macOS, which uses a relocatable `.app` bundle.) To enable it:

1. Create a file named `portable.txt` in the same directory as the `kat5200`
   executable.
2. Put a single `1` in that file.
3. Make sure a `kat5200.conf` is present in that directory.

When portable mode is active, the configuration and related files are read from and
written to the executable's directory.

## First run

If no ROM, no BIOS, or no valid configuration is found, kat5200 starts in the GUI so
you can configure it. Use the **Setup** window (described under
[Misc → Setup](options/misc.md#setup)) to scan for BIOS and ROM files and set up your
controllers before launching anything.
