295 lines
8.7 KiB
Markdown
295 lines
8.7 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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:**
|
|
```bash
|
|
./scripts/verify-build-environment.sh --fix
|
|
```
|
|
|
|
**Windows (PowerShell):**
|
|
```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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
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:
|
|
```bash
|
|
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:
|
|
```bash
|
|
export YAZE_BUILD_DIR="$HOME/.cache/yaze/build"
|
|
```
|
|
|
|
For AI-enabled builds, use the `*-ai` presets and specify only the targets you need:
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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:
|
|
```bash
|
|
scripts/install-nightly.sh # re-pulls and installs a new release
|
|
```
|
|
|
|
Removing:
|
|
```bash
|
|
rm -rf ~/.local/yaze/nightly ~/.local/bin/yaze-nightly* ~/.local/bin/z3ed-nightly ~/.local/bin/yaze-mcp-nightly
|
|
```
|
|
|
|
Key overrides:
|
|
```bash
|
|
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:**
|
|
```bash
|
|
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):**
|
|
```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:**
|
|
```bash
|
|
cmake --preset mac-dbg
|
|
cmake --build --preset mac-dbg --target yaze
|
|
```
|
|
|
|
**Linux:**
|
|
```bash
|
|
cmake --preset lin-dbg
|
|
cmake --build --preset lin-dbg --target yaze
|
|
```
|
|
|
|
**Windows:**
|
|
```bash
|
|
cmake --preset win-dbg
|
|
cmake --build --preset win-dbg --target yaze
|
|
```
|
|
|
|
### AI-Enabled Build (with gRPC and z3ed CLI)
|
|
|
|
**macOS:**
|
|
```bash
|
|
cmake --preset mac-ai
|
|
cmake --build --preset mac-ai --target yaze z3ed
|
|
```
|
|
|
|
**Linux:**
|
|
```bash
|
|
cmake --preset lin-ai
|
|
cmake --build --preset lin-ai --target yaze z3ed
|
|
```
|
|
|
|
**Windows:**
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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](troubleshooting.md)** - Solutions for common build issues
|
|
- **[Platform Compatibility](platform-compatibility.md)** - Platform-specific notes and CI/CD details
|
|
- **[CMake Presets Guide](presets.md)** - Complete preset reference
|
|
- **[Testing Guide](../developer/testing-guide.md)** - Comprehensive testing documentation
|