This document is the single source of truth for configuring, building, and testing YAZE on all platforms. Other documentation files link here rather than duplicating these instructions.

0. Standard Local Workflow

For day-to-day local development on a configured machine, use the unified workflow script:

scripts/dev/local-workflow.sh all

Useful subcommands:

scripts/dev/local-workflow.sh build
scripts/dev/local-workflow.sh test
scripts/dev/local-workflow.sh sync
scripts/dev/local-workflow.sh status
scripts/dev/local-workflow.sh hooks
scripts/dev/local-workflow.sh release-check

What sync does on macOS:

Updates /Applications/yaze.app from the selected build output.
Refreshes PATH link for z3ed (default: /usr/local/bin/z3ed).
Verifies runtime binary hashes after copy/link.

1. Environment Setup

Clone the Repository

git clone --recursive https://github.com/scawful/yaze.git

cd yaze

Verify Your Environment

Run the verification script once per machine to check dependencies and fix common issues:

macOS / Linux:

./scripts/verify-build-environment.sh --fix

Windows (PowerShell):

.\scripts\verify-build-environment.ps1 -FixIssues

macOS Toolchain Selection

AppleClang (/usr/bin/clang) is the default and most reliable choice. If Homebrew LLVM is on your PATH and you hit SDK header errors, pick the toolchain explicitly:

# AppleClang (recommended)
cmake --preset mac-dbg --fresh -DCMAKE_C_COMPILER=/usr/bin/clang -DCMAKE_CXX_COMPILER=/usr/bin/clang++
 
# Homebrew LLVM (optional)
cmake --preset mac-dbg --fresh -DCMAKE_TOOLCHAIN_FILE=cmake/llvm-brew.toolchain.cmake

2. Build Presets

YAZE uses CMake presets for consistent builds. Configure with cmake --preset <name>, then build with cmake --build --preset <name>.

Available Presets (High Level)

macOS: mac-dbg, mac-dbg-v, mac-rel, mac-dev, mac-ai, mac-ai-fast, mac-uni, mac-sdl3, mac-test
Windows: win-dbg, win-dbg-v, win-rel, win-dev, win-ai, win-z3ed, win-arm, win-arm-rel, win-vs-dbg, win-vs-rel, win-vs-ai, win-sdl3, win-test
Linux: lin-dbg, lin-dbg-v, lin-rel, lin-dev, lin-ai, lin-sdl3, lin-test
iOS: ios-debug, ios-release (device builds for the thin Xcode shell)
CI: ci-linux, ci-macos, ci-windows, ci-windows-ai
WASM: wasm-debug, wasm-release, wasm-crash-repro, wasm-ai

mac-ai-fast prefers the Homebrew gRPC/protobuf stack for faster configure times (brew install grpc protobuf abseil).

Tip: Add -v suffix (e.g., mac-dbg-v) to enable verbose compiler warnings.

iOS (Device) Build Flow

Use the thin iOS shell backed by CMake-built static libs:

scripts/build-ios.sh # builds ios-debug + generates Xcode project

scripts/build-ios.sh ios-release

This generates src/ios/yaze_ios.xcodeproj and a bundled static library at build-ios/ios/libyaze_ios_bundle.a. Open the Xcode project and run on device. Requires xcodegen (brew install xcodegen) and the iOS SDK from Xcode.

For CLI-driven device deploys (build + install + optional launch):

scripts/xcodebuild-ios.sh ios-debug deploy

scripts/xcodebuild-ios.sh ios-debug deploy "Baby Pad"

deploy resolves the app bundle from DerivedData and installs via xcrun devicectl. Device selection order is DEVICE arg, $YAZE_IOS_DEVICE, then "Baby Pad".

For multi-iPad deploy loops (build once + install to many devices):

scripts/dev/ios-ipad-workflow.sh instant --all
scripts/dev/ios-ipad-workflow.sh instant --devices "Baby Pad,iPadothée Chalamet" --no-launch
scripts/dev/ios-ipad-workflow.sh redeploy --all --no-launch

instant caches an iOS source fingerprint and skips rebuilds when inputs haven't changed, making repeated installs much faster.

3. Build Directory Policy

Build Type	Default Directory
Native (desktop/CLI)	`build/`
Native (AI presets)	`build_ai/`
WASM	`build-wasm/`

macOS and Windows presets use multi-config generators, so binaries live under build_ai/bin/Debug or build_ai/bin/Release (AI presets) and build/bin/... (non-AI presets). Linux uses single-config builds in build/bin or build_ai/bin depending on preset.

If you need per-user or per-agent isolation, create a local CMakeUserPresets.json that points binaryDir to a custom path outside the repo. Avoid creating additional build_* folders beyond build/ and build_ai/ to keep the checkout small.

Example:

cp CMakeUserPresets.json.example CMakeUserPresets.json
export YAZE_BUILD_ROOT="$HOME/.cache/yaze"
cmake --preset dev-local
cmake --build --preset dev-local --target yaze

You can also set YAZE_BUILD_DIR for scripts and the agent build tool to direct builds to an external path:

export YAZE_BUILD_DIR="$HOME/.cache/yaze/build"

For AI-enabled builds, use the *-ai presets and specify only the targets you need:

cmake --build --preset mac-ai --target yaze z3ed

Local AI Runtime Deploy (Recommended)

Use the unified workflow to build from build_ai presets and sync the runtime bundle to a single canonical app path: /Applications/yaze.app.

scripts/dev/local-workflow.sh all

For faster iteration when tests are already green:

scripts/dev/local-workflow.sh build --skip-tests

scripts/dev/local-workflow.sh sync

Menu launchers (SketchyBar, Raycast, Alfred, etc.) should target:

open -a "/Applications/yaze.app"

The sync workflow also prunes legacy aliases such as /Applications/Yaze.app and older Nightly app links when present.

Shared Dependency Caches (Recommended)

Set shared caches once per machine to avoid re-downloading dependencies after cleaning build directories.

macOS / Linux:

export CPM_SOURCE_CACHE="$HOME/.cpm-cache"
export VCPKG_DOWNLOADS="$HOME/.cache/vcpkg/downloads"
export VCPKG_BINARY_SOURCES="clear;files,$HOME/.cache/vcpkg/bincache,readwrite"

Windows (PowerShell):

$env:CPM_SOURCE_CACHE = "$env:USERPROFILE\.cpm-cache"
$env:VCPKG_DOWNLOADS = "$env:LOCALAPPDATA\vcpkg\downloads"
$env:VCPKG_BINARY_SOURCES = "clear;files,$env:LOCALAPPDATA\vcpkg\bincache,readwrite"

You can also set these in CMakeUserPresets.json (see CMakeUserPresets.json.example).

Windows Helper Scripts:

Quick builds: scripts/agents/windows-smoke-build.ps1
Test runs: scripts/agents/run-tests.sh (or PowerShell equivalent)

4. Common Build Commands

Tip: Prefer ./scripts/yaze and ./scripts/z3ed to run the newest local binary (the wrappers prefer build_ai/ outputs when available).

Standard Debug Build

macOS:

cmake --preset mac-dbg

cmake --build --preset mac-dbg --target yaze

Linux:

cmake --preset lin-dbg

cmake --build --preset lin-dbg --target yaze

Windows:

cmake --preset win-dbg

cmake --build --preset win-dbg --target yaze

AI-Enabled Build (with gRPC and z3ed CLI)

macOS:

cmake --preset mac-ai

cmake --build --preset mac-ai --target yaze z3ed

Linux:

cmake --preset lin-ai

cmake --build --preset lin-ai --target yaze z3ed

Windows:

cmake --preset win-ai

cmake --build --preset win-ai --target yaze z3ed

5. Testing

YAZE uses CTest with GoogleTest. Tests are organized by category using labels.

Quick Start

# Run stable tests (fast, no ROM required)
ctest --test-dir build -L stable -j4
 
# Run all enabled tests
ctest --test-dir build --output-on-failure
 
# Run tests matching a pattern
ctest --test-dir build -R "Dungeon"

Direct Test Binaries

# macOS/Windows (multi-config)
./build/bin/Debug/yaze_emu_test --emu_test_rom=roms/alttp_vanilla.sfc
./build/bin/Debug/yaze_test_unit --rom=roms/alttp_vanilla.sfc
./build/bin/Debug/yaze_test_integration --rom=roms/alttp_vanilla.sfc
./build/bin/Debug/yaze_test_gui --rom=roms/alttp_vanilla.sfc
./build/bin/Debug/yaze_test_benchmark --rom=roms/alttp_vanilla.sfc
 
# Linux (single-config)
./build/bin/yaze_emu_test --emu_test_rom=roms/alttp_vanilla.sfc

Test Categories

Category	Command	Description
Stable	`ctest --test-dir build -L stable`	Core unit tests, always available
GUI	`ctest --test-dir build -L gui`	GUI smoke tests
ROM-dependent	`ctest --test-dir build -L rom_dependent`	Requires a Zelda 3 ROM
Experimental	`ctest --test-dir build -L experimental`	AI/experimental features

Enabling ROM-Dependent Tests

# Configure with ROM path
cmake --preset mac-dev -DYAZE_TEST_ROM_VANILLA_PATH="$PWD/roms/alttp_vanilla.sfc"
 
# Build and run
cmake --build --preset mac-dev --target yaze_test
ctest --test-dir build -L rom_dependent

Test Coverage by Preset

Preset	Stable	GUI	ROM-Dep	Experimental
`*-dbg`	Yes	Yes	No	No
`*-ai`	Yes	Yes	No	Yes
`*-dev`	Yes	Yes	Yes	No
`*-rel`	No	No	No	No

Environment Variables

Variable	Purpose
`YAZE_TEST_ROM_VANILLA`	Path to vanilla ROM for ROM-dependent tests
`YAZE_TEST_ROM_EXPANDED`	Path to expanded (ZSCustom/OOS) ROM
`YAZE_TEST_ROM_PATH`	Legacy ROM path (vanilla fallback)
`YAZE_SKIP_ROM_TESTS`	Skip ROM tests (useful for CI)
`YAZE_ENABLE_UI_TESTS`	Enable GUI tests (auto-detected if display available)

6. Further Reading

Build Troubleshooting - Solutions for common build issues
Platform Compatibility - Platform-specific notes and CI/CD details
CMake Presets Guide - Complete preset reference
Testing Guide - Comprehensive testing documentation

	yaze 0.3.2 Link to the Past ROM Editor