a-la-karte/HACKING.md

Hacking A-La-Karte

This document is intended for contributors who want to build, run, and debug A-La-Karte locally.

Build

Configure

cmake -B build -S . -DCMAKE_BUILD_TYPE=Debug

SDL3

A-La-Karte uses SDL3 for gamepad navigation.

There are two supported ways to satisfy the SDL3 dependency:

Option 1: Use a system SDL3 package

If your distribution provides SDL3 development packages, install them and configure normally.

Common package names include libsdl3-dev (Debian/Ubuntu), SDL3-devel (Fedora/openSUSE), or similarly named SDL3 "-devel" packages.

At CMake configure time, A-La-Karte uses find_package(SDL3 REQUIRED). This requires that SDL3 provides a CMake package (e.g. SDL3Config.cmake) and that CMake can find it.

If CMake cannot find SDL3, you can point it at the right prefix:

cmake -B build -S . \
  -DCMAKE_BUILD_TYPE=Debug \
  -DCMAKE_PREFIX_PATH=/path/to/sdl3/prefix

Alternatively you can point directly at SDL3's CMake package directory:

cmake -B build -S . \
  -DCMAKE_BUILD_TYPE=Debug \
  -DSDL3_DIR=/path/to/SDL3Config.cmake/parent

Option 2: Build SDL3 from a source tree

If your distro does not ship SDL3 yet (or ships a version without a usable CMake package), you can build SDL3 as part of the A-La-Karte build by pointing CMake at an SDL3 source checkout:

You can obtain a source tree by cloning upstream SDL:

git clone https://github.com/libsdl-org/SDL.git

cmake -B build -S . \
  -DCMAKE_BUILD_TYPE=Debug \
  -DALAKARTE_SDL3_SOURCE_DIR=/path/to/SDL

ALAKARTE_SDL3_SOURCE_DIR must point at a directory that contains CMakeLists.txt from SDL3.

This is intended for local development and CI setups. Distributions should prefer packaging SDL3 as a system dependency.

Packaging guidance

Packagers should depend on the system SDL3 development package and ensure CMake can discover it.

In particular:

• The build dependency must include SDL3 headers and the CMake package files.
• A-La-Karte links against SDL3::SDL3.
• Avoid using ALAKARTE_SDL3_SOURCE_DIR in distribution packaging.

Build

cmake --build build

Run from the build directory

./build/bin/alakarte

Code Map

• src/main.cpp
  • Application entry point, KAboutData, and QML engine setup.
• src/app.*
  • Singleton exposed to QML. Owns GameModel, GameLauncher, Config, and SteamGridDB.
• src/game.*
  • In-memory game object + JSON serialization.
• src/gamemodel.*, src/gamesortfiltermodel.*
  • Model + filtering/sorting used by the UI.
• src/*importer.*
  • Importers for different sources (Steam, Lutris, Heroic, Bottles, Desktop Entries, Flatpak, etc.).
• src/gamelauncher.*
  • Launches games and records last played on launch.
• src/qml/
  • Kirigami/Qt Quick UI.

Repeatable Local Smoke Tests (No real library required)

Run with isolated XDG dirs

This avoids touching your real config and library:

export XDG_CONFIG_HOME="$(mktemp -d)"
export XDG_DATA_HOME="$(mktemp -d)"
./build/bin/alakarte

Desktop Entries importer fixture

You can create a temporary desktop entry under the isolated $XDG_DATA_HOME:

mkdir -p "$XDG_DATA_HOME/applications"
cat > "$XDG_DATA_HOME/applications/alakarte-test-game.desktop" <<'EOF'
[Desktop Entry]
Type=Application
Name=A-La-Karte Test Game
Exec=sh -lc 'sleep 1'
Icon=applications-games
Categories=Game;
EOF

Then:

• Use the import sheet and run the Desktop Entries import.
• Verify the entry appears and launches.
• Verify Last played updates after launch.

Manual entry / launcher smoke test

• Create a manual entry with a harmless command, e.g. sh -lc 'sleep 2'.
• Launch it.
• Confirm the app stays responsive and the game transitions out of the running state.

Notes

• SteamGridDB cover fetching requires an API key.
• KRunner integration is optional at build time (depending on available dependencies).