backend-infra-engineer: Release v0.3.3 snapshot
This commit is contained in:
scawful
320
docs/public/build/build-from-source.md
Normal file
320
docs/public/build/build-from-source.md
Normal file
@@ -0,0 +1,320 @@
|
||||
# Build Instructions
|
||||
|
||||
yaze uses a modern CMake build system with presets for easy configuration. This guide explains the
|
||||
environment checks, dependencies, and platform-specific considerations. For concise per-platform
|
||||
commands, always start with the [Build & Test Quick Reference](quick-reference.md).
|
||||
|
||||
## 1. Environment Verification
|
||||
|
||||
**Before your first build**, run the verification script to ensure your environment is configured correctly.
|
||||
|
||||
### Windows (PowerShell)
|
||||
```powershell
|
||||
.\scripts\verify-build-environment.ps1
|
||||
|
||||
# With automatic fixes
|
||||
.\scripts\verify-build-environment.ps1 -FixIssues
|
||||
```
|
||||
> Tip: After verification, run `.\scripts\setup-vcpkg-windows.ps1` to bootstrap vcpkg, ensure `clang-cl`/Ninja are installed, and cache the `x64-windows` triplet.
|
||||
|
||||
### macOS & Linux (Bash)
|
||||
```bash
|
||||
./scripts/verify-build-environment.sh
|
||||
|
||||
# With automatic fixes
|
||||
./scripts\verify-build-environment.sh --fix
|
||||
```
|
||||
|
||||
The script checks for required tools like CMake, a C++23 compiler, and platform-specific dependencies.
|
||||
|
||||
## 2. Using Presets
|
||||
|
||||
- Pick the preset that matches your platform/workflow (debug: `mac-dbg` / `lin-dbg` / `win-dbg`,
|
||||
AI-enabled: `mac-ai` / `win-ai`, release: `*-rel`, etc.).
|
||||
- Configure with `cmake --preset <name>` and build with `cmake --build --preset <name> [--target …]`.
|
||||
- Add `-v` to a preset name (e.g., `mac-dbg-v`) to surface compiler warnings.
|
||||
- Need a full matrix? See the [CMake Presets Guide](presets.md) for every preset and the quick
|
||||
reference for ready-to-run command snippets.
|
||||
|
||||
## Feature Toggles & Windows Profiles
|
||||
|
||||
### Windows Presets
|
||||
|
||||
| Preset | Purpose |
|
||||
| --- | --- |
|
||||
| `win-dbg`, `win-rel`, `ci-windows` | Core builds without agent UI, gRPC, or AI runtimes. Fastest option for MSVC/clang-cl. |
|
||||
| `win-ai`, `win-vs-ai` | Full agent stack for local development (UI panels + remote automation + AI runtime). |
|
||||
| `ci-windows-ai` | Nightly/weekly CI preset that exercises the entire automation stack on Windows. |
|
||||
|
||||
### Agent Feature Flags
|
||||
|
||||
| Option | Default | Effect |
|
||||
| --- | --- | --- |
|
||||
| `YAZE_BUILD_AGENT_UI` | `ON` when `YAZE_BUILD_GUI=ON` | Builds the ImGui widgets used by the chat/agent panels. |
|
||||
| `YAZE_ENABLE_REMOTE_AUTOMATION` | `ON` for `*-ai` presets | Adds gRPC/protobuf services plus GUI automation clients. |
|
||||
| `YAZE_ENABLE_AI_RUNTIME` | `ON` for `*-ai` presets | Enables Gemini/Ollama transports, proposal planning, and advanced routing logic. |
|
||||
| `YAZE_ENABLE_AGENT_CLI` | `ON` when `YAZE_BUILD_CLI=ON` | Compiles the conversational agent stack consumed by `z3ed`. |
|
||||
|
||||
Combine these switches to match your workflow: keep everything `OFF` for lightweight GUI hacking or turn them `ON` for automation-heavy work with sketchybar/yabai/skhd, tmux, or remote runners.
|
||||
|
||||
## 3. Dependencies
|
||||
|
||||
- **Required**: CMake 3.16+, C++23 Compiler (GCC 13+, Clang 16+, MSVC 2019+), Git.
|
||||
- **Bundled**: All other dependencies (SDL2, ImGui, Asar, nlohmann/json, cpp-httplib, GoogleTest, etc.) live under the `ext/` directory or are managed by CMake's `FetchContent`. No external package manager is required for a basic build.
|
||||
- **Optional**:
|
||||
- **gRPC**: For GUI test automation. Can be enabled with `-DYAZE_WITH_GRPC=ON`.
|
||||
- **vcpkg (Windows)**: Can be used for faster gRPC builds on Windows (optional).
|
||||
|
||||
## 4. Platform Setup
|
||||
|
||||
### macOS
|
||||
```bash
|
||||
# Install Xcode Command Line Tools
|
||||
xcode-select --install
|
||||
|
||||
# Recommended: Install build tools via Homebrew
|
||||
brew install cmake pkg-config
|
||||
|
||||
# For sandboxed/offline builds: Install dependencies to avoid network fetch
|
||||
brew install yaml-cpp googletest
|
||||
```
|
||||
|
||||
**Note**: When building in sandboxed/offline environments (e.g., via Claude Code or restricted networks), install `yaml-cpp` and `googletest` via Homebrew to avoid GitHub fetch failures. The build system automatically detects Homebrew installations and uses them as fallback:
|
||||
- yaml-cpp: `/opt/homebrew/opt/yaml-cpp`, `/usr/local/opt/yaml-cpp`
|
||||
- googletest: `/opt/homebrew/opt/googletest`, `/usr/local/opt/googletest`
|
||||
|
||||
### 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
|
||||
1. **Install Visual Studio 2022** with the “Desktop development with C++” workload (requires MSVC + MSBuild).
|
||||
2. **Install Ninja** (recommended): `choco install ninja` or enable the “CMake tools for Windows” optional component.
|
||||
3. Run the verifier: `.\scripts\verify-build-environment.ps1 -FixIssues` – this checks Visual Studio workloads, Ninja, clang-cl, Git settings, and vcpkg cache.
|
||||
4. Bootstrap vcpkg once: `.\scripts\setup-vcpkg-windows.ps1` (prefetches SDL2, yaml-cpp, etc.).
|
||||
5. Use the `win-*` presets (Ninja) or `win-vs-*` presets (Visual Studio generator) as needed. For AI/gRPC features, prefer `win-ai` / `win-vs-ai`.
|
||||
6. For quick validation, run the PowerShell helper:
|
||||
```powershell
|
||||
pwsh -File scripts/agents/windows-smoke-build.ps1 -Preset win-ai -Target z3ed
|
||||
```
|
||||
|
||||
## 5. Testing
|
||||
|
||||
The project uses CTest and GoogleTest. Tests are organized into categories using labels. See the [Testing Guide](../developer/testing-guide.md) for details.
|
||||
|
||||
### Running Tests with Presets
|
||||
|
||||
The easiest way to run tests is with `ctest` presets.
|
||||
|
||||
```bash
|
||||
# Configure a development build (enables ROM-dependent tests)
|
||||
cmake --preset mac-dev -DYAZE_TEST_ROM_PATH=/path/to/your/zelda3.sfc
|
||||
|
||||
# Build the tests
|
||||
cmake --build --preset mac-dev --target yaze_test
|
||||
|
||||
# Run stable tests (fast, run in CI)
|
||||
ctest --preset dev
|
||||
|
||||
# Run all tests, including ROM-dependent and experimental
|
||||
ctest --preset all
|
||||
```
|
||||
|
||||
### Running Tests Manually
|
||||
|
||||
You can also run tests by invoking the test executable directly or using CTest with labels.
|
||||
|
||||
```bash
|
||||
# Run all tests via the executable
|
||||
./build/bin/yaze_test
|
||||
|
||||
# Run only stable tests using CTest labels
|
||||
ctest --test-dir build --label-regex "STABLE"
|
||||
|
||||
# Run tests matching a name
|
||||
ctest --test-dir build -R "AsarWrapperTest"
|
||||
|
||||
# Exclude ROM-dependent tests
|
||||
ctest --test-dir build --label-exclude "ROM_DEPENDENT"
|
||||
```
|
||||
|
||||
## 6. IDE Integration
|
||||
|
||||
### VS Code (Recommended)
|
||||
1. Install the **CMake Tools** extension.
|
||||
2. Open the project folder.
|
||||
3. Select a preset from the status bar (e.g., `mac-ai`). On Windows, choose the desired kit (e.g., “Visual Studio Build Tools 2022”) so the generator matches your preset (`win-*` uses Ninja, `win-vs-*` uses Visual Studio).
|
||||
4. Press F5 to build and debug.
|
||||
5. After changing presets, run `cp build/compile_commands.json .` to update IntelliSense.
|
||||
|
||||
### Visual Studio (Windows)
|
||||
1. Select **File → Open → Folder** and choose the `yaze` directory.
|
||||
2. Visual Studio will automatically detect `CMakePresets.json`.
|
||||
3. Select the desired preset (e.g., `win-dbg` or `win-ai`) from the configuration dropdown.
|
||||
4. Press F5 to build and run.
|
||||
|
||||
### Xcode (macOS)
|
||||
```bash
|
||||
# Generate an Xcode project from a preset
|
||||
cmake --preset mac-dbg -G Xcode
|
||||
|
||||
# Open the project
|
||||
open build/yaze.xcodeproj
|
||||
```
|
||||
|
||||
## 7. Windows Build Optimization
|
||||
|
||||
### GitHub Actions / CI Builds
|
||||
|
||||
**Current Configuration (Optimized):**
|
||||
- **Compilers**: Both clang-cl and MSVC supported (matrix)
|
||||
- **vcpkg**: Only fast packages (SDL2, yaml-cpp) - 2 minutes
|
||||
- **gRPC**: Built via FetchContent (v1.75.1) - cached after first build
|
||||
- **Caching**: Aggressive multi-tier caching (vcpkg + FetchContent + sccache)
|
||||
- **Agent matrix**: A dedicated `ci-windows-ai` job runs outside pull requests to exercise the full gRPC + AI runtime stack.
|
||||
- **Expected time**:
|
||||
- First build: ~10-15 minutes
|
||||
- Cached build: ~3-5 minutes
|
||||
|
||||
**Why FetchContent for gRPC in CI?**
|
||||
- vcpkg's latest gRPC (v1.71.0) has no pre-built binaries
|
||||
- Building from source via vcpkg: 45-90 minutes
|
||||
- FetchContent with caching: 10-15 minutes first time, <1 min cached
|
||||
- Better control over gRPC version (v1.75.1 - latest stable)
|
||||
- BoringSSL ASM disabled on Windows for clang-cl compatibility
|
||||
- zlib conflict: gRPC's FetchContent builds its own zlib, conflicts with vcpkg's
|
||||
|
||||
### Desktop Development: Faster builds with vcpkg (optional)
|
||||
|
||||
For desktop development, you can use vcpkg for faster gRPC builds:
|
||||
|
||||
```powershell
|
||||
# Bootstrap vcpkg and prefetch packages
|
||||
.\scripts\setup-vcpkg-windows.ps1
|
||||
|
||||
# Configure with vcpkg
|
||||
cmake -B build -DYAZE_USE_VCPKG_GRPC=ON -DCMAKE_TOOLCHAIN_FILE=vcpkg/scripts/buildsystems/vcpkg.cmake
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- Pre-compiled gRPC packages: ~5 minutes vs ~10-15 minutes
|
||||
- No need to build gRPC from source
|
||||
- Faster iteration during development
|
||||
|
||||
**Note:** CI/CD workflows use FetchContent by default for reliability.
|
||||
|
||||
### Local Development
|
||||
|
||||
#### Fast Build (Recommended)
|
||||
|
||||
Use FetchContent for all dependencies (matches CI):
|
||||
```powershell
|
||||
# Configure (first time: ~15 min, subsequent: ~2 min)
|
||||
cmake -B build -G "Visual Studio 17 2022" -A x64
|
||||
|
||||
# Build
|
||||
cmake --build build --config RelWithDebInfo --parallel
|
||||
```
|
||||
|
||||
#### Using vcpkg (Optional)
|
||||
|
||||
If you prefer vcpkg for local development:
|
||||
```powershell
|
||||
# Install ONLY the fast packages
|
||||
vcpkg install sdl2:x64-windows yaml-cpp:x64-windows
|
||||
|
||||
# Let CMake use FetchContent for gRPC
|
||||
cmake -B build -DCMAKE_TOOLCHAIN_FILE=vcpkg/scripts/buildsystems/vcpkg.cmake
|
||||
```
|
||||
|
||||
**DO NOT** install grpc or zlib via vcpkg:
|
||||
- gRPC v1.71.0 has no pre-built binaries (45-90 min build)
|
||||
- zlib conflicts with gRPC's bundled zlib
|
||||
|
||||
### Compiler Support
|
||||
|
||||
**clang-cl (Recommended):**
|
||||
- Used in both CI and release workflows
|
||||
- Better diagnostics than MSVC
|
||||
- Fully compatible with MSVC libraries
|
||||
|
||||
**MSVC:**
|
||||
- Also tested in CI matrix
|
||||
- Fallback option if clang-cl issues occur
|
||||
|
||||
**Compiler Flags (Applied Automatically):**
|
||||
- `/bigobj` - Large object files (required for gRPC)
|
||||
- `/permissive-` - Standards conformance
|
||||
- `/wd4267 /wd4244` - Suppress harmless conversion warnings
|
||||
- `/constexpr:depth2048` - Template instantiation depth
|
||||
|
||||
## 8. Troubleshooting
|
||||
|
||||
Build issues, especially on Windows, often stem from environment misconfiguration. Before anything else, run the verification script.
|
||||
|
||||
```powershell
|
||||
# Run the verification script in PowerShell
|
||||
.\scripts\verify-build-environment.ps1
|
||||
```
|
||||
|
||||
This script is your primary diagnostic tool and can detect most common problems.
|
||||
|
||||
### Automatic Fixes
|
||||
|
||||
If the script finds issues, you can often fix them automatically by running it with the `-FixIssues` flag. This can:
|
||||
- Synchronize Git submodules.
|
||||
- Correct Git `core.autocrlf` and `core.longpaths` settings, which are critical for cross-platform compatibility on Windows.
|
||||
- Prompt to clean stale CMake caches.
|
||||
|
||||
```powershell
|
||||
# Attempt to fix detected issues automatically
|
||||
.\scripts\verify-build-environment.ps1 -FixIssues
|
||||
```
|
||||
|
||||
### Cleaning Stale Builds
|
||||
|
||||
After pulling major changes or switching branches, your build directory can become "stale," leading to strange compiler or linker errors. The verification script will warn you about old build files. You can clean them manually or use the `-CleanCache` flag.
|
||||
|
||||
**This will delete all `build*` and `out` directories.**
|
||||
|
||||
```powershell
|
||||
# Clean all build artifacts to start fresh
|
||||
.\scripts\verify-build-environment.ps1 -CleanCache
|
||||
```
|
||||
|
||||
### Common Issues
|
||||
|
||||
#### "nlohmann/json.hpp: No such file or directory"
|
||||
**Cause**: You are building code that requires AI features without using an AI-enabled preset, or your Git submodules are not initialized.
|
||||
**Solution**:
|
||||
1. Use an AI preset like `win-ai` or `mac-ai`.
|
||||
2. Ensure submodules are present by running `git submodule update --init --recursive`.
|
||||
|
||||
#### "Cannot open file 'yaze.exe': Permission denied"
|
||||
**Cause**: A previous instance of `yaze.exe` is still running in the background.
|
||||
**Solution**: Close it using Task Manager or run:
|
||||
```cmd
|
||||
taskkill /F /IM yaze.exe
|
||||
```
|
||||
|
||||
#### "C++ standard 'cxx_std_23' not supported"
|
||||
**Cause**: Your compiler is too old.
|
||||
**Solution**: Update your tools. You need Visual Studio 2022 17.4+, GCC 13+, or Clang 16+. The verification script checks this.
|
||||
|
||||
#### Visual Studio Can't Find Presets
|
||||
**Cause**: VS failed to parse `CMakePresets.json` or its cache is corrupt.
|
||||
**Solution**:
|
||||
1. Close and reopen the folder (`File -> Close Folder`).
|
||||
2. Check the "CMake" pane in the Output window for specific JSON parsing errors.
|
||||
3. Delete the hidden `.vs` directory in the project root to force Visual Studio to re-index the project.
|
||||
|
||||
#### Git Line Ending (CRLF) Issues
|
||||
**Cause**: Git may be automatically converting line endings, which can break shell scripts and other assets.
|
||||
**Solution**: The verification script checks for this. Use the `-FixIssues` flag or run `git config --global core.autocrlf false` to prevent this behavior.
|
||||
|
||||
#### File Path Length Limit on Windows
|
||||
**Cause**: By default, Windows has a 260-character path limit, which can be exceeded by nested dependencies.
|
||||
**Solution**: The verification script checks for this. Use the `-FixIssues` flag or run `git config --global core.longpaths true` to enable long path support.
|
||||
224
docs/public/build/platform-compatibility.md
Normal file
224
docs/public/build/platform-compatibility.md
Normal file
@@ -0,0 +1,224 @@
|
||||
# Platform Compatibility & CI/CD Fixes
|
||||
|
||||
**Last Updated**: October 9, 2025
|
||||
|
||||
---
|
||||
|
||||
## Platform-Specific Notes
|
||||
|
||||
### Windows
|
||||
|
||||
**Build System:**
|
||||
- Supported compilers: clang-cl (preferred), MSVC 2022 17.4+
|
||||
- Uses vcpkg for: SDL2, yaml-cpp (fast packages only)
|
||||
- Uses FetchContent for: gRPC v1.75.1, protobuf, abseil, zlib (better caching)
|
||||
|
||||
**Why FetchContent for gRPC?**
|
||||
- vcpkg gRPC v1.71.0 has no pre-built binaries (builds from source: 45-90 min)
|
||||
- FetchContent uses v1.75.1 (latest stable with modern compiler support)
|
||||
- BoringSSL ASM disabled on Windows (avoids NASM build conflicts with clang-cl)
|
||||
- Better caching in CI/CD (separate cache keys for vcpkg vs FetchContent)
|
||||
- First build: ~10-15 min, subsequent: <1 min (cached)
|
||||
- zlib bundled with gRPC (avoids vcpkg conflicts)
|
||||
|
||||
**Compiler Flags (both clang-cl and MSVC):**
|
||||
- `/bigobj` - Support large object files (required for gRPC)
|
||||
- `/permissive-` - Standards conformance mode
|
||||
- `/wd4267 /wd4244` - Suppress harmless conversion warnings
|
||||
- `/constexpr:depth2048` - Deep template instantiation (MSVC 2019+)
|
||||
|
||||
**Macro Definitions:**
|
||||
- `WIN32_LEAN_AND_MEAN` - Reduce Windows header pollution
|
||||
- `NOMINMAX` - Prevent min/max macro conflicts
|
||||
- `NOGDI` - Prevent GDI macro conflicts (DWORD, etc.)
|
||||
- `__PRFCHWINTRIN_H` - Work around Clang 20 `_m_prefetchw` linkage clash
|
||||
|
||||
**Build Times:**
|
||||
- First build (no cache): ~10-15 minutes
|
||||
- Incremental build (cached): ~3-5 minutes
|
||||
- CI/CD with full caching: ~5-8 minutes
|
||||
|
||||
**CI/CD Configuration:**
|
||||
- Compiler matrix: clang-cl + MSVC
|
||||
- 3-tier caching: vcpkg packages, FetchContent deps, sccache objects
|
||||
- Binary caching via GitHub Actions for vcpkg
|
||||
- Parallel builds: 4 jobs
|
||||
|
||||
### macOS
|
||||
|
||||
**Build System:**
|
||||
- Uses vcpkg for: SDL2, yaml-cpp, zlib
|
||||
- Uses FetchContent for: gRPC, abseil, protobuf
|
||||
|
||||
**Supported Architectures:**
|
||||
- x64 (Intel Macs) - macOS 13+
|
||||
- ARM64 (Apple Silicon) - macOS 14+
|
||||
|
||||
**Build Times:**
|
||||
- First build: ~20-30 minutes
|
||||
- Subsequent builds: ~3-5 minutes
|
||||
|
||||
### Linux
|
||||
|
||||
**Build System:**
|
||||
- Uses system packages (apt) for most dependencies
|
||||
- Does NOT use vcpkg
|
||||
- Uses FetchContent for: gRPC, abseil, protobuf (when not in system)
|
||||
|
||||
**Required System Packages:**
|
||||
```bash
|
||||
build-essential ninja-build pkg-config libglew-dev libxext-dev
|
||||
libwavpack-dev libabsl-dev libboost-all-dev libpng-dev python3-dev
|
||||
libpython3-dev libasound2-dev libpulse-dev libaudio-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 gcc-12 g++-12 clang-15
|
||||
```
|
||||
|
||||
**Build Times:**
|
||||
- First build: ~15-20 minutes
|
||||
- Subsequent builds: ~2-4 minutes
|
||||
|
||||
---
|
||||
|
||||
## Cross-Platform Code Validation
|
||||
|
||||
The following subsystems run unchanged across Windows, macOS, and Linux:
|
||||
|
||||
- Audio backend (`src/app/emu/audio`) uses SDL2 only; no platform branches.
|
||||
- Input backend/manager (`src/app/emu/input`) runs on SDL2 abstractions.
|
||||
- Debug tools (`src/app/emu/debug`) avoid OS-specific headers.
|
||||
- Emulator UI (`src/app/emu/ui`) is pure ImGui + SDL2.
|
||||
|
||||
---
|
||||
|
||||
## Common Build Issues & Solutions
|
||||
|
||||
### Windows: "use of undefined type 'PromiseLike'"
|
||||
**Cause:** Old gRPC version (< v1.67.1)
|
||||
**Fix:** Clear build cache and reconfigure
|
||||
```powershell
|
||||
rm -r build/_deps/grpc-*
|
||||
cmake -B build -G "Visual Studio 17 2022" -A x64
|
||||
```
|
||||
|
||||
### macOS: "absl not found"
|
||||
**Cause:** vcpkg not finding abseil packages
|
||||
**Fix:** Use FetchContent (default) - abseil is fetched automatically by gRPC
|
||||
```bash
|
||||
cmake -B build
|
||||
```
|
||||
|
||||
### Linux: CMake configuration fails
|
||||
**Cause:** Missing system dependencies
|
||||
**Fix:** Install required packages
|
||||
```bash
|
||||
sudo apt-get update
|
||||
sudo apt-get install -y [see package list above]
|
||||
```
|
||||
|
||||
### Windows: "DWORD syntax error"
|
||||
**Cause:** Windows macros conflicting with protobuf enums
|
||||
**Fix:** Ensure `NOGDI` is defined (now automatic in grpc.cmake)
|
||||
|
||||
---
|
||||
|
||||
## CI/CD Validation Checklist
|
||||
|
||||
Before merging platform-specific changes:
|
||||
|
||||
- Confirm the vcpkg baseline matches `vcpkg.json`.
|
||||
- Do not reintroduce the Windows x86 build (cpp-httplib incompatibility).
|
||||
- Keep Windows macro guards (`NOGDI`, `NOMINMAX`, `WIN32_LEAN_AND_MEAN`) in place.
|
||||
- Build against gRPC 1.67.1 with the MSVC workaround flags.
|
||||
- Leave shared code paths on SDL2/ImGui abstractions.
|
||||
- Re-run the full matrix if caches or presets change.
|
||||
|
||||
### CI/CD Performance Roadmap
|
||||
|
||||
- **Dependency caching**: Cache vcpkg installs on Windows plus Homebrew/apt
|
||||
archives to trim 5-10 minutes per job; track cache keys via OS + lockfiles.
|
||||
- **Compiler caching**: Enable `ccache`/`sccache` across the matrix using the
|
||||
`hendrikmuhs/ccache-action` with 500 MB per-run limits for 3-5 minute wins.
|
||||
- **Conditional work**: Add a path-filter job that skips emulator builds or
|
||||
full test runs when only docs or CLI code change; fall back to full matrix on
|
||||
shared components.
|
||||
- **Reusable workflows**: Centralize setup steps (checking out submodules,
|
||||
restoring caches, configuring presets) to reduce duplication between `ci.yml`
|
||||
and `release.yml`.
|
||||
- **Release optimizations**: Use lean presets without test targets, run platform
|
||||
builds in parallel, and reuse cached artifacts from CI when hashes match.
|
||||
|
||||
---
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
### Automated (CI)
|
||||
- Ubuntu 22.04 (GCC-12, Clang-15)
|
||||
- macOS 13/14 (x64 and ARM64)
|
||||
- Windows Server 2022 (x64)
|
||||
- Core tests: `AsarWrapperTest`, `SnesTileTest`, others tagged `STABLE`
|
||||
- Tooling: clang-format, clang-tidy, cppcheck
|
||||
- Sanitizers: Linux AddressSanitizer job
|
||||
|
||||
### Manual Testing
|
||||
After successful CI build:
|
||||
- Windows: verify audio backend, keyboard input, APU debugger UI.
|
||||
- Linux: verify input polling and audio output.
|
||||
- macOS: spot-check rendering, input, audio.
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Build Command (All Platforms)
|
||||
```bash
|
||||
cmake -B build
|
||||
cmake --build build --parallel
|
||||
|
||||
cmake --preset [mac-dbg|lin-dbg|win-dbg]
|
||||
cmake --build --preset [mac-dbg|lin-dbg|win-dbg]
|
||||
```
|
||||
|
||||
### Enable Features
|
||||
All features (JSON, gRPC, AI) are **always enabled** by default.
|
||||
No need to specify `-DZ3ED_AI=ON` or `-DYAZE_WITH_GRPC=ON`.
|
||||
|
||||
### Windows Troubleshooting
|
||||
```powershell
|
||||
# Verify environment
|
||||
.\scripts\verify-build-environment.ps1
|
||||
|
||||
# Use vcpkg for faster builds
|
||||
.\scripts\setup-vcpkg-windows.ps1
|
||||
cmake -B build -DCMAKE_TOOLCHAIN_FILE="vcpkg/scripts/buildsystems/vcpkg.cmake"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Filesystem Abstraction
|
||||
|
||||
To ensure robust and consistent behavior across platforms, YAZE has standardized its filesystem operations:
|
||||
|
||||
- **`std::filesystem`**: All new and refactored code uses the C++17 `std::filesystem` library for path manipulation, directory iteration, and file operations. This eliminates platform-specific bugs related to path separators (`/` vs `\`).
|
||||
|
||||
- **`PlatformPaths` Utility**: A dedicated utility class, `yaze::util::PlatformPaths`, provides platform-aware API for retrieving standard directory locations:
|
||||
- **Application Data**: `%APPDATA%` on Windows, `~/Library/Application Support` on macOS, XDG Base Directory on Linux
|
||||
- **Configuration Files**: Semantically clear API for config file locations
|
||||
- **Home and Temporary Directories**: Safely resolves user-specific and temporary folders
|
||||
|
||||
This removes legacy platform-specific APIs (like `dirent.h` or Win32 directory functions) for cleaner, more maintainable file handling.
|
||||
|
||||
---
|
||||
|
||||
## Native File Dialog Support
|
||||
|
||||
YAZE features native file dialogs on all platforms:
|
||||
- **macOS**: Cocoa-based file selection with proper sandboxing support
|
||||
- **Windows**: Windows Explorer integration with COM APIs (`IFileOpenDialog`/`IFileSaveDialog`)
|
||||
- **Linux**: GTK3 dialogs that match system appearance
|
||||
- **Fallback**: Cross-platform implementation when native dialogs unavailable
|
||||
|
||||
---
|
||||
|
||||
**Status:** All CI/CD issues resolved. Next push should build successfully on all platforms.
|
||||
206
docs/public/build/presets.md
Normal file
206
docs/public/build/presets.md
Normal file
@@ -0,0 +1,206 @@
|
||||
# Build Presets Guide
|
||||
|
||||
This document explains the reorganized CMake preset system for Yaze.
|
||||
|
||||
## Design Principles
|
||||
|
||||
1. **Short, memorable names** - No more `macos-dev-z3ed-ai`, just `mac-ai`
|
||||
2. **Warnings off by default** - Add `-v` suffix for verbose (e.g., `mac-dbg-v`)
|
||||
3. **Clear architecture support** - Explicit ARM64 and x86_64 presets
|
||||
4. **Platform prefixes** - `mac-`, `win-`, `lin-` for easy identification
|
||||
|
||||
## Quick Start
|
||||
|
||||
### macOS Development
|
||||
```bash
|
||||
# Most common: AI-enabled development
|
||||
cmake --preset mac-ai
|
||||
cmake --build --preset mac-ai
|
||||
|
||||
# Basic debug build (no AI)
|
||||
cmake --preset mac-dbg
|
||||
cmake --build --preset mac-dbg
|
||||
|
||||
# Verbose warnings for debugging
|
||||
cmake --preset mac-dbg-v
|
||||
cmake --build --preset mac-dbg-v
|
||||
|
||||
# Release build
|
||||
cmake --preset mac-rel
|
||||
cmake --build --preset mac-rel
|
||||
```
|
||||
|
||||
### Windows Development
|
||||
```bash
|
||||
# Debug build (x64)
|
||||
cmake --preset win-dbg
|
||||
cmake --build --preset win-dbg
|
||||
|
||||
# AI-enabled development
|
||||
cmake --preset win-ai
|
||||
cmake --build --preset win-ai
|
||||
|
||||
# ARM64 support
|
||||
cmake --preset win-arm
|
||||
cmake --build --preset win-arm
|
||||
```
|
||||
|
||||
## All Presets
|
||||
|
||||
### macOS Presets
|
||||
|
||||
| Preset | Description | Arch | Warnings | Features |
|
||||
|--------|-------------|------|----------|----------|
|
||||
| `mac-dbg` | Debug build | ARM64 | Off | Basic |
|
||||
| `mac-dbg-v` | Debug verbose | ARM64 | On | Basic |
|
||||
| `mac-rel` | Release | ARM64 | Off | Basic |
|
||||
| `mac-x64` | Debug x86_64 | x86_64 | Off | Basic |
|
||||
| `mac-uni` | Universal binary | Both | Off | Basic |
|
||||
| `mac-dev` | Development | ARM64 | Off | ROM tests |
|
||||
| `mac-ai` | AI development | ARM64 | Off | z3ed, JSON, gRPC, ROM tests |
|
||||
| `mac-z3ed` | z3ed CLI | ARM64 | Off | AI agent support |
|
||||
| `mac-rooms` | Dungeon editor | ARM64 | Off | Minimal build for room editing |
|
||||
|
||||
### Windows Presets
|
||||
|
||||
| Preset | Description | Arch | Warnings | Features |
|
||||
|--------|-------------|------|----------|----------|
|
||||
| `win-dbg` | Debug build | x64 | Off | Basic |
|
||||
| `win-dbg-v` | Debug verbose | x64 | On | Basic |
|
||||
| `win-rel` | Release | x64 | Off | Basic |
|
||||
| `win-arm` | Debug ARM64 | ARM64 | Off | Basic |
|
||||
| `win-arm-rel` | Release ARM64 | ARM64 | Off | Basic |
|
||||
| `win-dev` | Development | x64 | Off | ROM tests |
|
||||
| `win-ai` | AI development | x64 | Off | z3ed, JSON, gRPC, ROM tests |
|
||||
| `win-z3ed` | z3ed CLI | x64 | Off | AI agent support |
|
||||
|
||||
### Linux Presets
|
||||
|
||||
| Preset | Description | Compiler | Warnings |
|
||||
|--------|-------------|----------|----------|
|
||||
| `lin-dbg` | Debug | GCC | Off |
|
||||
| `lin-clang` | Debug | Clang | Off |
|
||||
|
||||
### Special Purpose
|
||||
|
||||
| Preset | Description |
|
||||
|--------|-------------|
|
||||
| `ci` | Continuous integration (no ROM tests) |
|
||||
| `asan` | AddressSanitizer build |
|
||||
| `coverage` | Code coverage build |
|
||||
|
||||
## Warning Control
|
||||
|
||||
By default, all presets suppress compiler warnings with `-w` for a cleaner build experience.
|
||||
|
||||
### To Enable Verbose Warnings:
|
||||
|
||||
1. Use a preset with `-v` suffix (e.g., `mac-dbg-v`, `win-dbg-v`)
|
||||
2. Or set `YAZE_SUPPRESS_WARNINGS=OFF` manually:
|
||||
```bash
|
||||
cmake --preset mac-dbg -DYAZE_SUPPRESS_WARNINGS=OFF
|
||||
```
|
||||
|
||||
## Architecture Support
|
||||
|
||||
### macOS
|
||||
- **ARM64 (Apple Silicon)**: `mac-dbg`, `mac-rel`, `mac-ai`, etc.
|
||||
- **x86_64 (Intel)**: `mac-x64`
|
||||
- **Universal Binary**: `mac-uni` (both ARM64 + x86_64)
|
||||
|
||||
### Windows
|
||||
- **x64**: `win-dbg`, `win-rel`, `win-ai`, etc.
|
||||
- **ARM64**: `win-arm`, `win-arm-rel`
|
||||
|
||||
## Build Directories
|
||||
|
||||
Most presets use `build/` directory. Exceptions:
|
||||
- `mac-rooms`: Uses `build_rooms/` to avoid conflicts
|
||||
|
||||
## Feature Flags
|
||||
|
||||
Common CMake options you can override:
|
||||
|
||||
```bash
|
||||
# Enable/disable components
|
||||
-DYAZE_BUILD_TESTS=ON/OFF
|
||||
-DYAZE_BUILD_Z3ED=ON/OFF
|
||||
-DYAZE_BUILD_EMU=ON/OFF
|
||||
-DYAZE_BUILD_APP=ON/OFF
|
||||
|
||||
# AI features
|
||||
-DZ3ED_AI=ON/OFF
|
||||
-DYAZE_WITH_JSON=ON/OFF
|
||||
-DYAZE_WITH_GRPC=ON/OFF
|
||||
|
||||
# Testing
|
||||
-DYAZE_ENABLE_ROM_TESTS=ON/OFF
|
||||
-DYAZE_TEST_ROM_PATH=/path/to/zelda3.sfc
|
||||
|
||||
# Build optimization
|
||||
-DYAZE_MINIMAL_BUILD=ON/OFF
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### Development with AI features and verbose warnings
|
||||
```bash
|
||||
cmake --preset mac-dbg-v -DZ3ED_AI=ON -DYAZE_WITH_GRPC=ON
|
||||
cmake --build --preset mac-dbg-v
|
||||
```
|
||||
|
||||
### Release build for distribution (macOS Universal)
|
||||
```bash
|
||||
cmake --preset mac-uni
|
||||
cmake --build --preset mac-uni
|
||||
cpack --preset mac-uni
|
||||
```
|
||||
|
||||
### Quick minimal build for testing
|
||||
```bash
|
||||
cmake --preset mac-dbg -DYAZE_MINIMAL_BUILD=ON
|
||||
cmake --build --preset mac-dbg -j12
|
||||
```
|
||||
|
||||
## Updating compile_commands.json
|
||||
|
||||
After configuring with a new preset, copy the compile commands for IDE support:
|
||||
|
||||
```bash
|
||||
cp build/compile_commands.json .
|
||||
```
|
||||
|
||||
This ensures clangd and other LSP servers can find headers and understand build flags.
|
||||
|
||||
## Migration from Old Presets
|
||||
|
||||
Old preset names have been simplified:
|
||||
|
||||
| Old Name | New Name |
|
||||
|----------|----------|
|
||||
| `macos-dev-z3ed-ai` | `mac-ai` |
|
||||
| `macos-debug` | `mac-dbg` |
|
||||
| `macos-release` | `mac-rel` |
|
||||
| `macos-debug-universal` | `mac-uni` |
|
||||
| `macos-dungeon-dev` | `mac-rooms` |
|
||||
| `windows-debug` | `win-dbg` |
|
||||
| `windows-release` | `win-rel` |
|
||||
| `windows-arm64-debug` | `win-arm` |
|
||||
| `linux-debug` | `lin-dbg` |
|
||||
| `linux-clang` | `lin-clang` |
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Warnings are still showing
|
||||
- Make sure you're using a preset without `-v` suffix
|
||||
- Check `cmake` output for `✓ Warnings suppressed` message
|
||||
- Reconfigure and rebuild: `rm -rf build && cmake --preset mac-dbg`
|
||||
|
||||
### clangd can't find nlohmann/json
|
||||
- Run `cmake --preset <your-preset>` to regenerate compile_commands.json
|
||||
- Copy to root: `cp build/compile_commands.json .`
|
||||
- Restart your IDE or LSP server
|
||||
|
||||
### Build fails with missing dependencies
|
||||
- Ensure submodules are initialized: `git submodule update --init --recursive`
|
||||
- For AI features, make sure you have OpenSSL: `brew install openssl` (macOS)
|
||||
80
docs/public/build/quick-reference.md
Normal file
80
docs/public/build/quick-reference.md
Normal file
@@ -0,0 +1,80 @@
|
||||
# Build & Test Quick Reference
|
||||
|
||||
Use this document as the single source of truth for configuring, building, and testing YAZE across
|
||||
platforms. Other guides (README, CLAUDE.md, GEMINI.md, etc.) should link here instead of duplicating
|
||||
steps.
|
||||
|
||||
## 1. Environment Prep
|
||||
- Clone with submodules: `git clone --recursive https://github.com/scawful/yaze.git`
|
||||
- Run the verifier once per machine:
|
||||
- macOS/Linux: `./scripts/verify-build-environment.sh --fix`
|
||||
- Windows PowerShell: `.\scripts\verify-build-environment.ps1 -FixIssues`
|
||||
|
||||
## 2. Build Presets
|
||||
Use `cmake --preset <name>` followed by `cmake --build --preset <name> [--target …]`.
|
||||
|
||||
| Preset | Platform(s) | Notes |
|
||||
|-------------|-------------|-------|
|
||||
| `mac-dbg`, `lin-dbg`, `win-dbg` | macOS/Linux/Windows | Standard debug builds, tests on by default. |
|
||||
| `mac-ai`, `lin-ai`, `win-ai` | macOS/Linux/Windows | Enables gRPC, agent UI, `z3ed`, and AI runtime. |
|
||||
| `mac-rel`, `lin-rel`, `win-rel` | macOS/Linux/Windows | Optimized release builds. |
|
||||
| `mac-dev`, `lin-dev`, `win-dev` | macOS/Linux/Windows | Development builds with ROM-dependent tests enabled. |
|
||||
| `mac-uni` | macOS | Universal binary (ARM64 + x86_64) for distribution. |
|
||||
| `ci-*` presets | Platform-specific | Mirrors CI matrix; see `CMakePresets.json`. |
|
||||
|
||||
**Verbose builds**: add `-v` suffix (e.g., `mac-dbg-v`, `lin-dbg-v`, `win-dbg-v`) to turn off compiler warning suppression.
|
||||
|
||||
## 3. AI/Assistant Build Policy
|
||||
- Human developers typically use `build` or `build_test` directories.
|
||||
- AI assistants **must use dedicated directories** (`build_ai`, `build_agent`, etc.) to avoid
|
||||
clobbering user builds.
|
||||
- When enabling AI features, prefer the `*-ai` presets and target only the binaries you need
|
||||
(`yaze`, `z3ed`, `yaze_test`, …).
|
||||
- Windows helpers: use `scripts/agents/windows-smoke-build.ps1` for quick builds and `scripts/agents/run-tests.sh` (or its PowerShell equivalent) for test runs so preset + generator settings stay consistent.
|
||||
|
||||
## 4. Common Commands
|
||||
```bash
|
||||
# Debug GUI build (macOS)
|
||||
cmake --preset mac-dbg
|
||||
cmake --build --preset mac-dbg --target yaze
|
||||
|
||||
# Debug GUI build (Linux)
|
||||
cmake --preset lin-dbg
|
||||
cmake --build --preset lin-dbg --target yaze
|
||||
|
||||
# Debug GUI build (Windows)
|
||||
cmake --preset win-dbg
|
||||
cmake --build --preset win-dbg --target yaze
|
||||
|
||||
# AI-enabled build with gRPC (macOS)
|
||||
cmake --preset mac-ai
|
||||
cmake --build --preset mac-ai --target yaze z3ed
|
||||
|
||||
# AI-enabled build with gRPC (Linux)
|
||||
cmake --preset lin-ai
|
||||
cmake --build --preset lin-ai --target yaze z3ed
|
||||
|
||||
# AI-enabled build with gRPC (Windows)
|
||||
cmake --preset win-ai
|
||||
cmake --build --preset win-ai --target yaze z3ed
|
||||
```
|
||||
|
||||
## 5. Testing
|
||||
- Build target: `cmake --build --preset <preset> --target yaze_test`
|
||||
- Run all tests: `./build/bin/yaze_test`
|
||||
- Filtered runs:
|
||||
- `./build/bin/yaze_test --unit`
|
||||
- `./build/bin/yaze_test --integration`
|
||||
- `./build/bin/yaze_test --e2e --show-gui`
|
||||
- `./build/bin/yaze_test --rom-dependent --rom-path path/to/zelda3.sfc`
|
||||
- Preset-based ctest: `ctest --preset dev`
|
||||
|
||||
Environment variables:
|
||||
- `YAZE_TEST_ROM_PATH` – default ROM for ROM-dependent tests.
|
||||
- `YAZE_SKIP_ROM_TESTS`, `YAZE_ENABLE_UI_TESTS` – gate expensive suites.
|
||||
|
||||
## 6. Troubleshooting & References
|
||||
- Detailed troubleshooting: `docs/public/build/troubleshooting.md`
|
||||
- Platform compatibility: `docs/public/build/platform-compatibility.md`
|
||||
- Internal agents must follow coordination protocol in
|
||||
`docs/internal/agents/coordination-board.md` before running builds/tests.
|
||||
472
docs/public/build/troubleshooting.md
Normal file
472
docs/public/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