yaze/docs/02-build-instructions.md

Build Instructions

YAZE uses CMake 3.16+ with modern target-based configuration. The project includes comprehensive Windows support with Visual Studio integration, vcpkg package management, and automated setup scripts.

Quick Start

macOS (Apple Silicon)

cmake --preset debug
cmake --build build

Linux

cmake -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build

Windows (Recommended)

# Automated setup (first time only)
.\scripts\setup-windows-dev.ps1

# Generate Visual Studio projects (with proper vcpkg integration)
python scripts/generate-vs-projects.py

# Or use CMake directly
cmake --preset windows-debug
cmake --build build --preset windows-debug

Minimal Build (CI/Fast)

cmake -B build -DYAZE_MINIMAL_BUILD=ON
cmake --build build

Dependencies

Required

• CMake 3.16+
• C++23 compiler (GCC 13+, Clang 16+, MSVC 2019+)
• Git with submodule support

Bundled Libraries

• SDL2, ImGui, Abseil, Asar, GoogleTest
• Native File Dialog Extended (NFD)
• All dependencies included in repository

Platform Setup

macOS

# Install Xcode Command Line Tools
xcode-select --install

# Optional: Install Homebrew dependencies (auto-detected)
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

Automated Setup (Recommended)

The project includes comprehensive setup scripts for Windows development:

# Complete development environment setup
.\scripts\setup-windows-dev.ps1

# Generate Visual Studio project files (with proper vcpkg integration)
python scripts/generate-vs-projects.py

# Test CMake configuration
.\scripts\test-cmake-config.ps1

What the setup script installs:

• Chocolatey package manager
• CMake 3.16+
• Git, Ninja, Python 3
• Visual Studio 2022 detection and verification

Manual Setup Options

Option 1 - Minimal (CI/Fast Builds):

• Visual Studio 2019+ with C++ CMake tools
• No additional dependencies needed (all bundled)

Option 2 - Full Development with vcpkg:

• Visual Studio 2019+ with C++ CMake tools
• vcpkg package manager for dependency management

vcpkg Integration

Automatic Setup:

# PowerShell
.\scripts\setup-windows-dev.ps1

# Command Prompt
scripts\setup-windows-dev.bat

Manual vcpkg Setup:

git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
.\bootstrap-vcpkg.bat
.\vcpkg.exe integrate install
set VCPKG_ROOT=%CD%

Dependencies (vcpkg.json):

• zlib (compression)
• libpng (PNG support)
• sdl2 (graphics/input with Vulkan support)

Note: Abseil and gtest are built from source via CMake rather than through vcpkg to avoid compatibility issues.

Windows Build Commands

Using CMake Presets:

# Debug build (minimal, no tests)
cmake --preset windows-debug
cmake --build build --preset windows-debug

# Development build (includes Google Test)
cmake --preset windows-dev
cmake --build build --preset windows-dev

# Release build (optimized, no tests)
cmake --preset windows-release
cmake --build build --preset windows-release

Using Visual Studio Projects:

# Generate project files (with proper vcpkg integration)
python scripts/generate-vs-projects.py

# Open YAZE.sln in Visual Studio
# Select configuration (Debug/Release) and platform (x64/x86/ARM64)
# Press F5 to build and run

Build Types:

• windows-debug: Minimal debug build, no Google Test
• windows-dev: Development build with Google Test and ROM testing
• windows-release: Optimized release build, no Google Test

Build Targets

Applications

• yaze: Main GUI editor application
• z3ed: Command-line interface tool

Libraries

• yaze_c: C API library for extensions
• asar-static: 65816 assembler library

Development (Debug Builds Only)

• yaze_emu: Standalone SNES emulator
• yaze_test: Comprehensive test suite

Build Configurations

Debug (Full Features)

cmake --preset debug  # macOS
# OR
cmake -B build -DCMAKE_BUILD_TYPE=Debug  # All platforms

Includes: NFD, ImGuiTestEngine, PNG support, emulator, all tools

Minimal (CI/Fast Builds)

cmake -B build -DYAZE_MINIMAL_BUILD=ON

Excludes: Emulator, CLI tools, UI tests, optional dependencies

Release

cmake --preset release  # macOS
# OR  
cmake -B build -DCMAKE_BUILD_TYPE=Release  # All platforms

IDE Integration

Visual Studio (Windows)

Recommended approach:

# Setup development environment
.\scripts\setup-windows-dev.ps1

# Generate Visual Studio project files (with proper vcpkg integration)
python scripts/generate-vs-projects.py

# Open YAZE.sln in Visual Studio 2022
# Select configuration (Debug/Release) and platform (x64/x86/ARM64)
# Press F5 to build and run

Features:

• Full IntelliSense support
• Integrated debugging
• Automatic vcpkg dependency management (zlib, libpng, SDL2)
• Multi-platform support (x64, ARM64)
• Automatic asset copying
• Generated project files stay in sync with CMake configuration

VS Code

1. Install CMake Tools extension
2. Open project, select "Debug" preset
3. Language server uses compile_commands.json automatically

CLion

• Opens CMake projects directly
• Select Debug configuration

Xcode (macOS)

cmake --preset debug -G Xcode
open build/yaze.xcodeproj

Windows Development Scripts

The project includes several PowerShell and Batch scripts to streamline Windows development:

Setup Scripts

• setup-windows-dev.ps1: Complete development environment setup
• setup-windows-dev.bat: Batch version of setup script

What they install:

• Chocolatey package manager
• CMake 3.16+
• Git, Ninja, Python 3
• Visual Studio 2022 detection

Project Generation Scripts

• generate-vs-projects.py: Generate Visual Studio project files with proper vcpkg integration
• generate-vs-projects.bat: Batch version of project generation

Features:

• Automatic CMake detection and installation
• Visual Studio 2022 detection
• Multi-architecture support (x64, ARM64)
• vcpkg integration
• CMake compatibility fixes

Testing Scripts

• test-cmake-config.ps1: Test CMake configuration without full build

Usage:

# Test configuration
.\scripts\test-cmake-config.ps1

# Test with specific architecture
.\scripts\test-cmake-config.ps1 -Architecture x86

# Clean test build
.\scripts\test-cmake-config.ps1 -Clean

Features by Build Type

Feature	Debug	Release	Minimal (CI)
GUI Editor	✅	✅	✅
Native File Dialogs	✅	✅	❌
PNG Support	✅	✅	❌
Emulator	✅	✅	❌
CLI Tools	✅	✅	❌
Test Suite	✅	❌	✅ (limited)
UI Testing	✅	❌	❌

CMake Compatibility

Submodule Compatibility Issues

YAZE includes several submodules (abseil-cpp, SDL) that may have CMake compatibility issues. The project automatically handles these with:

Automatic Policy Management:

• CMAKE_POLICY_VERSION_MINIMUM=3.5 (handles SDL requirements)
• CMAKE_POLICY_VERSION_MAXIMUM=3.28 (prevents future issues)
• CMAKE_WARN_DEPRECATED=OFF (suppresses submodule warnings)
• ABSL_PROPAGATE_CXX_STD=ON (handles Abseil C++ standard propagation)
• THREADS_PREFER_PTHREAD_FLAG=OFF (fixes Windows pthread issues)

Manual Configuration (if needed):

cmake -B build \
  -DCMAKE_POLICY_VERSION_MINIMUM=3.5 \
  -DCMAKE_POLICY_VERSION_MAXIMUM=3.28 \
  -DCMAKE_WARN_DEPRECATED=OFF \
  -DABSL_PROPAGATE_CXX_STD=ON \
  -DTHREADS_PREFER_PTHREAD_FLAG=OFF \
  -DCMAKE_BUILD_TYPE=Debug

CI/CD and Release Builds

GitHub Actions Workflows

The project includes three release workflows with different levels of complexity:

• release-simplified.yml: Fast, basic release builds
• release.yml: Standard release builds with fallback mechanisms
• release-complex.yml: Comprehensive release builds with multiple fallback strategies

vcpkg Fallback Mechanisms

All Windows CI/CD builds include automatic fallback mechanisms:

When vcpkg succeeds:

• Full build with all dependencies (zlib, libpng, SDL2)
• Complete feature set available

When vcpkg fails (network issues):

• Automatic fallback to minimal build configuration
• Uses source-built dependencies (Abseil, etc.)
• Still produces functional executables

Supported Architectures

Windows:

• x64 (64-bit) - Primary target for modern systems
• ARM64 - For ARM-based Windows devices (Surface Pro X, etc.)

macOS:

• Universal binary (Apple Silicon + Intel)

Linux:

• x64 (64-bit)

Troubleshooting

Windows CMake Issues

CMake Not Found:

# Run the setup script
.\scripts\setup-windows-dev.ps1

# Or install manually via Chocolatey
choco install cmake

Submodule Compatibility Errors:

# Test CMake configuration
.\scripts\test-cmake-config.ps1

# Clean build with compatibility flags
Remove-Item -Recurse -Force build
cmake -B build -DCMAKE_POLICY_VERSION_MINIMUM=3.5 -DCMAKE_WARN_DEPRECATED=OFF

Visual Studio Project Issues:

# Regenerate project files
.\scripts\generate-vs-projects.ps1

# Clean and rebuild
Remove-Item -Recurse -Force build
cmake --preset windows-debug

vcpkg Issues

Dependencies Not Installing:

# Check vcpkg installation
vcpkg version

# Reinstall dependencies
vcpkg install --triplet x64-windows zlib libpng sdl2

# Check installed packages
vcpkg list

Network/Download Failures:

• The CI/CD workflows automatically fall back to minimal builds
• For local development, ensure stable internet connection
• If vcpkg consistently fails, use minimal build mode:

  cmake -B build -DYAZE_MINIMAL_BUILD=ON
  

Visual Studio Integration:

# Re-integrate vcpkg
cd C:\vcpkg
.\vcpkg.exe integrate install

ZLIB or Other Dependencies Not Found:

# Regenerate project files with proper vcpkg integration
python scripts/generate-vs-projects.py

# Ensure vcpkg is properly set up
.\scripts\setup-windows-dev.ps1

Architecture Errors (macOS)

# Clean and use ARM64-only preset
rm -rf build
cmake --preset debug  # Uses arm64 only

Missing Headers (Language Server)

# Regenerate compile commands
cmake --preset debug
cp build/compile_commands.json .
# Restart VS Code

CI Build Failures

Use minimal build configuration that matches CI:

cmake -B build -DYAZE_MINIMAL_BUILD=ON -DYAZE_ENABLE_UI_TESTS=OFF
cmake --build build

Common Error Solutions

"CMake Deprecation Warning" from submodules:

• This is automatically handled by the project's CMake configuration
• If you see these warnings, they can be safely ignored

"pthread_create not found" on Windows:

• The project automatically sets THREADS_PREFER_PTHREAD_FLAG=OFF
• This is normal for Windows builds

"Abseil C++ std propagation" warnings:

• Automatically handled with ABSL_PROPAGATE_CXX_STD=ON
• Ensures proper C++ standard handling

Visual Studio "file not found" errors:

• Run python scripts/generate-vs-projects.py to regenerate project files
• Ensure CMake configuration completed successfully first

CI/CD Build Failures:

• Check if vcpkg download failed (network issues)
• The workflows automatically fall back to minimal builds
• For persistent issues, check the workflow logs for specific error messages