RGBDS: the assembler toolchain behind Game Boy homebrew

What RGBDS actually solves for Game Boy developers

The Game Boy and Game Boy Color run on a Sharp LR35902 core, and the practical way to produce a ROM for them is to assemble source into object files, link those objects into a flat image, patch the cartridge header, and convert artwork into tile data the hardware can read. RGBDS bundles those four jobs into one package. The README names the components directly: RGBASM is the assembler, RGBLINK is the linker, RGBFIX is the ROM checksum and header fixer, and RGBGFX is the PNG-to-Game Boy graphics converter.

The audience is narrow and specific. This is for people writing assembly for original Game Boy hardware or for emulators that model it, and for projects that need a reproducible build from source rather than a click-to-run editor. It is not a general retro console toolkit. If your target is the Game Boy Advance, the tooling question is different, and RGBDS does not address it.

The four-tool pipeline and how data moves through it

The build is a chain. RGBASM takes assembly source and emits object files. RGBLINK takes those objects and produces a linked binary, resolving symbols across separately assembled units. RGBFIX then writes the cartridge header fields and computes the checksum so the ROM boots and passes verification. RGBGFX sits slightly to the side: it converts PNG input into Game Boy tile and map data, which the assembler then includes as data in the build.

The repository layout reflects this split. The source tree carries src/asm/ for the assembler, src/link/ for the linker, src/fix/ for the header fixer and src/gfx/ for the graphics converter, with a shared set of objects (src/cli.o, src/diagnostics.o, src/style.o, src/usage.o, src/util.o) compiled into each binary. That shared layer is why the tools behave consistently at the command line, and it is also why the Makefile builds all four from one object list rather than four independent projects.

One consequence worth noting: the linker is a real linker, not a concatenator. If you are used to a single-file assembler where include order is the whole build system, RGBLINK's symbol resolution changes how you organise a project, and section placement becomes something you configure rather than something that falls out of file order.

Installing RGBDS on Linux and building from source

The README does not give a single universal install command. It points to a platform-specific installation page at rgbds.gbdev.io/install/ and then shows the source build. On a Debian-family system the repository's own Dockerfile is the most concrete record of what the build needs: it installs sudo, make, cmake, gcc and build-essential, then runs ./.github/scripts/install-deps.sh debian before building.

The plain make path is two commands, and the README gives them verbatim:

make
sudo make install

The CMake path is the alternative, and it is the one to prefer if you want an out-of-tree build directory:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build
cmake --install build

Both build systems accept a prefix and a suffix. The suffix is how you append a version number or commit ID to the installed binaries, which matters if you keep several RGBDS versions around for different projects. The README shows the make form with a git short hash:

make
sudo make install PREFIX=install_dir/ SUFFIX=-$(git rev-parse --short HEAD)

On Windows the README notes that any SUFFIX should include the .exe extension, which is the kind of detail that only shows up when the install silently produces unusable binaries. After installing, the useful first check is that all four executables are on your PATH: rgbasm, rgblink, rgbfix and rgbgfx. If only some resolve, the install prefix is the place to look.

Building RGBDS in a container and shipping the binaries out

The Dockerfile is worth reading even if you never intend to use Docker for development, because it documents a build configuration the maintainers chose. It starts from debian:13-slim, takes an ARG version defaulting to 1.0.3, and builds with a specific set of flags:

RUN make -j "$(getconf _NPROCESSORS_ONLN)" CXXFLAGS="-O3 -flto -DNDEBUG -static" PKG_CONFIG="pkg-config --static" Q=

That line is a static release build with link-time optimisation and assertions compiled out. The container then runs make install.sh to generate an installer, tars the four executables together with the man pages and the install script, and copies that archive out. The archive is named rgbds-linux-x86_64.tar.xz, so the container path produces Linux x86-64 binaries specifically.

This is a reasonable escape hatch for CI: build once in the container, extract the tarball, and skip a compiler toolchain on the build machine. It is not a substitute for the platform installation page if you want a system package, and the README does not claim otherwise.

Where RGBDS is the wrong tool, and what it asks of you

The clearest limitation is in the README itself: RGBDS is an assembler and linker package. There is no C compiler in the four tools. If your project is written in C, RGBDS is not the thing that compiles it, and treating the toolchain as a general-purpose SDK will lead you to look for a front end that does not exist here.

The second constraint is the build. The README's install section points outward to a documentation site and then shows make and cmake invocations. If you need a signed installer, a package-manager formula, or a Windows binary that does not require you to think about the .exe suffix, the README does not walk you through it. The repository does carry a Dockerfile, which covers Linux x86-64, but that is a container build, not a distribution channel for every desktop.

The third is the assembly requirement itself. RGBGFX converts PNG files to Game Boy graphics, which removes one class of manual work, but the rest of the pipeline assumes you are comfortable writing and organising assembly source. Projects that want a higher-level language or an engine with a scene editor are outside what these four tools do.

Maintenance is not a concern in the archived sense: the repository is not archived, and the last push was on 2026-08-01, the same date as the v1.0.3 release. That is recent, and it lines up with a 1.0.x release cadence that also produced v1.0.2 in July 2026 and v1.0.1 in January 2026.

How RGBDS differs from a general-purpose assembler

The obvious alternative is to assemble Game Boy code with a general-purpose assembler and hand-roll the rest of the pipeline. The difference in approach is that a generic assembler knows nothing about the cartridge header, the checksum, or the tile format. You would write your own header patch step and your own PNG conversion, and you would own the bugs in both.

RGBDS splits that responsibility across named tools instead. RGBFIX exists as a separate program precisely because header and checksum handling is a distinct step from linking, and RGBGFX exists because PNG-to-tile conversion is a distinct step from assembling. That separation is a design choice with a cost: the build has more stages to wire together, and a mistake in the order of rgbasm, rgblink, rgbfix and rgbgfx produces a ROM that fails in ways that look like code bugs. The benefit is that each stage is small enough to test on its own, and the shared CLI layer means the flags behave the same way across all four.

If your workflow already has a build system that treats the ROM as one opaque output, RGBDS asks you to model those four stages explicitly. That is more configuration up front and less guesswork later.

Licence and the cost of tracking releases

RGBDS is released under the MIT licence, and the Makefile carries an SPDX-License-Identifier: MIT header. MIT is permissive: it allows use, modification and redistribution, including in closed-source projects, provided the licence text and copyright notice are preserved. That is a summary of the licence terms, not legal advice, and if you are shipping a commercial Game Boy release you should read the LICENSE file in the repository rather than rely on a one-line characterisation.

The upgrade cost is mostly a build-and-pin question. Releases arrive as versioned tags, and the README's suffix mechanism exists so you can install a build labelled with a commit ID alongside a released one. The version string in the binaries falls back to the last release number when git describe produces nothing, which means a source tarball without git history still reports a version. For projects that need reproducible ROM builds, pinning a specific tag and recording the suffix is the practical approach, since the toolchain version ends up embedded in the binary's reported version string.

Editorial conclusion

Adopt RGBDS if you are writing Game Boy or Game Boy Color code at the assembly level and want one toolchain that assembles, links, fixes the header and converts PNG tiles. Do not adopt it if you expect a C compiler or a high-level engine: RGBDS is an assembler package, and the README lists exactly four tools, none of which is a C front end. Before committing, verify the install path for your platform against the online installation page, since the README only sketches the source build, and confirm that your ROM header and checksum step is wired through rgbfix rather than assumed.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes