backend-infra-engineer: Release v0.3.3 snapshot
This commit is contained in:
scawful
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