Gearboy

Windows

• Install Microsoft Visual Studio Community 2026 or later.
• Download the latest SDL3 VC development libraries from SDL3 Releases (the file named SDL3-devel-x.y.z-VC.zip).
• Extract the archive and rename the resulting folder (e.g. SDL3-x.y.z) to SDL3.
• Place the SDL3 folder inside platforms/windows/dependencies/ so that the include path is platforms/windows/dependencies/SDL3/include/SDL3/.
• Open the Gearboy Visual Studio solution platforms/windows/Gearboy.sln and build.

macOS

• Install Xcode and run xcode-select --install in the terminal for the compiler to be available on the command line.
• Run these commands to generate a Mac app bundle:

brew install sdl3
cd platforms/macos
make dist

Linux

• Ubuntu / Debian / Raspberry Pi (Raspbian):

If you are using Ubuntu 25.04 or later, you can install SDL3 directly. Use the following commands to build:

sudo apt install build-essential libsdl3-dev
cd platforms/linux
make

For older Ubuntu versions (22.04, 24.04), you need to build SDL3 from source first. Use the following commands to build both SDL3 and Gearboy:

sudo apt install build-essential cmake git curl jq pkg-config \
  libx11-dev libxext-dev libxrandr-dev libxcursor-dev libxfixes-dev \
  libxi-dev libxss-dev libxkbcommon-dev libwayland-dev libdecor-0-dev \
  libdrm-dev libgbm-dev libgl1-mesa-dev libegl1-mesa-dev libdbus-1-dev libudev-dev libxtst-dev
SDL3_TAG=$(curl -s https://api.github.com/repos/libsdl-org/SDL/releases/latest | jq -r '.tag_name')
git clone --depth 1 --branch "$SDL3_TAG" https://github.com/libsdl-org/SDL.git /tmp/SDL3
cmake -S /tmp/SDL3 -B /tmp/SDL3/build -DCMAKE_INSTALL_PREFIX=/usr -DSDL_TESTS=OFF -DSDL_EXAMPLES=OFF
cmake --build /tmp/SDL3/build -j$(nproc)
sudo cmake --install /tmp/SDL3/build
cd platforms/linux
make

Basic Usage

• Boot ROM: Gearboy can run with or without a Boot ROM. You can optionally load a Boot ROM and enable it.
• Mouse Cursor: Automatically hides when hovering over the main output window or when Main Menu is disabled.
• Portable Mode: Create an empty file named portable.ini in the same directory as the application binary to enable portable mode. On macOS, place the file next to the .app bundle.

Debugging Features

• Docking Windows: In debug mode, you can dock windows together by pressing SHIFT and dragging a window onto another.
• Multi-viewport: In Windows or macOS, you can enable "multi-viewport" in the debug menu. You must restart the emulator for the change to take effect. Once enabled, you can drag debugger windows outside the main window.
• Single Instance: You can enable "Single Instance" in the Emulator menu. When enabled, opening a ROM while another instance is running will send the ROM to the running instance instead of starting a new one.
• Debug Symbols: The emulator automatically tries to load a symbol file when loading a ROM (.sym, .noi). For example, for path_to_rom_file.gb it tries to load path_to_rom_file.sym. You can also load a symbol file using the GUI or the CLI. It supports RGBDS, GBDK-2020, WLA-DX, no$gmb, SDCC/NoICE (.noi), EQU and generic file formats.

Command Line Usage

gearboy [options] [rom_file] [symbol_file]

Arguments:
  [rom_file]               ROM file: accepts ROMs (.gb, .dmg, .gbc, .cgb, .sgb) or ZIP (.zip)
  [symbol_file]            Optional symbol file for debugging

Options:
  -f, --fullscreen         Start in fullscreen mode
  -w, --windowed           Start in windowed mode with menu visible
      --mcp-stdio          Auto-start MCP server with stdio transport
      --mcp-http           Auto-start MCP server with HTTP transport
      --mcp-router         Enable compact MCP tool routing
      --mcp-http-address A HTTP bind address (default: 127.0.0.1)
      --mcp-http-port N    HTTP port for MCP server (default: 7777)
      --headless           Run without GUI (requires --mcp-stdio or --mcp-http)
  -v, --version            Display version information
  -h, --help               Display this help message