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.
This commit is contained in:
scawful
84
.github/actions/README.md
vendored
Normal file
84
.github/actions/README.md
vendored
Normal file
@@ -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
|
||||||
|
|
||||||
264
docs/BUILD-GUIDE.md
Normal file
264
docs/BUILD-GUIDE.md
Normal file
@@ -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
|
||||||
472
docs/BUILD-TROUBLESHOOTING.md
Normal file
472
docs/BUILD-TROUBLESHOOTING.md
Normal file
@@ -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
|
||||||
Reference in New Issue
Block a user