scawful/yaze
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

build: standardize build dir policy

Browse Source
This commit is contained in:
scawful
2025-12-22 14:28:55 -05:00
parent 9333498538
commit ea4e1873de
8 changed files with 268 additions and 194 deletions
Download Patch File Download Diff File Expand all files Collapse all files

46
docs/public/build/build-from-source.md
View File

@@ -42,8 +42,10 @@ Select a preset that matches your platform and workflow:
|----------|---------|
| Debug builds | `mac-dbg`, `lin-dbg`, `win-dbg` |
| AI-enabled builds | `mac-ai`, `lin-ai`, `win-ai` |
| AI + system gRPC (macOS) | `mac-ai-fast` |
| Release builds | `mac-rel`, `lin-rel`, `win-rel` |
| Development (ROM tests) | `mac-dev`, `lin-dev`, `win-dev` |
| Fast test builds | `mac-test`, `lin-test`, `win-test` |
**Build Commands:**
```bash
@@ -57,6 +59,20 @@ See the [CMake Presets Guide](presets.md) for the complete preset reference.
---
## Build Directory Policy
By default, native builds live in `build/` and WASM builds live in `build-wasm/`. Keep additional build directories outside the repo to avoid size creep:
```bash
cp CMakeUserPresets.json.example CMakeUserPresets.json
export YAZE_BUILD_ROOT="$HOME/.cache/yaze"
cmake --preset dev-local
```
For scripts and agent-driven builds, set `YAZE_BUILD_DIR` to an external path (for example, `$HOME/.cache/yaze/build`).
---
## Feature Toggles
### Windows Presets
@@ -117,6 +133,21 @@ brew install yaml-cpp googletest
> **Note:** In sandboxed environments, install yaml-cpp and googletest via Homebrew to avoid network fetch failures. The build system auto-detects Homebrew installations at `/opt/homebrew/opt/` (Apple Silicon) or `/usr/local/opt/` (Intel).
#### Toolchain Options (macOS)
AppleClang (`/usr/bin/clang`) is the default and most reliable. If you want Homebrew LLVM, use the provided toolchain file so libc++ headers and rpaths are consistent:
```bash
# AppleClang (recommended)
cmake --preset mac-dbg --fresh -DCMAKE_C_COMPILER=/usr/bin/clang -DCMAKE_CXX_COMPILER=/usr/bin/clang++
# Homebrew LLVM
brew install llvm
cmake --preset mac-dbg --fresh -DCMAKE_TOOLCHAIN_FILE=cmake/llvm-brew.toolchain.cmake
```
`mac-ai-fast` expects Homebrew gRPC/protobuf/abseil (`brew install grpc protobuf abseil`).
### Linux (Ubuntu/Debian)
```bash
@@ -152,13 +183,13 @@ 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
cmake --preset mac-dev -DYAZE_TEST_ROM_VANILLA_PATH="$PWD/roms/alttp_vanilla.sfc"
# Build the tests
cmake --build --preset mac-dev --target yaze_test
# Run stable tests (fast, run in CI)
ctest --preset dev
ctest --preset stable
# Run all tests, including ROM-dependent and experimental
ctest --preset all
@@ -169,8 +200,11 @@ ctest --preset all
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 tests via the executables (multi-config paths on macOS/Windows)
./build/bin/Debug/yaze_emu_test --emu_test_rom=roms/alttp_vanilla.sfc
./build/bin/Debug/yaze_test_stable --rom=roms/alttp_vanilla.sfc
./build/bin/Debug/yaze_test_gui --rom=roms/alttp_vanilla.sfc
./build/bin/Debug/yaze_test_benchmark --rom=roms/alttp_vanilla.sfc
# Run only stable tests using CTest labels
ctest --test-dir build --label-regex "STABLE"
@@ -329,10 +363,10 @@ After pulling major changes or switching branches, your build directory can beco
### 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.
**Cause**: You are building code that requires AI features without using an AI-enabled preset, or CMake has not fetched CPM dependencies yet.
**Solution**:
1. Use an AI preset like `win-ai` or `mac-ai`.
2. Ensure submodules are present by running `git submodule update --init --recursive`.
2. Reconfigure to fetch dependencies: `cmake --preset <preset>` (or delete the build folder and re-run).
#### "Cannot open file 'yaze.exe': Permission denied"
**Cause**: A previous instance of `yaze.exe` is still running in the background.

145
docs/public/build/presets.md
View File

@@ -49,45 +49,82 @@ cmake --build --preset win-arm
### 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 |
| Preset | Description | Arch | Warnings | Notes |
|--------|-------------|------|----------|-------|
| `mac-dbg` | Debug build | Host | Off | Tests enabled |
| `mac-dbg-v` | Debug build (verbose) | Host | On | Extra warnings |
| `mac-rel` | Release build | Host | Off | LTO enabled |
| `mac-dev` | Development build | Host | Off | ROM tests enabled |
| `mac-ai` | AI + gRPC dev | Host | Off | Agent UI + automation |
| `mac-ai-fast` | AI dev (system gRPC) | Host | Off | `brew install grpc protobuf abseil` |
| `mac-uni` | Universal binary | arm64 + x86_64 | Off | Release packaging |
| `mac-sdl3` | SDL3 build | Host | Off | Experimental |
| `mac-test` | Fast test build | Host | Off | RelWithDebInfo |
### 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 |
| Preset | Description | Arch | Generator | Notes |
|--------|-------------|------|-----------|-------|
| `win-dbg` | Debug build | x64 | Ninja | Tests enabled |
| `win-dbg-v` | Debug build (verbose) | x64 | Ninja | Extra warnings |
| `win-rel` | Release build | x64 | Ninja | LTO enabled |
| `win-dev` | Development build | x64 | Ninja | ROM tests enabled |
| `win-ai` | AI + gRPC dev | x64 | Ninja | Agent UI + automation |
| `win-z3ed` | z3ed CLI | x64 | Ninja | CLI stack only |
| `win-arm` | Debug ARM64 | ARM64 | Ninja | |
| `win-arm-rel` | Release ARM64 | ARM64 | Ninja | |
| `win-vs-dbg` | Debug build | x64 | Visual Studio | |
| `win-vs-rel` | Release build | x64 | Visual Studio | |
| `win-vs-ai` | AI + gRPC dev | x64 | Visual Studio | |
| `win-sdl3` | SDL3 build | x64 | Ninja | Experimental |
| `win-test` | Fast test build | x64 | Ninja | RelWithDebInfo |
### Linux Presets
| Preset | Description | Compiler | Warnings |
|--------|-------------|----------|----------|
| `lin-dbg` | Debug | GCC | Off |
| `lin-clang` | Debug | Clang | Off |
| Preset | Description | Compiler | Notes |
|--------|-------------|----------|-------|
| `lin-dbg` | Debug build | GCC/Clang | Tests enabled |
| `lin-dbg-v` | Debug build (verbose) | GCC/Clang | Extra warnings |
| `lin-rel` | Release build | GCC/Clang | LTO enabled |
| `lin-dev` | Development build | GCC/Clang | ROM tests enabled |
| `lin-ai` | AI + gRPC dev | GCC/Clang | Agent UI + automation |
| `lin-sdl3` | SDL3 build | GCC/Clang | Experimental |
| `lin-test` | Fast test build | GCC/Clang | RelWithDebInfo |
### Special Purpose
### CI Presets
| Preset | Description |
|--------|-------------|
| `ci` | Continuous integration (no ROM tests) |
| `asan` | AddressSanitizer build |
| `coverage` | Code coverage build |
| `ci-linux` | Linux CI build |
| `ci-macos` | macOS CI build |
| `ci-windows` | Windows CI build |
| `ci-windows-ai` | Windows AI/automation CI build |
### WASM Presets
| Preset | Description |
|--------|-------------|
| `wasm-debug` | WebAssembly debug build |
| `wasm-release` | WebAssembly release build |
| `wasm-crash-repro` | Minimal repro build |
| `wasm-ai` | WebAssembly AI build |
### Test Presets
Run with `ctest --preset <name>`.
| Preset | Description |
|--------|-------------|
| `all` | All tests (including ROM-dependent) |
| `stable` | Stable tests only |
| `unit` | Unit tests only |
| `integration` | Integration tests only |
| `fast` | macOS fast test preset |
| `fast-win` | Windows fast test preset |
| `fast-lin` | Linux fast test preset |
| `stable-ai` | Stable tests against `ci-windows-ai` |
| `unit-ai` | Unit tests against `ci-windows-ai` |
| `integration-ai` | Integration tests against `ci-windows-ai` |
## Warning Control
@@ -104,9 +141,9 @@ By default, all presets suppress compiler warnings with `-w` for a cleaner build
## 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)
- **Apple Silicon (arm64)**: `mac-dbg`, `mac-rel`, `mac-ai`, `mac-dev`, etc.
- **Intel (x86_64)**: Use the same `mac-*` presets (they target the host arch).
- **Universal Binary**: `mac-uni` (arm64 + x86_64)
### Windows
- **x64**: `win-dbg`, `win-rel`, `win-ai`, etc.
@@ -114,7 +151,19 @@ By default, all presets suppress compiler warnings with `-w` for a cleaner build
## Build Directories
Most presets use `build/`. WASM presets use `build-wasm/`. Use `CMakeUserPresets.json` for custom directories.
Most presets use `build/`. WASM presets use `build-wasm/`. Keep only these two build directories in the repo to avoid bloat. For isolated agent builds, point `binaryDir` to a path outside the repo via `CMakeUserPresets.json`.
### Shared Dependency Caches
To avoid re-downloading dependencies after cleaning build dirs, set shared caches via `CMakeUserPresets.json` (see `CMakeUserPresets.json.example`) or environment variables:
```bash
export CPM_SOURCE_CACHE="$HOME/.cpm-cache"
export VCPKG_DOWNLOADS="$HOME/.cache/vcpkg/downloads"
export VCPKG_BINARY_SOURCES="clear;files,$HOME/.cache/vcpkg/bincache,readwrite"
```
For scripts and the agent build tool, you can also set `YAZE_BUILD_DIR` to an external path (e.g., `$HOME/.cache/yaze/build`) to keep the working tree clean.
## Feature Flags
@@ -123,28 +172,29 @@ 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
-DYAZE_BUILD_AGENT_UI=ON/OFF
# AI features
-DZ3ED_AI=ON/OFF
-DYAZE_WITH_JSON=ON/OFF
-DYAZE_WITH_GRPC=ON/OFF
-DYAZE_ENABLE_AI=ON/OFF
-DYAZE_ENABLE_AI_RUNTIME=ON/OFF
-DYAZE_ENABLE_GRPC=ON/OFF
-DYAZE_PREFER_SYSTEM_GRPC=ON/OFF
-DYAZE_ENABLE_JSON=ON/OFF
-DYAZE_ENABLE_REMOTE_AUTOMATION=ON/OFF
# Testing
-DYAZE_ENABLE_ROM_TESTS=ON/OFF
-DYAZE_TEST_ROM_PATH=/path/to/zelda3.sfc
# Build optimization
-DYAZE_MINIMAL_BUILD=ON/OFF
-DYAZE_TEST_ROM_VANILLA_PATH=/path/to/alttp_vanilla.sfc
-DYAZE_TEST_ROM_EXPANDED_PATH=/path/to/oos168.sfc
-DYAZE_USE_SDL3=ON/OFF
-DYAZE_ENABLE_LTO=ON/OFF
```
## Examples
### Development with AI features and verbose warnings
```bash
cmake --preset mac-dbg-v -DZ3ED_AI=ON -DYAZE_WITH_GRPC=ON
cmake --preset mac-dbg-v -DYAZE_ENABLE_AI=ON -DYAZE_ENABLE_GRPC=ON -DYAZE_BUILD_AGENT_UI=ON
cmake --build --preset mac-dbg-v
```
@@ -157,7 +207,7 @@ cpack --preset mac-uni
### Quick minimal build for testing
```bash
cmake --preset mac-dbg -DYAZE_MINIMAL_BUILD=ON
cmake --preset mac-dbg -DYAZE_ENABLE_AI=OFF -DYAZE_ENABLE_GRPC=OFF -DYAZE_BUILD_AGENT_UI=OFF
cmake --build --preset mac-dbg -j12
```
@@ -181,12 +231,10 @@ Old preset names have been simplified:
| `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
@@ -201,5 +249,6 @@ Old preset names have been simplified:
- Restart your IDE or LSP server
### Build fails with missing dependencies
- Ensure submodules are initialized: `git submodule update --init --recursive`
- Re-run configure to fetch CPM dependencies: `cmake --preset <your-preset>`
- If offline, set `CPM_SOURCE_CACHE` to a populated cache directory
- For AI features, make sure you have OpenSSL: `brew install openssl` (macOS)

79
docs/public/build/quick-reference.md
View File

@@ -27,23 +27,33 @@ Run the verification script once per machine to check dependencies and fix commo
.\scripts\verify-build-environment.ps1 -FixIssues
```
### macOS Toolchain Selection
AppleClang (`/usr/bin/clang`) is the default and most reliable choice. If Homebrew LLVM is on your PATH and you hit SDK header errors, pick the toolchain explicitly:
```bash
# AppleClang (recommended)
cmake --preset mac-dbg --fresh -DCMAKE_C_COMPILER=/usr/bin/clang -DCMAKE_CXX_COMPILER=/usr/bin/clang++
# Homebrew LLVM (optional)
cmake --preset mac-dbg --fresh -DCMAKE_TOOLCHAIN_FILE=cmake/llvm-brew.toolchain.cmake
```
---
## 2. Build Presets
YAZE uses CMake presets for consistent builds. Configure with `cmake --preset <name>`, then build with `cmake --build --preset <name>`.
### Available Presets
### Available Presets (High Level)
| Preset | Platform | Description |
|--------|----------|-------------|
| `mac-dbg`, `lin-dbg`, `win-dbg` | macOS / Linux / Windows | Standard debug builds with tests enabled |
| `mac-ai`, `lin-ai`, `win-ai` | macOS / Linux / Windows | Full AI stack: gRPC, agent UI, z3ed CLI, 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 |
| `mac-uni` | macOS | Universal binary (ARM64 + x86_64) for distribution |
| `mac-test`, `lin-test`, `win-test` | All | Optimized builds for fast test iteration |
| `ci-*` | Platform-specific | CI/CD configurations (see CMakePresets.json) |
- **macOS**: `mac-dbg`, `mac-dbg-v`, `mac-rel`, `mac-dev`, `mac-ai`, `mac-ai-fast`, `mac-uni`, `mac-sdl3`, `mac-test`
- **Windows**: `win-dbg`, `win-dbg-v`, `win-rel`, `win-dev`, `win-ai`, `win-z3ed`, `win-arm`, `win-arm-rel`, `win-vs-dbg`, `win-vs-rel`, `win-vs-ai`, `win-sdl3`, `win-test`
- **Linux**: `lin-dbg`, `lin-dbg-v`, `lin-rel`, `lin-dev`, `lin-ai`, `lin-sdl3`, `lin-test`
- **CI**: `ci-linux`, `ci-macos`, `ci-windows`, `ci-windows-ai`
- **WASM**: `wasm-debug`, `wasm-release`, `wasm-crash-repro`, `wasm-ai`
`mac-ai-fast` prefers the Homebrew gRPC/protobuf stack for faster configure times (`brew install grpc protobuf abseil`).
**Tip:** Add `-v` suffix (e.g., `mac-dbg-v`) to enable verbose compiler warnings.
@@ -56,7 +66,9 @@ YAZE uses CMake presets for consistent builds. Configure with `cmake --preset <n
| Native (desktop/CLI) | `build/` |
| WASM | `build-wasm/` |
If you need per-user or per-agent isolation, create a local `CMakeUserPresets.json` that points `binaryDir` to a custom path.
macOS and Windows presets use multi-config generators, so binaries live under `build/bin/Debug` or `build/bin/Release`. Linux uses single-config builds in `build/bin`.
If you need per-user or per-agent isolation, create a local `CMakeUserPresets.json` that points `binaryDir` to a custom path outside the repo. Avoid creating additional `build_*` folders in the repo to keep the checkout small.
Example:
```bash
@@ -66,11 +78,37 @@ cmake --preset dev-local
cmake --build --preset dev-local --target yaze
```
You can also set `YAZE_BUILD_DIR` for scripts and the agent build tool to direct builds to an external path:
```bash
export YAZE_BUILD_DIR="$HOME/.cache/yaze/build"
```
For AI-enabled builds, use the `*-ai` presets and specify only the targets you need:
```bash
cmake --build --preset mac-ai --target yaze z3ed
```
### Shared Dependency Caches (Recommended)
Set shared caches once per machine to avoid re-downloading dependencies after
cleaning build directories.
**macOS / Linux:**
```bash
export CPM_SOURCE_CACHE="$HOME/.cpm-cache"
export VCPKG_DOWNLOADS="$HOME/.cache/vcpkg/downloads"
export VCPKG_BINARY_SOURCES="clear;files,$HOME/.cache/vcpkg/bincache,readwrite"
```
**Windows (PowerShell):**
```powershell
$env:CPM_SOURCE_CACHE = "$env:USERPROFILE\.cpm-cache"
$env:VCPKG_DOWNLOADS = "$env:LOCALAPPDATA\vcpkg\downloads"
$env:VCPKG_BINARY_SOURCES = "clear;files,$env:LOCALAPPDATA\vcpkg\bincache,readwrite"
```
You can also set these in `CMakeUserPresets.json` (see `CMakeUserPresets.json.example`).
**Windows Helper Scripts:**
- Quick builds: `scripts/agents/windows-smoke-build.ps1`
- Test runs: `scripts/agents/run-tests.sh` (or PowerShell equivalent)
@@ -138,6 +176,19 @@ ctest --test-dir build --output-on-failure
ctest --test-dir build -R "Dungeon"
```
### Direct Test Binaries
```bash
# macOS/Windows (multi-config)
./build/bin/Debug/yaze_emu_test --emu_test_rom=roms/alttp_vanilla.sfc
./build/bin/Debug/yaze_test_stable --rom=roms/alttp_vanilla.sfc
./build/bin/Debug/yaze_test_gui --rom=roms/alttp_vanilla.sfc
./build/bin/Debug/yaze_test_benchmark --rom=roms/alttp_vanilla.sfc
# Linux (single-config)
./build/bin/yaze_emu_test --emu_test_rom=roms/alttp_vanilla.sfc
```
### Test Categories
| Category | Command | Description |
@@ -151,7 +202,7 @@ ctest --test-dir build -R "Dungeon"
```bash
# Configure with ROM path
cmake --preset mac-dev -DYAZE_TEST_ROM_PATH=/path/to/zelda3.sfc
cmake --preset mac-dev -DYAZE_TEST_ROM_VANILLA_PATH="$PWD/roms/alttp_vanilla.sfc"
# Build and run
cmake --build --preset mac-dev --target yaze_test
@@ -171,7 +222,9 @@ ctest --test-dir build -L rom_dependent
| Variable | Purpose |
|----------|---------|
| `YAZE_TEST_ROM_PATH` | Path to ROM for ROM-dependent tests |
| `YAZE_TEST_ROM_VANILLA` | Path to vanilla ROM for ROM-dependent tests |
| `YAZE_TEST_ROM_EXPANDED` | Path to expanded (ZSCustom/OOS) ROM |
| `YAZE_TEST_ROM_PATH` | Legacy ROM path (vanilla fallback) |
| `YAZE_SKIP_ROM_TESTS` | Skip ROM tests (useful for CI) |
| `YAZE_ENABLE_UI_TESTS` | Enable GUI tests (auto-detected if display available) |

143
docs/public/build/troubleshooting.md
View File

@@ -1,12 +1,13 @@
# YAZE Build Troubleshooting Guide
**Last Updated**: October 2025
**Related Docs**: BUILD-GUIDE.md, ci-cd/CI-SETUP.md
**Last Updated**: December 2025
**Related Docs**: quick-reference.md, build-from-source.md, presets.md
## Table of Contents
- [gRPC ARM64 Issues](#grpc-arm64-issues)
- [Windows Build Issues](#windows-build-issues)
- [macOS Issues](#macos-issues)
- [Disk Usage and Build Directory Bloat](#disk-usage-and-build-directory-bloat)
- [Linux Issues](#linux-issues)
- [Common Build Errors](#common-build-errors)
@@ -14,127 +15,43 @@
## gRPC ARM64 Issues
### Status: Known Issue with Workarounds
### Preferred Path: System gRPC on macOS
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.
On Apple Silicon, the fastest and most reliable setup is Homebrew's gRPC stack:
### 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
cmake --preset mac-ai-fast
```
### Environment Configuration
You can also force it in any preset with `-DYAZE_PREFER_SYSTEM_GRPC=ON`.
**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++)
### If You Must Build gRPC From Source
### Build Commands for Testing
When building gRPC/Abseil from source on ARM64, x86-only SSE flags can still surface. If you see errors like:
```
clang++: error: unsupported option '-msse4.1' for target 'arm64-apple-darwin...'
```
switch to system gRPC (`YAZE_PREFER_SYSTEM_GRPC=ON`) or disable gRPC for that build:
```bash
# Clean build
rm -rf build/_deps/grpc-build
# Test configuration
cmake --preset mac-dbg
# Test build
cmake --build --preset mac-dbg --target protoc
cmake --preset mac-dbg -DYAZE_ENABLE_GRPC=OFF
```
### Success Criteria
### Toolchain Consistency (AppleClang vs Homebrew LLVM)
If Homebrew LLVM is on your PATH, SDK headers can be picked up in the wrong order and cause missing type errors. Either:
The build succeeds when:
```bash
cmake --build --preset mac-dbg --target protoc
# Returns exit code 0 (no SSE flag errors)
# Force AppleClang
cmake --preset mac-dbg --fresh -DCMAKE_C_COMPILER=/usr/bin/clang -DCMAKE_CXX_COMPILER=/usr/bin/clang++
# Or use the Homebrew LLVM toolchain file
cmake --preset mac-dbg --fresh -DCMAKE_TOOLCHAIN_FILE=cmake/llvm-brew.toolchain.cmake
```
### 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
@@ -282,6 +199,18 @@ sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
---
## Disk Usage and Build Directory Bloat
If the repository grows unexpectedly large, check for extra build directories in the repo root. The supported in-repo directories are `build/` and `build-wasm/`. Move any additional builds to an external path via `CMakeUserPresets.json` or `YAZE_BUILD_DIR`, then delete the old folders:
```bash
rm -rf build_agent build_agent_llvm build_agent_ninja build_gemini
```
Keeping CPM/vcpkg caches in `~/.cache` or `~/.cpm-cache` prevents re-downloading after cleanups.
---
## Linux Issues
### Missing Dependencies