# 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)
```bash
cmake --preset debug
cmake --build build
```

### Linux
```bash
cmake -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build
```

### Windows (Recommended)
```powershell
# 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)
```bash
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
```bash
# Install Xcode Command Line Tools
xcode-select --install

# Optional: Install Homebrew dependencies (auto-detected)
brew install cmake pkg-config
```

### Linux (Ubuntu/Debian)
```bash
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:

```powershell
# 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
# PowerShell
.\scripts\setup-windows-dev.ps1

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

**Manual vcpkg Setup:**
```cmd
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:**
```cmd
# 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:**
```powershell
# 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)
```bash
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)
```bash
cmake -B build -DYAZE_MINIMAL_BUILD=ON
```
**Excludes**: Emulator, CLI tools, UI tests, optional dependencies

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

## IDE Integration

### Visual Studio (Windows)
**Recommended approach:**
```powershell
# 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)
```bash
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:**
```powershell
# 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):**
```bash
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:**
```powershell
# Run the setup script
.\scripts\setup-windows-dev.ps1

# Or install manually via Chocolatey
choco install cmake
```

**Submodule Compatibility Errors:**
```powershell
# 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:**
```powershell
# 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:**
```cmd
# 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:
  ```bash
  cmake -B build -DYAZE_MINIMAL_BUILD=ON
  ```

**Visual Studio Integration:**
```cmd
# Re-integrate vcpkg
cd C:\vcpkg
.\vcpkg.exe integrate install
```

**ZLIB or Other Dependencies Not Found:**
```bash
# 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)
```bash
# Clean and use ARM64-only preset
rm -rf build
cmake --preset debug  # Uses arm64 only
```

### Missing Headers (Language Server)
```bash
# Regenerate compile commands
cmake --preset debug
cp build/compile_commands.json .
# Restart VS Code
```

### CI Build Failures
Use minimal build configuration that matches CI:
```bash
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