Monter une toolchain Game Boy sur macOS en dix minutes

Cet article décrit, étape par étape, comment installer de quoi compiler, exécuter et tester une ROM Game Boy sur un Mac récent. La cible est volontairement minimale : assembleur RGBDS, compilateur C GBDK-2020, émulateur SameBoy (mode interactif et mode headless pour les tests automatisés).

Tout le reste — éditeur de tiles, tracker audio, hooks Git — peut s’ajouter ensuite. L’objectif ici est d’aller le plus vite possible jusqu’au premier Hello World qui s’affiche.

Procédure validée sur macOS Ventura+ (Apple Silicon). Une section finale donne les équivalents Ubuntu / Pop_OS.

Pré-requis

Un terminal, Homebrew et la CLI GitHub.

# Outils de ligne de commande Apple (compilateur, git, make)
xcode-select --install

# Homebrew, si absent
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# CLI GitHub (téléchargement de releases)
brew install gh
gh auth login

Vérification :

brew --version
clang --version
gh --version

1. RGBDS — l’assembleur de référence

RGBDS regroupe l’assembleur (rgbasm), le linker (rgblink), le fixer de header (rgbfix) et le convertisseur PNG → tiles (rgbgfx). Il est indispensable même si l’on prévoit d’écrire en C : GBDK-2020 délègue le link et le rgbfix final à RGBDS.

brew install rgbds

Vérification :

rgbasm --version    # rgbds 0.7+
rgblink --version
rgbfix --version
rgbgfx --version

2. GBDK-2020 — le compilateur C

Pas de paquet Homebrew officiel ; on récupère la dernière release sur GitHub.

mkdir -p "$HOME/gbdk-dl" && cd "$HOME/gbdk-dl"
gh release download --repo gbdk-2020/gbdk-2020 --pattern 'gbdk-macos-arm64.tar.gz'
tar xzf gbdk-macos-arm64.tar.gz -C "$HOME"   # crée ~/gbdk/

Sur Mac Intel, remplacer gbdk-macos-arm64.tar.gz par gbdk-macos.tar.gz.

Ajouter au shell (~/.zshrc) :

export GBDK_HOME="$HOME/gbdk"
export PATH="$GBDK_HOME/bin:$PATH"

Recharger puis vérifier :

source ~/.zshrc
lcc -v          # doit lister sdcc + GBDK
which lcc       # ~/gbdk/bin/lcc

Piège Gatekeeper : les binaires GBDK ne sont pas notarisés. Au premier lancement, macOS peut bloquer lcc ou sdcc avec un message « impossible de vérifier le développeur ». On lève la quarantaine d’un coup :

xattr -dr com.apple.quarantine "$HOME/gbdk"

3. SameBoy — émulateur précis et scriptable

Mode interactif via le cask Homebrew :

brew install --cask sameboy

L’application s’installe dans /Applications/SameBoy.app. Elle suffit pour ouvrir une ROM à la main, lire le débogueur, tester les inputs.

Pour les tests automatisés, il faut le binaire sameboy_tester (fourni dans les sources, pas dans le cask). Côté pipeline gb_pipeline, on encapsule la compilation :

cd ~/dev/retro/gb_pipeline
bin/gb install tester

Le script clone LIJI32/SameBoy à un tag épinglé, compile la cible tester, et installe sameboy_tester plus les boot ROMs dans ~/bin. Pour suivre une autre référence :

SAMEBOY_REF=master bin/gb install tester
SAMEBOY_REF=v1.0.4 bin/gb install tester

Vérification :

sameboy_tester --help

4. Vérification globale

La CLI Thor du pipeline (bin/gb doctor) audite la toolchain en une commande :

cd ~/dev/retro/gb_pipeline
bundle install              # une seule fois
bin/gb doctor

Sortie attendue, toutes les lignes en ✅ :

✅ rgbasm               rgbasm v1.0.1
✅ rgblink              rgblink v1.0.1
✅ rgbfix               rgbfix v1.0.1
✅ rgbgfx               rgbgfx v1.0.1
✅ lcc (GBDK-2020)      /Users/.../gbdk/bin/lcc
✅ sameboy_tester       (installé)
✅ aseprite             …
✅ uge2source           …
✅ clang                Apple clang version 14.0.3
✅ bundle               Bundler version 2.6.2
✅ lefthook             1.13.6
Toolchain complète.

5. Premier Hello World

Une fois la toolchain en place, on construit la ROM RGBDS pure et on capture la première frame en headless :

bin/gb build asm
bin/gb headless hello
open build/hello.bmp

Résultat : quatre bandes verticales en quatre nuances DMG, signe que le LCD est initialisé et que le tile 0 est dessiné correctement.

Et l’équivalent C avec GBDK :

bin/gb build c
bin/gb headless hello_c
open build/hello_c.bmp

À titre de bonus, voici la frame de référence capturée à 3 secondes par le test headless, telle qu’elle est comparée dans la suite de tests :

6. (Optionnel) Aseprite, hUGETracker, flashcart

Hors périmètre de cet article. Voir docs/install_mac.md §5–§8 du pipeline pour Aseprite (wrapper ~/bin/aseprite), hUGETracker (uge2source), flashcart EverDrive / EZ-Flash.

Annexe — Ubuntu / Pop_OS

Sur Debian/Ubuntu 22.04 et dérivés (Pop_OS 22.04+), le paquet rgbds est disponible mais souvent en retard d’une version. Préférer le PPA officiel ou la release GitHub pour rester aligné sur le standard de la communauté gbdev.

# Outils de base
sudo apt update
sudo apt install -y build-essential git curl

# RGBDS — version Apt (peut être en retard)
sudo apt install -y rgbds
rgbasm --version

# Variante : compilation depuis la source (toujours à jour)
sudo apt install -y bison libpng-dev pkg-config
git clone https://github.com/gbdev/rgbds.git && cd rgbds
make -j"$(nproc)" && sudo make install

GBDK-2020 (release Linux x86_64) :

mkdir -p ~/gbdk-dl && cd ~/gbdk-dl
gh release download --repo gbdk-2020/gbdk-2020 --pattern 'gbdk-linux64.tar.gz'
tar xzf gbdk-linux64.tar.gz -C "$HOME"
echo 'export GBDK_HOME="$HOME/gbdk"' >> ~/.bashrc
echo 'export PATH="$GBDK_HOME/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
lcc -v

SameBoy : pas de paquet officiel pour Linux ; compiler depuis la source.

sudo apt install -y libsdl2-dev rgbds
git clone https://github.com/LIJI32/SameBoy.git && cd SameBoy
make sdl tester -j"$(nproc)"
sudo cp build/bin/SDL/sameboy ~/bin/
sudo cp build/bin/tester/sameboy_tester ~/bin/

Le reste (gh, Ruby + Bundler, hooks) suit les paquets standard d’Ubuntu et n’ajoute rien de spécifique au monde Game Boy.

Conclusion

En une demi-heure de travail effectif, on dispose d’un environnement complet : assembleur, compilateur C, émulateur visuel et émulateur headless pour tests automatisés. La pile est identique à celle qu’utilise la communauté gbdev contemporaine, ce qui facilite la lecture des tutoriels et l’usage des assets externes (musiques .uge, tilesets PNG).

La suite logique : un premier .asm qui pose le header Nintendo et initialise le LCD. C’est l’objet du prochain article.

Dépôt du pipeline (en cours d’ouverture publique) : https://github.com/levaleureux/gb_pipeline.