chore: add comprehensive build documentation and troubleshooting guides

- Created a new README.md for GitHub Actions composite actions, detailing available actions, inputs, and usage instructions for the YAZE CI/CD pipeline. - Added a BUILD-GUIDE.md to provide a detailed overview of the build process across macOS, Linux, and Windows, including quick start commands and build system configurations. - Introduced a BUILD-TROUBLESHOOTING.md to address common build issues, platform-specific problems, and provide solutions, enhancing the developer experience and support. Benefits: - Improves onboarding and usability for developers by providing clear and structured documentation. - Facilitates easier troubleshooting and understanding of the build process across different platforms.
2025-11-01 10:49:00 -04:00
parent c4cf5e918f
commit 746ade46ee
3 changed files with 820 additions and 0 deletions
--- a/.github/actions/README.md
+++ b/.github/actions/README.md
@@ -0,0 +1,84 @@
+# GitHub Actions - Composite Actions
+
+This directory contains reusable composite actions for the YAZE CI/CD pipeline.
+
+## Available Actions
+
+### 1. `setup-build`
+Sets up the build environment with dependencies and caching.
+
+**Inputs:**
+- `platform` (required): Target platform (linux, macos, windows)
+- `preset` (required): CMake preset to use
+- `cache-key` (optional): Cache key for dependencies
+
+**What it does:**
+- Configures CPM cache
+- Installs platform-specific build dependencies
+- Sets up sccache/ccache for faster builds
+
+### 2. `build-project`
+Builds the project with CMake and caching.
+
+**Inputs:**
+- `platform` (required): Target platform (linux, macos, windows)
+- `preset` (required): CMake preset to use
+- `build-type` (optional): Build type (Debug, Release, RelWithDebInfo)
+
+**What it does:**
+- Caches build artifacts
+- Configures the project with CMake
+- Builds the project with optimal parallel settings
+- Shows build artifacts for verification
+
+### 3. `run-tests`
+Runs the test suite with appropriate filtering.
+
+**Inputs:**
+- `test-type` (required): Type of tests to run (stable, unit, integration, all)
+- `preset` (optional): CMake preset to use (default: ci)
+
+**What it does:**
+- Runs the specified test suite(s)
+- Generates JUnit XML test results
+- Uploads test results as artifacts
+
+## Usage
+
+These composite actions are used in the main CI workflow (`.github/workflows/ci.yml`). They must be called after checking out the repository:
+
+```yaml
+steps:
+  - name: Checkout code
+    uses: actions/checkout@v4
+    with:
+      submodules: recursive
+
+  - name: Setup build environment
+    uses: ./.github/actions/setup-build
+    with:
+      platform: linux
+      preset: ci
+      cache-key: ${{ hashFiles('cmake/dependencies.lock') }}
+```
+
+## Important Notes
+
+1. **Repository checkout required**: The repository must be checked out before calling any of these composite actions. They do not include a checkout step themselves.
+
+2. **Platform-specific behavior**: Each action adapts to the target platform (Linux, macOS, Windows) and runs appropriate commands for that environment.
+
+3. **Caching**: The actions use GitHub Actions caching to speed up builds by caching:
+   - CPM dependencies (~/.cpm-cache)
+   - Build artifacts (build/)
+   - Compiler cache (sccache/ccache)
+
+4. **Dependencies**: The Linux CI packages are listed in `.github/workflows/scripts/linux-ci-packages.txt`.
+
+## Maintenance
+
+When updating these actions:
+- Test on all three platforms (Linux, macOS, Windows)
+- Ensure shell compatibility (bash for Linux/macOS, pwsh for Windows)
+- Update this README if inputs or behavior changes
+
--- a/docs/BUILD-GUIDE.md
+++ b/docs/BUILD-GUIDE.md
@@ -0,0 +1,264 @@
+# YAZE Build Guide
+
+**Status**: CI/CD Overhaul Complete ✅
+**Last Updated**: October 2025
+**Platforms**: macOS (ARM64/Intel), Linux, Windows
+
+## Quick Start
+
+### macOS (Apple Silicon)
+```bash
+# Basic debug build
+cmake --preset mac-dbg && cmake --build --preset mac-dbg
+
+# With AI features (z3ed agent, gRPC, JSON)
+cmake --preset mac-ai && cmake --build --preset mac-ai
+
+# Release build
+cmake --preset mac-rel && cmake --build --preset mac-rel
+```
+
+### Linux
+```bash
+# Debug build
+cmake --preset lin-dbg && cmake --build --preset lin-dbg
+
+# With AI features
+cmake --preset lin-ai && cmake --build --preset lin-ai
+```
+
+### Windows (Visual Studio)
+```bash
+# Debug build
+cmake --preset win-dbg && cmake --build --preset win-dbg
+
+# With AI features
+cmake --preset win-ai && cmake --build --preset win-ai
+```
+
+## Build System Overview
+
+### CMake Presets
+The project uses a streamlined preset system with short, memorable names:
+
+| Preset | Platform | Features | Build Dir |
+|--------|----------|----------|-----------|
+| `mac-dbg`, `lin-dbg`, `win-dbg` | All | Basic debug builds | `build/` |
+| `mac-ai`, `lin-ai`, `win-ai` | All | AI features (z3ed, gRPC, JSON) | `build_ai/` |
+| `mac-rel`, `lin-rel`, `win-rel` | All | Release builds | `build/` |
+| `mac-dev`, `win-dev` | Desktop | Development with ROM tests | `build/` |
+| `mac-uni` | macOS | Universal binary (ARM64+x86_64) | `build/` |
+
+Add `-v` suffix (e.g., `mac-dbg-v`) for verbose compiler warnings.
+
+### Build Configuration
+- **C++ Standard**: C++23 (required)
+- **Generator**: Ninja Multi-Config (all platforms)
+- **Dependencies**: Bundled via Git submodules or CMake FetchContent
+- **Optional Features**:
+  - gRPC: Enable with `-DYAZE_WITH_GRPC=ON` (for GUI automation)
+  - AI Agent: Enable with `-DZ3ED_AI=ON` (requires JSON and gRPC)
+  - ROM Tests: Enable with `-DYAZE_ENABLE_ROM_TESTS=ON -DYAZE_TEST_ROM_PATH=/path/to/zelda3.sfc`
+
+## CI/CD Build Fixes (October 2025)
+
+### Issues Resolved
+
+#### 1. CMake Integration ✅
+**Problem**: Generator mismatch between `CMakePresets.json` and VSCode settings
+
+**Fixes**:
+- Updated `.vscode/settings.json` to use Ninja Multi-Config
+- Fixed compile_commands.json path to `build/compile_commands.json`
+- Created proper `.vscode/tasks.json` with preset-based tasks
+- Updated `scripts/dev-setup.sh` for future setups
+
+#### 2. gRPC Dependency ✅
+**Problem**: CPM downloading but not building gRPC targets
+
+**Fixes**:
+- Fixed target aliasing for non-namespaced targets (grpc++ → grpc::grpc++)
+- Exported `ABSL_TARGETS` for project-wide use
+- Added `target_add_protobuf()` function for protobuf code generation
+- Fixed protobuf generation paths and working directory
+
+#### 3. Protobuf Code Generation ✅
+**Problem**: `.pb.h` and `.grpc.pb.h` files weren't being generated
+
+**Fixes**:
+- Changed all `YAZE_WITH_GRPC` → `YAZE_ENABLE_GRPC` (compile definition vs CMake variable)
+- Fixed variable scoping using `CACHE INTERNAL` for functions
+- Set up proper include paths for generated files
+- All proto files now generate successfully:
+  - `rom_service.proto`
+  - `canvas_automation.proto`
+  - `imgui_test_harness.proto`
+  - `emulator_service.proto`
+
+#### 4. SDL2 Configuration ✅
+**Problem**: SDL.h headers not found
+
+**Fixes**:
+- Changed all `SDL_TARGETS` → `YAZE_SDL2_TARGETS`
+- Fixed variable export using `PARENT_SCOPE`
+- Added Homebrew SDL2 include path (`/opt/homebrew/opt/sdl2/include/SDL2`)
+- Fixed all library targets to link SDL2 properly
+
+#### 5. ImGui Configuration ✅
+**Problem**: Conflicting ImGui versions (bundled vs CPM download)
+
+**Fixes**:
+- Used bundled ImGui from `src/lib/imgui/` instead of downloading
+- Created proper ImGui static library target
+- Added `imgui_stdlib.cpp` for std::string support
+- Exported with `PARENT_SCOPE`
+
+#### 6. nlohmann_json Configuration ✅
+**Problem**: JSON headers not found
+
+**Fixes**:
+- Created `cmake/dependencies/json.cmake`
+- Set up bundled `third_party/json/`
+- Added include directories to all targets that need JSON
+
+#### 7. GTest and GMock ✅
+**Problem**: GMock was disabled but test targets required it
+
+**Fixes**:
+- Changed `BUILD_GMOCK OFF` → `BUILD_GMOCK ON` in testing.cmake
+- Added verification for both gtest and gmock targets
+- Linked all four testing libraries: gtest, gtest_main, gmock, gmock_main
+- Built ImGuiTestEngine from bundled source for GUI test automation
+
+### Build Statistics
+
+**Main Application**:
+- Compilation Units: 310 targets
+- Executable: `build/bin/Debug/yaze.app/Contents/MacOS/yaze` (macOS)
+- Size: 120MB (ARM64 Mach-O)
+- Status: ✅ Successfully built
+
+**Test Suites**:
+- `yaze_test_stable`: 126MB - Unit + Integration tests for CI/CD
+- `yaze_test_gui`: 123MB - GUI automation tests
+- `yaze_test_experimental`: 121MB - Experimental features
+- `yaze_test_benchmark`: 121MB - Performance benchmarks
+- Status: ✅ All test executables built successfully
+
+## Test Execution
+
+### Build Tests
+```bash
+# Build tests
+cmake --build build --target yaze_test
+
+# Run all tests
+./build/bin/yaze_test
+
+# Run specific categories
+./build/bin/yaze_test --unit              # Unit tests only
+./build/bin/yaze_test --integration       # Integration tests
+./build/bin/yaze_test --e2e --show-gui    # End-to-end GUI tests
+
+# Run with ROM-dependent tests
+./build/bin/yaze_test --rom-dependent --rom-path zelda3.sfc
+
+# Run specific test by name
+./build/bin/yaze_test "*Asar*"
+```
+
+### Using CTest
+```bash
+# Run all stable tests
+ctest --preset stable --output-on-failure
+
+# Run all tests
+ctest --preset all --output-on-failure
+
+# Run unit tests only
+ctest --preset unit
+
+# Run integration tests only
+ctest --preset integration
+```
+
+## Platform-Specific Notes
+
+### macOS
+- Supports both Apple Silicon (ARM64) and Intel (x86_64)
+- Use `mac-uni` preset for universal binaries
+- Bundled Abseil used by default to avoid deployment target mismatches
+- Requires Xcode Command Line Tools
+
+**ARM64 Considerations**:
+- gRPC v1.67.1 is the tested stable version
+- Abseil SSE flags are handled automatically
+- See docs/BUILD-TROUBLESHOOTING.md for gRPC ARM64 issues
+
+### Windows
+- Requires Visual Studio 2022 with "Desktop development with C++" workload
+- Run `scripts\verify-build-environment.ps1` before building
+- gRPC builds take 15-20 minutes first time (use vcpkg for faster builds)
+- Watch for path length limits: Enable long paths with `git config --global core.longpaths true`
+
+**vcpkg Integration**:
+- Optional: Use `-DYAZE_USE_VCPKG_GRPC=ON` for pre-built packages
+- Faster builds (~5-10 min vs 30-40 min)
+- See docs/BUILD-TROUBLESHOOTING.md for vcpkg setup
+
+### Linux
+- Requires GCC 13+ or Clang 16+
+- Install dependencies: `libgtk-3-dev`, `libdbus-1-dev`, `pkg-config`
+- See `.github/workflows/ci.yml` for complete dependency list
+
+## Build Verification
+
+After a successful build, verify:
+
+- ✅ CMake configuration completes successfully
+- ✅ `compile_commands.json` generated (62,066 lines, 10,344 source files indexed)
+- ✅ Main executable links successfully
+- ✅ All test executables build successfully
+- ✅ IntelliSense working with full codebase indexing
+
+## Troubleshooting
+
+For platform-specific issues, dependency problems, and error resolution, see:
+- **docs/BUILD-TROUBLESHOOTING.md** - Comprehensive troubleshooting guide
+- **docs/ci-cd/LOCAL-CI-TESTING.md** - Local testing strategies
+
+## Files Modified (CI/CD Overhaul)
+
+### Core Build System (9 files)
+1. `cmake/dependencies/grpc.cmake` - gRPC setup, protobuf generation
+2. `cmake/dependencies/sdl2.cmake` - SDL2 configuration
+3. `cmake/dependencies/imgui.cmake` - ImGui + ImGuiTestEngine
+4. `cmake/dependencies/json.cmake` - nlohmann_json setup
+5. `cmake/dependencies/testing.cmake` - GTest + GMock
+6. `cmake/dependencies.cmake` - Dependency coordination
+7. `src/yaze_pch.h` - Removed Abseil includes
+8. `CMakeLists.txt` - Top-level configuration
+9. `CMakePresets.json` - Preset definitions
+
+### VSCode/CMake Integration (4 files)
+10. `.vscode/settings.json` - CMake integration
+11. `.vscode/c_cpp_properties.json` - Compile commands path
+12. `.vscode/tasks.json` - Build tasks
+13. `scripts/dev-setup.sh` - VSCode config generation
+
+### Library Configuration (6 files)
+14. `src/app/gfx/gfx_library.cmake` - SDL2 variable names
+15. `src/app/net/net_library.cmake` - JSON includes
+16. `src/app/app.cmake` - SDL2 targets for macOS
+17. `src/app/gui/gui_library.cmake` - SDL2 targets
+18. `src/app/emu/emu_library.cmake` - SDL2 targets
+19. `src/app/service/grpc_support.cmake` - SDL2 targets
+
+**Total: 26 files modified/created**
+
+## See Also
+
+- **CLAUDE.md** - Project overview and development guidelines
+- **docs/BUILD-TROUBLESHOOTING.md** - Platform-specific troubleshooting
+- **docs/ci-cd/CI-SETUP.md** - CI/CD pipeline configuration
+- **docs/testing/TEST-GUIDE.md** - Testing strategies and execution
--- a/docs/BUILD-TROUBLESHOOTING.md
+++ b/docs/BUILD-TROUBLESHOOTING.md
@@ -0,0 +1,472 @@
+# YAZE Build Troubleshooting Guide
+
+**Last Updated**: October 2025
+**Related Docs**: BUILD-GUIDE.md, ci-cd/CI-SETUP.md
+
+## Table of Contents
+- [gRPC ARM64 Issues](#grpc-arm64-issues)
+- [Windows Build Issues](#windows-build-issues)
+- [macOS Issues](#macos-issues)
+- [Linux Issues](#linux-issues)
+- [Common Build Errors](#common-build-errors)
+
+---
+
+## gRPC ARM64 Issues
+
+### Status: Known Issue with Workarounds
+
+The ARM64 macOS build has persistent issues with Abseil's random number generation targets when building gRPC from source. This issue has been ongoing through multiple attempts to fix.
+
+### The Problem
+
+**Error**:
+```
+clang++: error: unsupported option '-msse4.1' for target 'arm64-apple-darwin25.0.0'
+```
+
+**Target**: `absl_random_internal_randen_hwaes_impl`
+
+**Root Cause**: Abseil's random number generation targets are being built with x86-specific compiler flags (`-msse4.1`, `-maes`, `-msse4.2`) on ARM64 macOS.
+
+### Working Configuration
+
+**gRPC Version**: v1.67.1 (tested and stable)
+**Protobuf Version**: 3.28.1 (bundled with gRPC)
+**Abseil Version**: 20240116.0 (bundled with gRPC)
+
+### Solution Approaches Tried
+
+#### ❌ Failed Attempts
+1. **CMake flag configuration** - Abseil variables being overridden by gRPC
+2. **Global CMAKE_CXX_FLAGS** - Flags set at target level, not global
+3. **Pre-configuration Abseil settings** - gRPC overrides them
+4. **Different gRPC versions** - v1.62.0, v1.68.0, v1.60.0, v1.58.0 all have issues
+
+#### ✅ Working Approach: Target Property Manipulation
+
+The working solution involves manipulating target properties after gRPC is configured:
+
+```cmake
+# In cmake/grpc.cmake (from working commit 6db7ba4782)
+if(APPLE AND CMAKE_OSX_ARCHITECTURES STREQUAL "arm64")
+  # List of Abseil targets with x86-specific flags
+  set(_absl_targets_with_x86_flags
+    absl_random_internal_randen_hwaes_impl
+    absl_random_internal_randen_hwaes
+    absl_crc_internal_cpu_detect
+  )
+
+  foreach(_absl_target IN LISTS _absl_targets_with_x86_flags)
+    if(TARGET ${_absl_target})
+      get_target_property(_absl_opts ${_absl_target} COMPILE_OPTIONS)
+      if(_absl_opts)
+        # Remove SSE flags: -maes, -msse4.1, -msse2, -Xarch_x86_64
+        list(FILTER _absl_opts EXCLUDE REGEX "^-m(aes|sse)")
+        list(FILTER _absl_opts EXCLUDE REGEX "^-Xarch_x86_64")
+        set_property(TARGET ${_absl_target} PROPERTY COMPILE_OPTIONS ${_absl_opts})
+      endif()
+    endif()
+  endforeach()
+endif()
+```
+
+### Current Workaround
+
+**Option 1**: Use the bundled Abseil with target property manipulation (as above)
+
+**Option 2**: Disable gRPC for ARM64 development
+```cmake
+if(APPLE AND CMAKE_OSX_ARCHITECTURES STREQUAL "arm64")
+  set(YAZE_WITH_GRPC OFF CACHE BOOL "" FORCE)
+  message(STATUS "ARM64: Disabling gRPC due to build issues")
+endif()
+```
+
+**Option 3**: Use pre-built vcpkg packages (Windows-style approach for macOS)
+```bash
+brew install grpc protobuf abseil
+# Then use find_package instead of FetchContent
+```
+
+### Environment Configuration
+
+**Homebrew LLVM Configuration**:
+- **Toolchain**: `cmake/llvm-brew.toolchain.cmake`
+- **SDK**: `/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk`
+- **C++ Standard Library**: Homebrew's libc++ (not system libstdc++)
+
+### Build Commands for Testing
+
+```bash
+# Clean build
+rm -rf build/_deps/grpc-build
+
+# Test configuration
+cmake --preset mac-dbg
+
+# Test build
+cmake --build --preset mac-dbg --target protoc
+```
+
+### Success Criteria
+
+The build succeeds when:
+```bash
+cmake --build --preset mac-dbg --target protoc
+# Returns exit code 0 (no SSE flag errors)
+```
+
+### Files to Monitor
+
+**Critical Files**:
+- `cmake/grpc.cmake` - Main gRPC configuration
+- `build/_deps/grpc-build/third_party/abseil-cpp/` - Abseil build output
+- `build/_deps/grpc-build/third_party/abseil-cpp/absl/random/CMakeFiles/` - Random target build files
+
+**Log Files**:
+- CMake configuration output (look for Abseil configuration messages)
+- Build output (look for compiler flag errors)
+- `build/_deps/grpc-build/CMakeCache.txt` - Check if ARM64 flags are set
+
+### Additional Resources
+
+- **gRPC ARM64 Issues**: https://github.com/grpc/grpc/issues (search for ARM64, macOS, Abseil)
+- **Abseil Random Documentation**: https://abseil.io/docs/cpp/guides/random
+- **CMake FetchContent**: https://cmake.org/cmake/help/latest/module/FetchContent.html
+
+---
+
+## Windows Build Issues
+
+### MSVC Compatibility with gRPC
+
+**Problem**: gRPC v1.75.1 has MSVC compilation errors in UPB (micro protobuf) code
+
+**Error**:
+```
+error C2099: initializer is not a constant
+```
+
+**Solution**: Use gRPC v1.67.1 (MSVC-compatible, tested) or use vcpkg pre-built packages
+
+### vcpkg Integration (Recommended)
+
+#### Setup vcpkg
+
+```powershell
+# Install vcpkg if not already installed
+git clone https://github.com/microsoft/vcpkg.git
+cd vcpkg
+.\bootstrap-vcpkg.bat
+
+# Install packages
+.\vcpkg install grpc:x64-windows protobuf:x64-windows sdl2:x64-windows yaml-cpp:x64-windows
+```
+
+#### Configure CMake to Use vcpkg
+
+**Option 1**: Set environment variable
+```powershell
+$env:CMAKE_TOOLCHAIN_FILE = "C:\path\to\vcpkg\scripts\buildsystems\vcpkg.cmake"
+cmake --preset win-dbg
+```
+
+**Option 2**: Use CMake preset with toolchain
+```json
+// CMakePresets.json (already configured)
+{
+  "name": "win-dbg",
+  "cacheVariables": {
+    "CMAKE_TOOLCHAIN_FILE": "$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake"
+  }
+}
+```
+
+#### Expected Build Times
+
+| Method | Time | Version | Status |
+|--------|------|---------|--------|
+| **vcpkg** (recommended) | ~5-10 min | gRPC 1.71.0 | ✅ Pre-compiled binaries |
+| **FetchContent** (fallback) | ~30-40 min | gRPC 1.67.1 | ✅ MSVC-compatible |
+| **FetchContent** (old) | ~45+ min | gRPC 1.75.1 | ❌ UPB compilation errors |
+
+### Long Path Issues
+
+Windows has a default path length limit of 260 characters, which can cause issues with deep dependency trees.
+
+**Solution**:
+```powershell
+# Enable long paths for Git
+git config --global core.longpaths true
+
+# Enable long paths system-wide (requires admin)
+New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" `
+  -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force
+```
+
+### Missing Visual Studio Components
+
+**Error**: "Could not find Visual C++ compiler"
+
+**Solution**: Install "Desktop development with C++" workload via Visual Studio Installer
+
+```powershell
+# Verify Visual Studio installation
+.\scripts\verify-build-environment.ps1
+```
+
+### Package Detection Issues
+
+**Problem**: `find_package(gRPC CONFIG)` not finding vcpkg-installed packages
+
+**Causes**:
+1. Case sensitivity: vcpkg uses lowercase `grpc` config
+2. Namespace mismatch: vcpkg provides `gRPC::grpc++` target
+3. Missing packages in `vcpkg.json`
+
+**Solution**: Enhanced detection in `cmake/grpc_windows.cmake`:
+
+```cmake
+# Try both case variations
+find_package(gRPC CONFIG QUIET)
+if(NOT gRPC_FOUND)
+  find_package(grpc CONFIG QUIET)  # Try lowercase
+  if(grpc_FOUND)
+    set(gRPC_FOUND TRUE)
+  endif()
+endif()
+
+# Create aliases for non-namespaced targets
+if(TARGET gRPC::grpc++)
+  add_library(grpc++ ALIAS gRPC::grpc++)
+  add_library(grpc++_reflection ALIAS gRPC::grpc++_reflection)
+endif()
+```
+
+---
+
+## macOS Issues
+
+### Homebrew SDL2 Not Found
+
+**Problem**: SDL.h headers not found even with Homebrew SDL2 installed
+
+**Solution**: Add Homebrew include path explicitly
+
+```cmake
+# In cmake/dependencies/sdl2.cmake
+if(APPLE)
+  include_directories(/opt/homebrew/opt/sdl2/include/SDL2)  # Apple Silicon
+  include_directories(/usr/local/opt/sdl2/include/SDL2)    # Intel
+endif()
+```
+
+### Code Signing Issues
+
+**Problem**: "yaze.app is damaged and can't be opened"
+
+**Solution**: Sign the application bundle
+```bash
+codesign --force --deep --sign - build/bin/yaze.app
+```
+
+### Multiple Xcode Versions
+
+**Problem**: CMake using wrong SDK or compiler version
+
+**Solution**: Select Xcode version explicitly
+```bash
+sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
+```
+
+---
+
+## Linux Issues
+
+### Missing Dependencies
+
+**Error**: Headers not found for various libraries
+
+**Solution**: Install development packages
+
+**Ubuntu/Debian**:
+```bash
+sudo apt-get update
+sudo apt-get install -y \
+  build-essential cmake ninja-build pkg-config \
+  libglew-dev libxext-dev libwavpack-dev libboost-all-dev \
+  libpng-dev python3-dev \
+  libasound2-dev libpulse-dev \
+  libx11-dev libxrandr-dev libxcursor-dev libxinerama-dev libxi-dev \
+  libxss-dev libxxf86vm-dev libxkbcommon-dev libwayland-dev libdecor-0-dev \
+  libgtk-3-dev libdbus-1-dev git
+```
+
+**Fedora/RHEL**:
+```bash
+sudo dnf install -y \
+  gcc-c++ cmake ninja-build pkg-config \
+  glew-devel libXext-devel wavpack-devel boost-devel \
+  libpng-devel python3-devel \
+  alsa-lib-devel pulseaudio-libs-devel \
+  libX11-devel libXrandr-devel libXcursor-devel libXinerama-devel libXi-devel \
+  libXScrnSaver-devel libXxf86vm-devel libxkbcommon-devel wayland-devel \
+  gtk3-devel dbus-devel git
+```
+
+### GCC Version Too Old
+
+**Error**: C++23 features not supported
+
+**Solution**: Install newer GCC or use Clang
+
+```bash
+# Install GCC 13
+sudo apt-get install -y gcc-13 g++-13
+
+# Configure CMake to use GCC 13
+cmake --preset lin-dbg \
+  -DCMAKE_C_COMPILER=gcc-13 \
+  -DCMAKE_CXX_COMPILER=g++-13
+```
+
+---
+
+## Common Build Errors
+
+### "Target not found" Errors
+
+**Error**: `CMake Error: Cannot specify link libraries for target "X" which is not built by this project`
+
+**Causes**:
+1. Target aliasing issues
+2. Dependency order problems
+3. Missing `find_package()` calls
+
+**Solutions**:
+1. Check `cmake/dependencies.cmake` for proper target exports
+2. Ensure dependencies are included before they're used
+3. Verify target names match (e.g., `grpc++` vs `gRPC::grpc++`)
+
+### Protobuf Version Mismatch
+
+**Error**: "Protobuf C++ gencode is built with an incompatible version"
+
+**Cause**: System protoc version doesn't match bundled protobuf runtime
+
+**Solution**: Use bundled protoc
+```cmake
+set(_gRPC_PROTOBUF_PROTOC_EXECUTABLE $<TARGET_FILE:protoc>)
+```
+
+### compile_commands.json Not Generated
+
+**Problem**: IntelliSense/clangd not working
+
+**Solution**: Ensure preset uses Ninja Multi-Config generator
+```bash
+cmake --preset mac-dbg  # Uses Ninja Multi-Config
+# compile_commands.json will be at build/compile_commands.json
+```
+
+### ImGui ID Collisions
+
+**Error**: "Dear ImGui: Duplicate ID"
+
+**Solution**: Add `PushID/PopID` scopes around widgets
+```cpp
+ImGui::PushID("unique_identifier");
+// ... widgets here ...
+ImGui::PopID();
+```
+
+### ASAR Library Build Errors
+
+**Status**: Known issue with stubbed implementation
+
+**Current State**: ASAR methods return `UnimplementedError`
+
+**Workaround**: Assembly patching features are disabled until ASAR CMakeLists.txt macro errors are fixed
+
+---
+
+## Debugging Tips
+
+### Enable Verbose Build Output
+
+```bash
+# Verbose CMake configuration
+cmake --preset mac-dbg -- -LAH
+
+# Verbose build
+cmake --build --preset mac-dbg --verbose
+
+# Very verbose build
+cmake --build --preset mac-dbg -- -v VERBOSE=1
+```
+
+### Check Dependency Detection
+
+```bash
+# See what CMake found
+cmake --preset mac-dbg 2>&1 | grep -E "(Found|Using|Detecting)"
+
+# Check cache for specific variables
+cmake -LA build/ | grep -i grpc
+```
+
+### Isolate Build Issues
+
+```bash
+# Build specific targets to isolate issues
+cmake --build build --target yaze_canvas   # Just canvas library
+cmake --build build --target yaze_gfx      # Just graphics library
+cmake --build build --target protoc        # Just protobuf compiler
+```
+
+### Clean Builds
+
+```bash
+# Clean build directory (fast)
+cmake --build build --target clean
+
+# Remove build artifacts but keep dependencies (medium)
+rm -rf build/bin build/lib
+
+# Nuclear option - full rebuild (slow, 30+ minutes)
+rm -rf build/
+cmake --preset mac-dbg
+```
+
+---
+
+## Getting Help
+
+1. **Check existing documentation**:
+   - BUILD-GUIDE.md - General build instructions
+   - CLAUDE.md - Project overview
+   - CI/CD logs - .github/workflows/ci.yml
+
+2. **Search git history** for working configurations:
+   ```bash
+   git log --all --grep="grpc" --oneline
+   git show <commit-hash>:cmake/grpc.cmake
+   ```
+
+3. **Enable debug logging**:
+   ```bash
+   YAZE_LOG_LEVEL=DEBUG ./build/bin/yaze 2>&1 | tee debug.log
+   ```
+
+4. **Create a minimal reproduction**:
+   - Isolate the failing component
+   - Create a minimal CMakeLists.txt
+   - Test with minimal dependencies
+
+5. **File an issue** with:
+   - Platform and OS version
+   - CMake preset used
+   - Full error output
+   - `cmake -LA build/` output
+   - Relevant CMakeCache.txt entries