scawful/yaze
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
607f6aa1e8954349c443cad3d67cc0d13a476249
yaze/docs/public/build/quick-reference.md
scawful 8d011bf094 imgui-frontend-engineer: update docs and plans
2025-12-28 10:51:31 -06:00

8.7 KiB
Raw Blame History

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

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.

3. Build Directory Policy

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

macOS and Windows presets use multi-config generators, so binaries live under build/bin/Debug or build/bin/Release. Linux uses single-config builds in build/bin.

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 in the repo 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 Nightly Install (Isolated)

Use scripts/install-nightly.sh to keep a separate clone and install prefix for nightly builds so your dev build/ stays untouched.

scripts/install-nightly.sh

Wrappers are created under ~/.local/bin:

  • yaze-nightly (GUI)
  • yaze-nightly-grpc (GUI + gRPC for MCP)
  • z3ed-nightly (CLI)
  • yaze-mcp-nightly (MCP server; expects ~/Code/yaze-mcp/venv)

How it works:

  • Clones origin into $YAZE_NIGHTLY_REPO (default ~/Code/yaze-nightly) and keeps it clean.
  • Builds into $YAZE_NIGHTLY_BUILD_DIR (default ~/Code/yaze-nightly/build-nightly).
  • Installs into $YAZE_NIGHTLY_PREFIX/releases/<timestamp> and updates .../current symlink.
  • Writes wrapper scripts to $YAZE_NIGHTLY_BIN_DIR (default ~/.local/bin).

Updating:

scripts/install-nightly.sh  # re-pulls and installs a new release

Removing:

rm -rf ~/.local/yaze/nightly ~/.local/bin/yaze-nightly* ~/.local/bin/z3ed-nightly ~/.local/bin/yaze-mcp-nightly

Key overrides:

export YAZE_NIGHTLY_REPO="$HOME/Code/yaze-nightly"
export YAZE_NIGHTLY_PREFIX="$HOME/.local/yaze/nightly"
export YAZE_NIGHTLY_BUILD_TYPE=RelWithDebInfo
export YAZE_GRPC_PORT=50051
export YAZE_MCP_REPO="$HOME/Code/yaze-mcp"

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

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_stable --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

Reference in New Issue View Git Blame Copy Permalink