yaze/docs/public/build/quick-reference.md

Build and Test Quick Reference

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.

---

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

---

2. Build Presets

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

Available Presets

Preset	Platform	Description
mac-dbg, lin-dbg, win-dbg	macOS / Linux / Windows	Standard debug builds with tests enabled
mac-ai, lin-ai, win-ai	macOS / Linux / Windows	Full AI stack: gRPC, agent UI, z3ed CLI, AI runtime
mac-rel, lin-rel, win-rel	macOS / Linux / Windows	Optimized release builds
mac-dev, lin-dev, win-dev	macOS / Linux / Windows	Development builds with ROM-dependent tests
mac-uni	macOS	Universal binary (ARM64 + x86_64) for distribution
mac-test, lin-test, win-test	All	Optimized builds for fast test iteration
ci-*	Platform-specific	CI/CD configurations (see CMakePresets.json)

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

---

3. Build Directory Policy

Build Type	Default Directory
Native (desktop/CLI)	build/
WASM	build-wasm/

If you need per-user or per-agent isolation, create a local CMakeUserPresets.json that points binaryDir to a custom path.

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

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

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

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

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"

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_PATH=/path/to/zelda3.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_PATH	Path to ROM for ROM-dependent tests
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