0xrsydn/gameboy-rust
1
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
gameboy-rust/docs/development.md
0xrsydn 109c1ffe81 feat(desktop): run ROM files in a window with keypad input 
Add --rom PATH --window with optional bounded --frames execution. Capture from BIOS boot, pump native events between bounded machine slices, retain frames during STOP, and sample keypad input for wake-up. Share final machine reports with terminal mode.

Add an original file-exportable input ROM, controller and CLI regressions, and opt-in native window tests. Document controls, frame limits, STOP behavior, and compatibility limits. Verified on Darwin arm64: debug/release workspace and core tests, Clippy, rustdoc, native ROM diagnostics, all ten demo smoke tests, and a 60-frame release ROM run.
2026-10-05 19:22:13 +07:00

3.1 KiB
Raw Blame History

Development environment

macOS (Darwin) is the first development and validation target. Build and test new features on Apple Silicon macOS before expanding platform support. Future window, input, and audio libraries must support native macOS.

Install Nix with nix-command and flakes enabled, plus direnv. The flake defines shells for Apple Silicon macOS, Intel macOS, ARM64 Linux, and x86-64 Linux. Only Apple Silicon macOS is verified. Intel macOS and Linux remain untested.

Verified locally on macOS 15.7.3:

  • Nix system: aarch64-darwin.
  • Rust host: aarch64-apple-darwin.
  • Release executable: native Mach-O arm64, without Rosetta.
  • All tests pass in debug and release builds.
  • All ten native window smoke tests pass. The mosaic test submits 128 frames; the other nine submit 60 frames each.
  • The eight CPU-driven smoke tests check CPU state, every output pixel, and presentation at VBlank entry.
  • The terminal-only CPU and timer IRQ demos run successfully.
  • The bounded terminal ROM runner loads original raw programs and reports state without opening a window.
  • The native ROM-window test presents a file-backed original program and reports STOP, CPU, and video failures.

These results cover the CPU core, memory, Mode 0–5 snapshots and row capture, input mapping, and desktop windows. They do not verify a complete GBA display controller or audio. Arrow-key movement in the original host display test was confirmed manually on this Mac. CPU demos and ROM windows have automated input-mapping tests; their physical keyboard behavior still needs manual confirmation.

Enable the direnv hook in your shell if it is not already configured. For zsh, add this line to ~/.zshrc:

eval "$(direnv hook zsh)"

For bash, use eval "$(direnv hook bash)" in ~/.bashrc instead. Restart your shell after changing its configuration.

From this project directory:

direnv allow
cargo run
cargo test
cargo fmt --all --check
cargo clippy --all-targets -- -D warnings

To run commands without a shell hook:

direnv allow .
direnv exec . cargo run --locked
direnv exec . cargo test --locked

.envrc uses the Nix flake to load Rust, Cargo, rustfmt, and Clippy. flake.lock pins the Nix package source. Keep it in version control. The first run needs network access to download the development tools and Rust dependencies.

The pinned Nix Darwin toolchain targets macOS 14.0 or newer. The flake sets Darwin-only CFLAGS to correct two minifb 0.28 native-build issues:

  • Override its macOS 10.10 deployment flag, which predates the Metal APIs it uses.
  • Use -fcommon for its shared tentative Objective-C global definition.

Build through direnv or nix develop so these settings apply. The window runs on the main thread, as required by macOS AppKit. crates/desktop/src/desktop.rs also corrects the inverted macOS focus result in minifb 0.28.0. The dependency is pinned to that exact version. Review this workaround before upgrading minifb. Intel macOS and Linux desktop builds are not verified.

Without direnv, use:

nix develop

For one command without entering a shell:

nix develop -c cargo test