mGBA Logo mGBA

Building mGBA from Source

This guide explains how to compile mGBA from source code. Building from source allows you to use the latest development version, customize the build, or contribute to the project.

Prerequisites

Required Tools

  • CMake 3.1 or later: Build system generator
  • C Compiler: GCC 4.9+, Clang 3.4+, or MSVC 2015+
  • Git: Version control system

Dependencies

  • SDL2: Cross-platform multimedia library (2.0.8 or later)
  • Qt5: GUI toolkit (optional, for Qt GUI)
  • libpng: PNG image library
  • zlib: Compression library
  • lua: Lua scripting library (5.4, optional)

Getting the Source Code

Clone Repository

git clone https://github.com/mgba-emu/mgba.git
cd mgba

Update Submodules

git submodule update --init --recursive

Building on Windows

Using Visual Studio

  1. Install Visual Studio 2015 or later with C++ support
  2. Install CMake and add to PATH
  3. Run CMake GUI or use command line:
mkdir build
cd build
cmake .. -G "Visual Studio 16 2019" -A x64
cmake --build . --config Release

Using MinGW

mkdir build
cd build
cmake .. -G "MinGW Makefiles"
cmake --build .

Building on macOS

Using Xcode

  1. Install Xcode Command Line Tools: xcode-select --install
  2. Install dependencies via Homebrew:
brew install cmake sdl2 libpng zlib lua

Then build:

mkdir build
cd build
cmake .. -G Xcode
cmake --build . --config Release

Building on Linux

Ubuntu/Debian

Install dependencies:

sudo apt-get update
sudo apt-get install build-essential cmake libsdl2-dev libqt5opengl5-dev qtbase5-dev libpng-dev zlib1g-dev liblua5.4-dev

Build:

mkdir build
cd build
cmake ..
make -j4

Fedora

sudo dnf install gcc cmake SDL2-devel qt5-qtbase-devel libpng-devel zlib-devel lua-devel
mkdir build && cd build
cmake ..
make -j4

Arch Linux

sudo pacman -S cmake sdl2 qt5-base libpng zlib lua
mkdir build && cd build
cmake ..
make -j4

CMake Options

Configure build options:

  • USE_QT: Enable Qt GUI (ON/OFF, default: ON)
  • USE_SDL: Enable SDL frontend (ON/OFF, default: ON)
  • USE_DEBUGGERS: Enable debugger support (ON/OFF, default: ON)
  • USE_LUA: Enable Lua scripting (ON/OFF, default: ON)
  • BUILD_GL: Build OpenGL renderer (ON/OFF, default: ON)
cmake .. -DUSE_QT=ON -DUSE_SDL=ON -DUSE_LUA=ON

Installation

After building, install mGBA:

# Linux/macOS
sudo cmake --install . --prefix /usr/local

# Or install to custom location
cmake --install . --prefix ~/local

Troubleshooting Build Issues

Missing Dependencies

If CMake reports missing dependencies:

  • Install missing packages using your package manager
  • Ensure development headers are installed (not just runtime libraries)
  • Use pkg-config to verify dependency installation

Build Errors

Common build errors and solutions:

  • Compiler Errors: Update compiler to supported version
  • Linker Errors: Ensure all dependencies are installed
  • CMake Errors: Update CMake to version 3.1 or later
  • Git Submodule Issues: Run git submodule update --init --recursive
Need Help? If you encounter build issues, check GitHub Issues for similar problems or ask for help in GitHub Discussions.

Related Articles

For more information about mGBA development: