From 8769cf6dea663549983ab70b6c3b0c4ae15cc7b0 Mon Sep 17 00:00:00 2001
From: Michael G <10155689+DarthMDev@users.noreply.github.com>
Date: Wed, 9 Sep 2026 12:23:15 -0400
Subject: [PATCH] docs: add macOS source build guide for WiiCompiled and Retro
 Rewind (#177)

* docs: add macOS source build guide for WiiCompiled and Retro Rewind

* review fixes

* Change Retro-WFC payload download URL

Updated the URL for downloading Retro-WFC payload.
---
 README.md              |   4 +-
 docs/building-macos.md | 349 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 352 insertions(+), 1 deletion(-)
 create mode 100644 docs/building-macos.md

diff --git a/README.md b/README.md
index d616cb4..396cf9b 100644
--- a/README.md
+++ b/README.md
@@ -150,7 +150,9 @@ The default test suite needs no binaries and no host C++ compiler, so you can ha
 translator without any game data around.
 
 For everything beyond that, feeding in your own `main.dol`/`StaticR.rel`, running the
-translation, generating the manifest and build graph, and compiling. see [`translator/README.md`](translator/README.md).
+translation, generating the manifest and build graph, and compiling, see [`translator/README.md`](translator/README.md).
+
+For a step-by-step guide on compiling both WiiCompiled and Retro Rewind from source on macOS (Apple Silicon), see the [macOS Build Guide](docs/building-macos.md).
 
 ## FAQ
 
diff --git a/docs/building-macos.md b/docs/building-macos.md
new file mode 100644
index 0000000..6c8aa95
--- /dev/null
+++ b/docs/building-macos.md
@@ -0,0 +1,349 @@
+# Building WiiCompiled and Retro Rewind on macOS
+
+This guide covers building **WiiCompiled** (base game) and **Retro Rewind** from source on macOS for Apple Silicon (`arm64`). Follow these instructions to compile the native executables directly.
+
+> [!NOTE]
+> If you only want to build the base game (**WiiCompiled**), look for sections marked **`(Skip if only building WiiCompiled)`** to bypass Retro Rewind and online payload steps.
+
+---
+
+## 1. Prerequisites
+
+### System Requirements
+- **Hardware**: Apple Silicon Mac (M1/M2/M3/M4)
+- **Operating System**: macOS 14 (Sonoma) or later
+- **Xcode Command Line Tools**:
+  ```bash
+  xcode-select --install
+  ```
+
+### Toolchain Dependencies
+Install the required tools using [Homebrew](https://brew.sh):
+```bash
+brew install cmake ninja
+brew install --cask dotnet-sdk@8
+```
+
+Verify that Clang, CMake, Ninja, and the .NET 8 runtime are available:
+```bash
+clang --version
+cmake --version
+ninja --version
+dotnet --list-runtimes   # Must list Microsoft.NETCore.App 8.x
+```
+
+---
+
+## 2. Required Game and Mod Assets
+
+Due to legal requirements, no proprietary Nintendo assets or code are included in this repository. You must provide your own legally dumped game files.
+
+1. **Mario Kart Wii PAL (`RMCP01`) Disc Image** *(Required)*:
+   - Supported formats: `.iso`, `.wbfs`, `.ciso`, `.rvz`, `.gcm`, `.gcz`.
+2. **nodtool** *(Required for disc extraction)*:
+   - Download the macOS Apple Silicon binary of [nodtool](https://github.com/encounter/nod/releases):
+     ```bash
+     curl -fsSL "https://github.com/encounter/nod/releases/download/v2.0.0-alpha.10/nodtool-macos-arm64" -o nodtool
+     chmod +x nodtool
+     ```
+3. **Retro Rewind Distribution** *(Skip if only building WiiCompiled)*:
+   - Download the [Retro Rewind](https://wiki.tockdom.com/wiki/Retro_Rewind) release package. You will need the `RetroRewind6` folder (which contains `Binaries/Code.pul`).
+4. **Retro-WFC Payload** *(Skip if only building WiiCompiled or building offline)*:
+   - Required for online multiplayer on Retro Rewind. Downloaded during setup from `http://nas.play.rwfc.net/payload?g=RMCPD00`.
+
+---
+
+## 3. Step 1: Extract Disc Assets
+
+Extract your clean PAL `RMCP01` disc into the `Assets/` directory of the repository:
+
+```bash
+# Using nodtool directly into a temporary scratch directory
+mkdir -p /tmp/mkw-extract
+./nodtool extract /path/to/RMCP01.iso /tmp/mkw-extract
+
+# Copy extracted assets into the repository Assets directory
+rm -rf Assets/DATA/files Assets/DATA/sys
+mkdir -p Assets/DATA
+cp /tmp/mkw-extract/*/sys/main.dol Assets/main.dol
+cp /tmp/mkw-extract/*/files/rel/StaticR.rel Assets/StaticR.rel
+cp -R /tmp/mkw-extract/*/files Assets/DATA/files
+cp -R /tmp/mkw-extract/*/sys Assets/DATA/sys
+
+# Clean up temporary files
+rm -rf /tmp/mkw-extract
+```
+
+> [!TIP]
+> Alternatively, you can use the repository's helper script:
+> ```bash
+> Launcher/macos/extract-disc.command --game /path/to/RMCP01.iso --assets-dir Assets --nodtool ./nodtool
+> ```
+
+### Verify Extracted Asset Hashes
+Confirm that the extracted files match the expected clean PAL revision:
+```bash
+shasum -a 256 Assets/main.dol Assets/StaticR.rel
+```
+- `Assets/main.dol`: `80d18895b39c63bd80f457398bfcbb91b7d16ac116a41a88967e954080155b05`
+- `Assets/StaticR.rel`: `16d9d146112541fefea701ecb5bc1a496f9d50e4a752fbb5b6778e7c6399f67d`
+
+---
+
+## 4. Step 2: Build the Translator CLI
+
+Compile the static recompiler CLI:
+
+```bash
+dotnet build translator/src/Translator.Cli/Translator.Cli.csproj -c Release
+```
+
+Define a shell function to invoke the translator (ensuring paths with spaces are handled safely):
+```bash
+translator() {
+  dotnet "$(pwd)/translator/src/Translator.Cli/bin/Release/net8.0/Translator.Cli.dll" "$@"
+}
+```
+
+---
+
+## 5. Step 3: Translation
+
+### A. Translate Base Game Functions
+```bash
+mkdir -p generated/functions build/base
+
+translator translate-recursive 0x8000629c \
+  --project projects/mkwii/recomp.yml \
+  --outdir generated/functions \
+  --output-metadata generated/base_translation_output.json \
+  --production-source-bundle generated/base_translation_sources.bin \
+  --no-function-files \
+  --prune-stale \
+  --threads $(sysctl -n hw.ncpu)
+```
+
+### B. Emit Base Manifest
+```bash
+translator emit-base-manifest \
+  --project projects/mkwii/recomp.yml \
+  --out build/base \
+  --functions-dir generated/functions \
+  --translation-output-metadata generated/base_translation_output.json \
+  --region P
+```
+
+---
+
+### C. Stage and Translate Retro Rewind *(Skip this step if you only want to build WiiCompiled)*
+
+1. Stage `Code.pul`:
+   ```bash
+   RETRO_DIR="/path/to/RetroRewind6"
+   mkdir -p PulsarPacks/completed/RetroRewind/RetroRewind6/Binaries
+   cp "$RETRO_DIR/Binaries/Code.pul" PulsarPacks/completed/RetroRewind/RetroRewind6/Binaries/Code.pul
+   ```
+
+2. **Retro-WFC Payload Setup (for Online Multiplayer)**:
+   Online play in Retro Rewind requires the shared Retro-WFC payload. Download and validate it:
+   ```bash
+   mkdir -p build/retro-wfc/binary
+   curl -fsSL --retry 3 "https://nas.play.rwfc.net/payload?g=RMCPD00" \
+     -o build/retro-wfc/binary/payload.RMCPD00.bin
+
+   # Validate payload signature and integrity
+   translator validate-retro-wfc-payload --directory build/retro-wfc
+   ```
+
+3. Run Retro Rewind translation:
+   ```bash
+   mkdir -p build/mods/retro_rewind_full_cpp
+
+   translator translate-mod \
+     --project projects/mkwii/recomp.yml \
+     --profile retro-rewind \
+     --base-manifest build/base/mkwii_base_manifest.json \
+     --base-translation-output-metadata generated/base_translation_output.json \
+     --code-pul "$RETRO_DIR/Binaries/Code.pul" \
+     --mod-root "$RETRO_DIR" \
+     --mod-name "Retro Rewind" \
+     --region P \
+     --out build/mods/retro_rewind_full_cpp \
+     --prefer-cached-inputs \
+     --emit-cpp \
+     --threads $(sysctl -n hw.ncpu) \
+     --retro-wfc-payload build/retro-wfc/binary/payload.RMCPD00.bin
+   ```
+   > [!TIP]
+   > If you do not want online play or do not have an internet connection, replace `--retro-wfc-payload ...` with `--skip-retro-wfc`.
+
+---
+
+### D. Generate Data Initialization and Build Shards
+
+First, generate the embedded game data initializer:
+```bash
+translator generate-data-init --project projects/mkwii/recomp.yml
+```
+
+Next, generate the CMake build shards using **one** of the following options:
+
+#### Option 1: Base Game Only (WiiCompiled)
+```bash
+mkdir -p generated/build_shards
+translator emit-build-shards \
+  --project projects/mkwii/recomp.yml \
+  --base-metadata generated/base_translation_output.json \
+  --base-functions-dir generated/functions \
+  --native-source-dir runtime/src \
+  --out generated/build_shards
+```
+
+#### Option 2: Base Game + Retro Rewind
+```bash
+mkdir -p generated/build_shards
+translator emit-build-shards \
+  --project projects/mkwii/recomp.yml \
+  --base-metadata generated/base_translation_output.json \
+  --base-functions-dir generated/functions \
+  --native-source-dir runtime/src \
+  --out generated/build_shards \
+  --resolved-profile build/mods/retro_rewind_full_cpp/resolved_dispatch_profile.json \
+  --retro-cpp-dir build/mods/retro_rewind_full_cpp/cpp
+```
+
+---
+
+## 6. Step 4: Configure and Compile with CMake & Ninja
+
+Configure the native C++ build targeting Apple Silicon:
+
+```bash
+cmake -S runtime -B build-macos -G Ninja \
+  -DCMAKE_BUILD_TYPE=Release \
+  -DCMAKE_C_COMPILER=clang \
+  -DCMAKE_CXX_COMPILER=clang++ \
+  -DAURORA_SDL3_PROVIDER=vendor
+```
+
+Compile the desired target:
+
+```bash
+# To build WiiCompiled only:
+cmake --build build-macos --target WiiCompiled --parallel $(sysctl -n hw.ncpu)
+
+# OR to build both WiiCompiled and Retro Rewind:
+cmake --build build-macos --target WiiCompiled RetroRewind --parallel $(sysctl -n hw.ncpu)
+```
+
+Once compilation completes, the executables are ready in your build directory:
+- `build-macos/WiiCompiled`
+- `build-macos/RetroRewind` (if built)
+
+During the build, CMake automatically copies the required runtime assets into `build-macos/`:
+- `build-macos/dsp_coef.bin`
+- `build-macos/initial_pipeline_cache.db`
+- `build-macos/wii_bootstrap/`
+
+---
+
+## 7. Step 5: Running Executables from the Build Folder
+
+### Configure `Config.toml`
+The runtime reads configuration from `~/Library/Application Support/WiiCompiled/Config.toml`.
+
+Create the directory and configuration file:
+
+```bash
+mkdir -p "$HOME/Library/Application Support/WiiCompiled"
+```
+
+#### For Base Game Only (WiiCompiled):
+```toml
+# ~/Library/Application Support/WiiCompiled/Config.toml
+[video]
+widescreen = true
+resolution_multiplier = 1.0
+graphics_api = "metal"
+
+[paths]
+dvd_root = "/absolute/path/to/Wiicompiled/Assets/DATA"
+```
+
+#### For Base Game and Retro Rewind:
+```toml
+# ~/Library/Application Support/WiiCompiled/Config.toml
+[video]
+widescreen = true
+resolution_multiplier = 1.0
+graphics_api = "metal"
+
+[paths]
+dvd_root = "/absolute/path/to/Wiicompiled/Assets/DATA"
+retro_rewind_root = "/path/to/RetroRewind6"
+```
+
+> [!NOTE]
+> Ensure `dvd_root` points to the directory containing `files` and `sys/fst.bin`.
+
+### Launching the Game
+Run the compiled binaries directly from your terminal or by double clicking:
+
+```bash
+# Run base WiiCompiled
+./build-macos/WiiCompiled
+
+# Run Retro Rewind
+./build-macos/RetroRewind
+```
+
+
+
+Press **F10** in-game at any time to open the configuration bar (controls, resolution, display settings, audio).
+
+---
+
+## Quick Reference: Automated Helper Script
+
+The repository provides a script (`Launcher/local-build-macos.command`) that handles extraction, translation, and compilation in a single command.
+
+### Building Base Game Only:
+```bash
+Launcher/local-build-macos.command \
+  --profile base \
+  --output-dir build-macos/Products \
+  --game /path/to/RMCP01.iso \
+  --nodtool ./nodtool
+```
+
+### Building Both (with Online Retro-WFC Payload):
+```bash
+# 1. Download Retro-WFC payload into a staging directory:
+mkdir -p build/retro-wfc/binary
+curl -fsSL --retry 3 "http://nas.play.rwfc.net/payload?g=RMCPD00" \
+  -o build/retro-wfc/binary/payload.RMCPD00.bin
+
+# 2. Run the automated build with the payload directory:
+Launcher/local-build-macos.command \
+  --profile both \
+  --output-dir build-macos/Products \
+  --base-output-dir build-macos/Products \
+  --game /path/to/RMCP01.iso \
+  --nodtool ./nodtool \
+  --retro-rewind-package-dir /path/to/RetroRewind6 \
+  --retro-wfc-offline-dir build/retro-wfc
+```
+
+### Building Both (Offline, Skipping Payload):
+```bash
+Launcher/local-build-macos.command \
+  --profile both \
+  --output-dir build-macos/Products \
+  --base-output-dir build-macos/Products \
+  --game /path/to/RMCP01.iso \
+  --nodtool ./nodtool \
+  --retro-rewind-package-dir /path/to/RetroRewind6 \
+  --skip-retro-wfc-payload
+```
+
+When finished, the compiled executables reside in `native-build-macos/` and the bundled `.app` packages are placed in `build-macos/Products/`.