Build GBAx on Windows

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.

Install the Windows toolchain

Use Windows x64, Visual Studio 2022 with C++ tools, CMake, Python, Qt 6.10.2 for MSVC 2022 64-bit, and a bootstrapped vcpkg checkout. The release workflow pins vcpkg to 15b12b99a227d51e21c86dffd40385439eac87a0.

Keep the toolchains consistent

Install Git and the Visual Studio C++ workload before starting. The documented Qt kit is built for MSVC 2022 x64; pair it with the corresponding compiler and x64-windows vcpkg dependencies. A MinGW Qt installation is a different compiler environment and is not interchangeable with this package recipe.

Bootstrap vcpkg before installing its libraries. The pinned vcpkg revision records the dependency baseline used by the workflow; using whatever happens to be installed globally can produce a different result. The two PowerShell variables below are examples for your own filesystem, not required folder names.

Install dependencies

In PowerShell, adjust these two paths to match your machine:

$gbaxVcpkg = 'C:\dev\vcpkg'
$gbaxQt = 'C:\Qt\6.10.2\msvc2022_64'
& "$gbaxVcpkg\vcpkg.exe" install sdl2:x64-windows libzip:x64-windows libpng:x64-windows sqlite3:x64-windows zlib:x64-windows libepoxy:x64-windows

Build and package

From the repository root, run:

./tools/release/build-windows.ps1 -QtRoot $gbaxQt -VcpkgRoot $gbaxVcpkg

The script builds the Qt frontend, deploys runtime DLLs and resources, checks the deployed application and produces the ZIP under dist. Extract the whole ZIP before testing. Copying only GBAx.exe is insufficient.

Common Windows build failures

If CMake cannot find Qt, verify that $gbaxQt points at the kit directory containing its CMake packages and deployment tools. If a dependency is missing, confirm the x64-windows triplet and that the script received the intended vcpkg root. Compiler or linker errors mentioning incompatible machine types often indicate an architecture mismatch.

If the build succeeds but the extracted ZIP fails, examine the deployed files and runtime validation output. Do not fix the test by copying libraries into a global system directory; that can hide an incomplete package. The release script uses windeployqt and additional runtime deployment so the resulting folder can be tested independently.

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.