7d396fea35
Move the README's hardware notes, demo controls, environment setup, test notes, file map, and references into docs/ and docs/hardware/. The README is now an overview with a docs index. AGENTS.md gives coding agents a short map of crates, commands, and where to read and write documentation. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
80 lines
2.9 KiB
Markdown
80 lines
2.9 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.
|
||
|
||
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.
|
||
The new CPU graphics demo has automated input-mapping tests; its 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, 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:
|
||
|
||
```sh
|
||
nix develop
|
||
```
|
||
|
||
For one command without entering a shell:
|
||
|
||
```sh
|
||
nix develop -c cargo test
|
||
```
|