A Game Boy emulator written in C++17.

gbglow includes CPU, PPU, audio, cartridge, input, save-state, and debugger components.

The current release target is Ubuntu 24.04. Release builds stay portable by default. Host-specific tuning is available when you explicitly ask for it.

Supported cartridge families:

• ROM-only
• MBC1
• MBC3
• MBC5

git clone https://github.com/byteshiftlabs/gbglow.git
cd gbglow
./build.sh

# Optional: enable host-specific tuning for a personal build on this machine
./build.sh --native-tuning

# 3. Run a ROM
./run.sh path/to/game.gb

If you are new to the emulator, use this order:

1. Run ./build.sh and launch a known-good ROM with ./run.sh path/to/game.gb.
2. Run cd build && ctest --output-on-failure so you understand the current automated test surface.
3. Rebuild the docs only if you are changing public documentation or developer docs.
4. Read ROADMAP.md before opening larger emulator accuracy or tooling changes so you stay aligned with the current priorities.

Current support target: Ubuntu 24.04.

Dear ImGui is fetched automatically during CMake configure.

Release builds stay portable by default. If you want -march=native and -mtune=native, opt in explicitly with ./build.sh --native-tuning or -DGBGLOW_ENABLE_NATIVE_TUNING=ON during CMake configure.

Install on Ubuntu 24.04:

sudo apt install build-essential cmake libsdl2-dev pkg-config cppcheck zenity

Required tools:

• GCC or Clang with C++17 support
• CMake 3.14 or newer
• SDL2 development package
• pkg-config, used to detect the SDL2 development package and provide the compiler/linker flags for it
• cppcheck

The debugger UI uses Dear ImGui. It is fetched automatically during CMake configure, so no separate manual install is needed.

Screenshots are supported in the emulator with F12 and are saved to a local gbglow screenshot directory.

./build.sh

To run the exact same pinned cppcheck version that CI uses:

./build.sh --bootstrap-cppcheck --clean

Manual test run:

cd build && ctest --output-on-failure

Current test targets:

• test_core
• test_persistence
• test_ppu

Build the docs with:

python3 -m venv .docs-venv
source .docs-venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r docs/requirements.txt
make -C docs html

# Open docs/_build/html/index.html in your browser

On Ubuntu 24.04, prefer the virtualenv path above instead of installing Sphinx into the system interpreter.

See ROADMAP.md for the current validation, documentation, and follow-up work priorities.

GPL-3.0