backend-infra-engineer: Release v0.3.0 snapshot

2025-09-27 00:25:45 -04:00
parent 8ce29e1436
commit e32ac75b9c
346 changed files with 55946 additions and 11764 deletions
--- a/docs/02-build-instructions.md
+++ b/docs/02-build-instructions.md
@@ -0,0 +1,153 @@
+# Build Instructions
+
+YAZE uses CMake 3.16+ with modern target-based configuration. For VSCode users, install the CMake extensions:
+- https://marketplace.visualstudio.com/items?itemName=twxs.cmake
+- https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools
+
+## Quick Start
+
+### macOS (Apple Silicon)
+```bash
+cmake --preset debug
+cmake --build build
+```
+
+### Linux / Windows
+```bash
+cmake -B build -DCMAKE_BUILD_TYPE=Debug
+cmake --build build
+```
+
+### Minimal Build
+```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
+**Option 1 - Minimal (Recommended for CI):**
+- Visual Studio 2019+ with C++ CMake tools
+- No additional dependencies needed (all bundled)
+
+**Option 2 - Full Development:**
+- Install vcpkg and dependencies from `vcpkg.json`
+
+## 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
+
+### 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
+```
+
+## Features by Build Type
+
+| Feature | Debug | Release | Minimal (CI) |
+|---------|-------|---------|--------------|
+| GUI Editor | ✅ | ✅ | ✅ |
+| Native File Dialogs | ✅ | ✅ | ❌ |
+| PNG Support | ✅ | ✅ | ❌ |
+| Emulator | ✅ | ✅ | ❌ |
+| CLI Tools | ✅ | ✅ | ❌ |
+| Test Suite | ✅ | ❌ | ✅ (limited) |
+| UI Testing | ✅ | ❌ | ❌ |
+
+## Troubleshooting
+
+### 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
+```