106 lines
5.1 KiB
Markdown
106 lines
5.1 KiB
Markdown
# 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.
|
||
- The headless suite runner passes generated ARM/Thumb/BIOS cases, produces repeatable JSON, and rejects deliberate assertion mismatches.
|
||
|
||
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 hardware audio fidelity.
|
||
CPAL 0.16 is a macOS-only dependency of the desktop crate. The existing Nix Darwin shell builds its CoreAudio backend without extra shell packages.
|
||
Native tests submit an original tone and original ROM-generated samples to the default output device.
|
||
Use `--audio` with a ROM window to opt in. Ordinary tests and muted windows do not require an audio device.
|
||
Other host audio platforms are not implemented. Underruns remain possible; device callbacks do not prove listening quality.
|
||
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`:
|
||
|
||
```sh
|
||
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:
|
||
|
||
```sh
|
||
direnv allow
|
||
cargo run
|
||
cargo test
|
||
cargo fmt --all --check
|
||
cargo clippy --all-targets -- -D warnings
|
||
```
|
||
|
||
To run commands without a shell hook:
|
||
|
||
```sh
|
||
direnv allow .
|
||
direnv exec . cargo run --locked
|
||
direnv exec . cargo test --locked
|
||
```
|
||
|
||
`.envrc` uses the Nix flake to load Rust, Cargo, rustfmt, Clippy, and Python 3.
|
||
Python supports the pinned public-test preparation adapter and its standard-library-only tests.
|
||
`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.
|
||
|
||
## Portability boundary
|
||
|
||
The Rust `gba-core` owns CPU, memory, video, audio generation, input state, and cartridge protocols.
|
||
It has no external dependencies or filesystem, window, host-clock, or audio-device code.
|
||
The same core can serve another frontend; porting does not require rewriting emulated hardware.
|
||
This separation is a design boundary, not a completed Linux or WebAssembly port.
|
||
|
||
- Linux can reuse the desktop structure and Unix raw-save adapter. Build dependencies and native behavior still need validation.
|
||
Host audio currently returns an explicit unsupported-platform error outside macOS; add and test a Linux backend separately.
|
||
- A browser needs WebAssembly bindings, canvas presentation, browser input, Web Audio, and browser scheduling.
|
||
Its frontend must load ROM/image bytes and persist save images through browser storage or explicit import/export.
|
||
It cannot reuse desktop `.sav` filesystem operations or CoreAudio.
|
||
- Core save loading/inspection is byte-based. Flash commands never access host files.
|
||
Desktop [save persistence](hardware/saves.md#desktop-persistence) is tested on Darwin arm64 only.
|
||
|
||
Cross-compilation, performance, lifecycle handling, and save durability need tests on each target.
|
||
The core currently uses Rust's standard library; it is dependency-free, not a `no_std` crate.
|
||
|
||
Without direnv, use:
|
||
|
||
```sh
|
||
nix develop
|
||
```
|
||
|
||
For one command without entering a shell:
|
||
|
||
```sh
|
||
nix develop -c cargo test
|
||
```
|