Building from Source

Building from Source

This guide covers building RustySNES's native desktop, no_std chip-stack, and WebAssembly targets.

Prerequisites

1. Rust toolchain. RustySNES targets Rust 1.96 (edition 2024), pinned in rust-toolchain.toml. Install via rustup; it will auto-install the pinned toolchain plus the wasm32-unknown-unknown and thumbv7em-none-eabihf targets the quality gates below exercise.

2. System dependencies (Linux only). The frontend crate links against wgpu/winit/cpal system libraries:

   # Debian / Ubuntu
   sudo apt-get install -y libxkbcommon-dev libwayland-dev libxkbcommon-x11-dev libasound2-dev libudev-dev
   # Arch / CachyOS
   sudo pacman -S --needed libxkbcommon wayland alsa-lib systemd-libs

macOS and Windows need no extra system packages beyond a working Rust toolchain.

Standard desktop build

# Build the whole workspace
cargo build --release --workspace

# Run the emulator against a ROM
cargo run --release -p rustysnes-frontend -- path/to/rom.sfc

Quality gate

This is the same gate CI enforces on every release-tag push (ci.yml's full-test/no_std jobs) and that every PR is expected to pass locally before review:

cargo fmt --all --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
cargo test --workspace --features test-roms       # adds the committed test-ROM oracle
RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps
cargo build -p rustysnes-core --target thumbv7em-none-eabihf --no-default-features

Never run cargo clippy --all-features — some optional frontend features are mutually exclusive and the feature set cannot resolve together. Use the explicit gate above (default features) instead.

The last command is the no_std gate: the chip crates (rustysnes-cpu, rustysnes-ppu, rustysnes-apu, rustysnes-cart, rustysnes-core) are no_std + alloc and must build for a bare embedded target with default features disabled. This is a hard architectural constraint, not a stretch goal — see Architecture-Overview.

WebAssembly build

rustup target add wasm32-unknown-unknown
cargo install trunk --locked

cd crates/rustysnes-frontend/web
trunk build --release      # production build, output in dist/
trunk serve                # local dev server with hot reload

The wasm target compiles and CI builds it on every main push (deployed to the GitHub Pages demo), but the in-browser UI itself is currently a bootstrap scaffold rather than the full playable frontend — see Roadmap and Frontend-Architecture for where that lands in the release ladder.

Contributing

See CONTRIBUTING.md in the main repository for the branch-naming convention, commit-message format, and code-review expectations. Pick a ticket from to-dos/ (or open an issue first if your work isn't already represented there), and reference the ticket ID in your commits and PR.