Building from Source

Building from Source

The authoritative build instructions are the README's quick start, docs/build-and-tooling.md and CONTRIBUTING.md. This page summarises them.

Toolchain

The toolchain is pinned in rust-toolchain.toml (Rust 1.99 at v3.2.0; the workspace uses edition 2024), so rustup installs the right version automatically. On Linux the window, GPU and audio stack need a few system libraries:

# Ubuntu / Debian
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

The optional retroachievements feature needs a C compiler on every platform, as does native Lua scripting.

Desktop

cargo run --release -p rustynes-frontend -- path/to/rom.nes

# Every native feature at once (RetroAchievements, Lua, host IPC, HD packs,
# debugger telemetry, A/V recording): the `full` feature, via a cargo alias.
cargo full-run path/to/rom.nes
cargo full-build

Do not build with --all-features: some features are mutually exclusive (the native and WebAssembly Lua backends, for example), so CI and the hooks always name features explicitly.

WebAssembly

Install trunk and run trunk serve (development) or trunk build --release in crates/rustynes-frontend/web. The default browser build is wasm-winit; --no-default-features --features wasm-canvas gives a lighter embed. The wasm-bindgen version pinned in web/Trunk.toml must match the library version in Cargo.lock.

Libretro core

The crate Makefile in crates/rustynes-libretro builds the rustynes_libretro shared library for the host platform. See Libretro-Core.

Mobile

The Android and iOS apps have their own build instructions in docs/android.md and docs/ios.md.

Quality gates

CI requires these to pass. CONTRIBUTING.md has the full pull-request checklist, including the no_std cross-compile of the chip stack, and AGENTS.md lists the per-feature clippy runs.

cargo fmt --all --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
cargo test --workspace --features test-roms   # adds the test-ROM suites