Build GBAx on Linux

Use this guide when you want to change GBAx, inspect its implementation or reproduce its packaging process. If you only want to play, install a desktop download instead. A source build creates the application; it does not supply game files or a Nintendo BIOS.

Understand the build stages

CMake configures the project and finds dependencies. A compiler turns the C/C++ source into executable code. Packaging then collects the runtime libraries, Qt plugins, artwork resources and notices the application needs on another machine. Passing compilation is only one stage: an executable can work on a developer’s computer because it finds libraries that are missing from the package.

The release profile enables the Qt frontend and SDL audio/controller support. It does not build the separate SDL frontend. Optional integrations such as the application updater, FFmpeg recording, Lua scripting and Discord presence are disabled in Preview 1. Changing a profile option may introduce new dependencies and packaging work.

Get the matching source

git clone --branch v2.0.0-candidate-40705365475 --depth 1 https://github.com/gbaxemulator/GBAx.git
cd GBAx

The instructions below follow the Preview 1 release tag. To verify that you have the same revision described by this documentation, run:

git rev-parse HEAD

The expected commit is c1a826ae838f9b9226cdd2dd33b3dfea6893cbfb. A different checkout can have different dependencies or scripts. Keep your working changes in version control and use a fresh build directory when switching toolchains.

Use a fresh release build directory. The packaging scripts reject stale staging folders. Keep game files, saves and personal configuration outside the source tree.

Prepare a native development environment

Use an x86_64 Ubuntu 24.04 environment for the published baseline. In addition to the workflow packages below, a minimal installation needs Git, Python 3, a C/C++ compiler and the ordinary download/archive tools used by the packaging script. Hosted CI runners already provide many of those utilities; a fresh desktop or container may not.

sudo apt-get install -y build-essential git python3 curl wget unzip

Qt development packages provide headers and libraries for the interface. SDL handles host audio and controllers; libzip and compression libraries support archives; image and database libraries serve other frontend features. The package manager’s development packages are needed at build time even if the final AppImage carries the corresponding runtime libraries.

Install dependencies on Ubuntu 24.04

The published package targets x86_64 and glibc 2.39 or newer. The workflow uses Ubuntu’s Qt 6.4.2 packages.

sudo apt-get update
sudo apt-get install -y --no-install-recommends cmake ninja-build pkg-config \
  qt6-base-dev qt6-tools-dev-tools libqt6opengl6-dev qt6-svg-dev qt6-wayland \
  libsdl2-dev libzip-dev zipcmp zipmerge ziptool libpng-dev libsqlite3-dev \
  libepoxy-dev zlib1g-dev libcmocka-dev libssl-dev patchelf file desktop-file-utils

Build the AppImage

bash tools/release/build-linux.sh
chmod +x dist/GBAx-2.0.0-linux-x86_64.AppImage
./dist/GBAx-2.0.0-linux-x86_64.AppImage

If the test system lacks FUSE:

APPIMAGE_EXTRACT_AND_RUN=1 ./dist/GBAx-2.0.0-linux-x86_64.AppImage

The packaging tools are pinned and checked with SHA-256. Test both X11 and Wayland where applicable; building on a newer distribution does not establish compatibility with older glibc versions.

Common Linux build failures

A missing header or CMake package usually points to an absent development dependency. An error mentioning a newer GLIBC symbol points to the host/runtime baseline. Building on a newer distribution can raise that baseline even if the source code has not changed.

A Qt platform-plugin failure occurs later, when starting the application. Preserve the exact plugin error and test the deployed AppImage, not a shell environment filled with development overrides. Check both X11 and Wayland where available. The script’s pinned packaging downloads and SHA-256 checks should remain intact; a failed download verification should be investigated rather than bypassed.

Test the package, not only the build directory

Use the packaged output in a new location, ideally on a test machine without your development libraries. Check first-run setup, folder scanning with subfolders, a supported archive, background artwork, one game with sound, save/reload, controller reconnect and returning to the launcher. Keep notes for each platform; success on one OS does not establish that another package works.

The repository’s release workflow includes automated checks and deployed-runtime validation. These help detect missing resources and dependencies, but they do not replace interactive desktop tests or a game compatibility test suite. Keep the package’s licence and dependency notices when distributing a build.

Keep a useful build report

Record the commit, OS version, processor architecture, compiler and Qt version, the command you ran and the first meaningful error. For a configuration failure, keep the CMake output. For a link failure, keep the missing symbol/library message. For a runtime failure, state whether it occurs in the build tree, the extracted package or both. This makes it possible to distinguish a source error from a deployment problem.