yaze uses a modern CMake build system with presets for easy configuration. This guide covers how to build yaze on macOS, Linux, and Windows.
1. Environment Verification
Before your first build, run the verification script to ensure your environment is configured correctly.
Windows (PowerShell)
.\scripts\verify-build-environment.ps1
# With automatic fixes
.\scripts\verify-build-environment.ps1 -FixIssues
macOS & Linux (Bash)
./scripts/verify-build-environment.sh
# With automatic fixes
./scripts\verify-build-environment.sh --fix
The script checks for required tools like CMake, a C++23 compiler, and platform-specific dependencies.
2. Quick Start: Building with Presets
We use CMake Presets for simple, one-command builds. See the CMake Presets Guide for a full list.
macOS
# Configure a debug build (Apple Silicon)
cmake --preset mac-dbg
# Build the project
cmake --build --preset mac-dbg
Linux
# Configure a debug build
cmake --preset lin-dbg
# Build the project
cmake --build --preset lin-dbg
Windows
# Configure a debug build for Visual Studio (x64)
cmake --preset win-dbg
# Build the project
cmake --build --preset win-dbg
AI-Enabled Build (All Platforms)
To build with the z3ed
AI agent features:
# macOS
cmake --preset mac-ai
cmake --build --preset mac-ai
# Windows
cmake --preset win-ai
cmake --build --preset win-ai
3. Dependencies
- Required: CMake 3.16+, C++23 Compiler (GCC 13+, Clang 16+, MSVC 2019+), Git.
- Bundled: All other dependencies (SDL2, ImGui, Abseil, Asar, GoogleTest, etc.) are included as Git submodules or managed by CMake's
FetchContent
. No external package manager is required for a basic build.
- Optional:
- gRPC: For GUI test automation. Can be enabled with
-DYAZE_WITH_GRPC=ON
.
- vcpkg (Windows): Can be used for dependency management, but is not required.
4. Platform Setup
macOS
# Install Xcode Command Line Tools
xcode-select --install
# Recommended: Install build tools via Homebrew
brew install cmake pkg-config
Linux (Ubuntu/Debian)
sudo apt-get update
sudo apt-get install -y build-essential cmake ninja-build pkg-config \
libgtk-3-dev libdbus-1-dev
Windows
- Visual Studio 2022 is required, with the "Desktop development with C++" workload.
- The
verify-build-environment.ps1
script will help identify any missing components.
- For building with gRPC, see the "Windows Build Optimization" section below.
5. Testing
The project uses CTest and GoogleTest. Tests are organized into categories using labels. See the Testing Guide for details.
Running Tests with Presets
The easiest way to run tests is with ctest
presets.
# Configure a development build (enables ROM-dependent tests)
cmake --preset mac-dev -DYAZE_TEST_ROM_PATH=/path/to/your/zelda3.sfc
# Build the tests
cmake --build --preset mac-dev --target yaze_test
# Run stable tests (fast, run in CI)
ctest --preset dev
# Run all tests, including ROM-dependent and experimental
ctest --preset all
Running Tests Manually
You can also run tests by invoking the test executable directly or using CTest with labels.
# Run all tests via the executable
./build/bin/yaze_test
# Run only stable tests using CTest labels
ctest --test-dir build --label-regex "STABLE"
# Run tests matching a name
ctest --test-dir build -R "AsarWrapperTest"
# Exclude ROM-dependent tests
ctest --test-dir build --label-exclude "ROM_DEPENDENT"
6. IDE Integration
VS Code (Recommended)
- Install the CMake Tools extension.
- Open the project folder.
- Select a preset from the status bar (e.g.,
mac-ai
).
- Press F5 to build and debug.
- After changing presets, run
cp build/compile_commands.json .
to update IntelliSense.
Visual Studio (Windows)
- Select File → Open → Folder and choose the
yaze
directory.
- Visual Studio will automatically detect
CMakePresets.json
.
- Select the desired preset (e.g.,
win-dbg
or win-ai
) from the configuration dropdown.
- Press F5 to build and run.
Xcode (macOS)
# Generate an Xcode project from a preset
cmake --preset mac-dbg -G Xcode
# Open the project
open build/yaze.xcodeproj
7. Windows Build Optimization
gRPC v1.67.1 and MSVC Compatibility
Recent Update (October 2025): The project has been upgraded to gRPC v1.67.1 which includes critical MSVC template fixes. This version resolves previous template instantiation errors that occurred with v1.62.0.
MSVC-Specific Compiler Flags: The build system now automatically applies these flags for Windows builds:
/bigobj
- Allows large object files (gRPC generates many symbols)
/permissive-
- Enables standards conformance mode
/wd4267 /wd4244
- Suppresses harmless conversion warnings
/constexpr:depth2048
- Handles deep template instantiations (MSVC 2019+)
The Problem: Slow gRPC Builds
Building with gRPC on Windows (-DYAZE_WITH_GRPC=ON
) can take 15-20 minutes the first time, as it compiles gRPC v1.67.1 and its dependencies from source.
Solution A: Use vcpkg for Pre-compiled Binaries (Recommended - FAST)
Using vcpkg
to manage gRPC is the recommended approach for Windows developers who need GUI automation features.
Step 1: Install vcpkg and Dependencies
# This only needs to be done once
# Use the setup script for convenience:
.\scripts\setup-vcpkg-windows.ps1
# Or manually:
vcpkg install grpc:x64-windows protobuf:x64-windows abseil:x64-windows
Step 2: Configure CMake to Use vcpkg Pass the vcpkg.cmake
toolchain file to your configure command.
# Configure a build that uses vcpkg for gRPC
cmake -B build -G "Visual Studio 17 2022" -A x64 `
-DCMAKE_TOOLCHAIN_FILE="vcpkg/scripts/buildsystems/vcpkg.cmake"
# Build (will now be much faster: 5-10 minutes)
cmake --build build --config RelWithDebInfo --parallel
Build Time: ~5-10 minutes (uses pre-compiled gRPC)
Solution B: FetchContent Build (Slow but Automatic)
If you don't want to use vcpkg, CMake will automatically download and build gRPC from source.
# Configure (will download and build gRPC v1.67.1 from source)
cmake -B build -G "Visual Studio 17 2022" -A x64
# Build (first time: ~45-60 minutes, subsequent: ~2-5 minutes)
cmake --build build --config RelWithDebInfo --parallel
Build Time: ~45-60 minutes first time, ~2-5 minutes subsequent builds (gRPC cached)
8. Troubleshooting
Build issues, especially on Windows, often stem from environment misconfiguration. Before anything else, run the verification script.
# Run the verification script in PowerShell
.\scripts\verify-build-environment.ps1
This script is your primary diagnostic tool and can detect most common problems.
Automatic Fixes
If the script finds issues, you can often fix them automatically by running it with the -FixIssues
flag. This can:
- Synchronize Git submodules.
- Correct Git
core.autocrlf
and core.longpaths
settings, which are critical for cross-platform compatibility on Windows.
- Prompt to clean stale CMake caches.
# Attempt to fix detected issues automatically
.\scripts\verify-build-environment.ps1 -FixIssues
Cleaning Stale Builds
After pulling major changes or switching branches, your build directory can become "stale," leading to strange compiler or linker errors. The verification script will warn you about old build files. You can clean them manually or use the -CleanCache
flag.
This will delete all build*
and out
directories.
# Clean all build artifacts to start fresh
.\scripts\verify-build-environment.ps1 -CleanCache
Common Issues
"nlohmann/json.hpp: No such file or directory"
Cause: You are building code that requires AI features without using an AI-enabled preset, or your Git submodules are not initialized. Solution:
- Use an AI preset like
win-ai
or mac-ai
.
- Ensure submodules are present by running
git submodule update --init --recursive
.
"Cannot open file 'yaze.exe': Permission denied"
Cause: A previous instance of yaze.exe
is still running in the background. Solution: Close it using Task Manager or run:
"C++ standard 'cxx_std_23' not supported"
Cause: Your compiler is too old. Solution: Update your tools. You need Visual Studio 2022 17.4+, GCC 13+, or Clang 16+. The verification script checks this.
Visual Studio Can't Find Presets
Cause: VS failed to parse CMakePresets.json
or its cache is corrupt. Solution:
- Close and reopen the folder (
File -> Close Folder
).
- Check the "CMake" pane in the Output window for specific JSON parsing errors.
- Delete the hidden
.vs
directory in the project root to force Visual Studio to re-index the project.
Git Line Ending (CRLF) Issues
Cause: Git may be automatically converting line endings, which can break shell scripts and other assets. Solution: The verification script checks for this. Use the -FixIssues
flag or run git config --global core.autocrlf false
to prevent this behavior.
File Path Length Limit on Windows
Cause: By default, Windows has a 260-character path limit, which can be exceeded by nested dependencies. Solution: The verification script checks for this. Use the -FixIssues
flag or run git config --global core.longpaths true
to enable long path support.