From 746ade46ee15723f00111b357d70c27fd47ca83e Mon Sep 17 00:00:00 2001 From: scawful Date: Sat, 1 Nov 2025 10:49:00 -0400 Subject: [PATCH] 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. --- .github/actions/README.md | 84 ++++++ docs/BUILD-GUIDE.md | 264 +++++++++++++++++++ docs/BUILD-TROUBLESHOOTING.md | 472 ++++++++++++++++++++++++++++++++++ 3 files changed, 820 insertions(+) create mode 100644 .github/actions/README.md create mode 100644 docs/BUILD-GUIDE.md create mode 100644 docs/BUILD-TROUBLESHOOTING.md diff --git a/.github/actions/README.md b/.github/actions/README.md new file mode 100644 index 00000000..33584c36 --- /dev/null +++ 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 + diff --git a/docs/BUILD-GUIDE.md b/docs/BUILD-GUIDE.md new file mode 100644 index 00000000..9ee93415 --- /dev/null +++ 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 diff --git a/docs/BUILD-TROUBLESHOOTING.md b/docs/BUILD-TROUBLESHOOTING.md new file mode 100644 index 00000000..e57a4ae8 --- /dev/null +++ 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 $) +``` + +### 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 :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