4.9 KiB
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