docs: Add build guide

BUILD_GUIDE.md

@@ -0,0 +1,253 @@
+# Pinky Build & Run Guide
+
+This guide provides detailed instructions for building and running Pinky NES emulator on various platforms.
+
+## Quick Start
+
+### Linux (libretro/RetroArch)
+
+```bash
+# Build the libretro core
+cd pinky-libretro
+cargo build --release
+
+# Use with RetroArch
+retroarch -L target/release/libpinky_libretro.so game.nes
+```
+
+### Web Browser
+
+Visit the [web demo](http://koute.github.io/pinky-web/) to play directly in your browser.
+
+## Building from Source
+
+### Prerequisites
+
+- Rust (1.70+ recommended)
+- Cargo
+
+For specific frontends, additional dependencies may be required.
+
+### Building the libretro Core
+
+The libretro core is the primary way to run Pinky with full frontend support.
+
+```bash
+cd pinky-libretro
+cargo build
+```
+
+**Debug build**: `target/debug/libpinky_libretro.so` (Linux) or `.dll` (Windows)
+**Release build**: `target/release/libpinky_libretro.so` (faster, recommended)
+
+#### Using with RetroArch
+
+1. Copy the built library to RetroArch's core directory:
+   ```bash
+   cp target/release/libpinky_libretro.so ~/.config/retroarch/cores/
+   ```
+
+2. Load the core in RetroArch:
+   - Menu → Load Core → pinky_libretro
+   - Load Content → Select your NES ROM
+
+3. Or use command line:
+   ```bash
+   retroarch -L ~/.config/retroarch/cores/libpinky_libretro.so game.nes
+   ```
+
+### Building the SDL2 Development UI
+
+The `pinky-devui` provides a simple standalone frontend for testing.
+
+```bash
+# Install SDL2 dependencies (Ubuntu/Debian)
+sudo apt-get install libsdl2-dev
+
+# Build
+cd pinky-devui
+cargo build --release
+```
+
+Run with a ROM:
+```bash
+./target/release/pinky-devui game.nes
+```
+
+### Building for Web (WASM)
+
+```bash
+# Install wasm-pack
+cargo install wasm-pack
+
+# Build for web
+cd pinky-web
+wasm-pack build --target web --release
+```
+
+Deploy the `pkg` directory to a web server.
+
+## Platform-Specific Instructions
+
+### Windows
+
+#### Prerequisites
+
+- Visual Studio Build Tools or Visual Studio
+- Rust (via rustup)
+
+#### Building libretro Core
+
+```bash
+cd pinky-libretro
+cargo build --release
+```
+
+The DLL will be at `target\release\pinky_libretro.dll`.
+
+**RetroArch for Windows**:
+1. Copy DLL to RetroArch's `cores` folder
+2. Load core via Menu → Load Core
+
+### macOS
+
+#### Prerequisites
+
+```bash
+# Install Xcode command line tools
+xcode-select --install
+
+# Install Rust
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+```
+
+#### Building
+
+```bash
+cd pinky-libretro
+cargo build --release
+```
+
+The dylib will be at `target/release/libpinky_libretro.dylib`.
+
+### Android
+
+Pinky can be built for Android via the libretro core.
+
+1. Install Android NDK
+2. Set up Rust for Android:
+   ```bash
+   rustup target add aarch64-linux-android
+   ```
+
+3. Build:
+   ```bash
+   cargo build --target aarch64-linux-android --release
+   ```
+
+Use with RetroArch for Android.
+
+## Supported Mappers
+
+| ID | Name | Games |
+|----|------|-------|
+| 0 | NROM | Super Mario Bros, Tetris |
+| 1 | MMC1 | The Legend of Zelda, Metroid |
+| 2 | UxROM | Castlevania, Final Fantasy |
+| 7 | AxROM | Battletoads |
+| 30 | UNROM 512 | Homebrew games |
+
+Check [nesmapper.txt](http://tuxnes.sourceforge.net/nesmapper.txt) for which games use which mapper.
+
+## Known Limitations
+
+- Most unofficial 6502 instructions not implemented
+- Limited mapper support (see above)
+- PPU sprite overflow not fully accurate
+- No savestate support yet
+- PAL region not fully supported
+
+## Troubleshooting
+
+### Build Fails
+
+Ensure you have the latest Rust:
+```bash
+rustup update
+```
+
+### Game Doesn't Run
+
+1. Check if the ROM's mapper is supported
+2. Verify ROM file is not corrupted
+3. Try a different ROM (e.g., homebrew test ROMs)
+
+### Slow Performance (Debug Build)
+
+Debug builds are unoptimized. Use release builds:
+```bash
+cargo build --release
+```
+
+### Web Version Doesn't Load
+
+- Ensure CORS headers are set correctly on your web server
+- Check browser console for errors
+- Try a different browser (Chrome/Firefox recommended)
+
+## Testing
+
+Run the test suite:
+
+```bash
+cd nes-testsuite
+cargo test
+```
+
+This runs various NES test ROMs to verify emulation accuracy.
+
+## Development
+
+### Project Structure
+
+```
+pinky/
+├── emumisc/           # Emulator utilities
+├── mos6502/           # 6502 CPU emulation
+├── nes/               # Core NES emulation
+├── nes-testsuite/     # Test ROMs
+├── pinky-libretro/    # libretro frontend
+├── pinky-devui/       # SDL2 dev UI
+├── pinky-web/         # WebAssembly build
+└── rp2c02-testsuite/  # PPU test suite
+```
+
+### Running PPU Tests
+
+```bash
+cd rp2c02-testsuite
+cargo test
+```
+
+This runs automatically generated tests from Visual2C02 transistor-level simulation.
+
+## Resources
+
+- [NESdev Wiki](http://wiki.nesdev.com/w/index.php/Nesdev_Wiki) - Primary documentation
+- [nesmapper.txt](http://tuxnes.sourceforge.net/nesmapper.txt) - Mapper reference
+- [Visual2C02](https://github.com/whatmough/visual2c02) - PPU transistor simulation
+- [RetroArch](https://www.retroarch.com/) - Recommended frontend
+
+## Contributing
+
+Contributions welcome! Areas needing work:
+
+- Additional mapper support
+- Savestate implementation
+- PAL support
+- Unofficial 6502 instructions
+- Accuracy improvements
+
+---
+
+*Community contribution - unofficial build guide*