How nicolasiragne/gbmu works
Project type and purpose
• This is “GBmu,” a GameBoy emulator project. It ships two parallel implementations:
• A native C/C++ core + CLI/SDL‐based UI, built via CMake.
• A Rust “workspace” wrapping the same core via FFI (crates/bindings) plus two Rust executables (CLI and TUI debugger), built via Cargo.
• Its purpose is to emulate GameBoy hardware (CPU, PPU, GPU, timer, MMU, MBC) and expose a debugger/UI on top.
File structure
• Top‐level:
• srcs/ + includes/ + libyacc/ + CMakeLists.txt → C/C++ emulator core, debugger grammar, CLI debugger, SDL frontend (gbclodo).
• crates/ → Rust workspace:
– crates/bindings → build.rs uses cc crate to compile C core, providing safe FFI bindings.
– crates/shared → common Rust utilities.
– crates/gbmu → Rust CLI emulator, uses bindings + shared.
– crates/ui → Rust TUI debugger, uses bindings + shared.
• rom/, saves/, savestates/ → input ROMs & state persistence.
• scripts/ + docker/ + etc. → ancillary tooling.
• Build scripts:
• CMake and Makefile orchestrate the native build;
• Cargo.toml (workspace) orchestrates the Rust build.
README for additional insights
• Confirms CMake build for C/C++ binary (./gbmu <rom_file>), optional libyacc debugger vs. fallback_debugger.
• Mentions dependencies: GNU readline, SDL (implied by renderer_opengl), libyacc.
Main components & interactions
• Core Emulator Module (C code):
• CPU (includes registers, instruction decode, opcodes/)
• MMU (memory.c, io_map.c, MBC handlers)
• PPU/GPU (ppu.c, gpu.c, palette.c)
• Timer (timer.c), input (input_functions.c / joypad), sound (in DMG_SOUND.sav, not fully implemented),
• Savestate / Save‐game (savestate.c, save_game.c)
• Debugger Module (C++ and fallback):
• libyacc‐powered parser (libyacc_wrapper) + SymbolNonTerminal*/SymbolTerminal*
• Fallback (fallback_debugger.c, fallback_debugger.h)
• UI / Frontends:
• Native C CLI (“gbmu” binary)
• Native SDL/OpenGL GUI (“gbclodo” under srcs/gbclodo)
• Rust CLI (crates/gbmu)
• Rust TUI Debugger (crates/ui)
• FFI Layer:
• crates/bindings compiles and exposes the C core via Rust FFI (build.rs, bindings.rs)
• crates/shared shares error types & utilities in Rust
• External Dependencies:
• libreadline, SDL2/OpenGL, libyacc
Architectural patterns & design principles
• Layering / separation of concerns:
• Low‐level core (hardware emulation) completely independent of UI
• Debugger hooks wired into core via well‐defined C APIs
• Rust wrapper crate cleanly isolates FFI details (separation Rust/C)
• Build‐time abstraction:
• Two build systems side by side (CMake vs. Cargo)
• Conditional inclusion of libyacc vs. fallback using CMake variable WITH_LIBYACC
• Plugin/extension points: