From 405b542e9827ae557a255283163f764c83eff603 Mon Sep 17 00:00:00 2001 From: scawful Date: Thu, 20 Nov 2025 00:12:08 -0500 Subject: [PATCH] build: add Homebrew fallback for googletest in sandboxed environments Adds automatic detection of Homebrew-installed googletest to support offline/sandboxed builds (e.g., Claude Code, restricted networks). Changes: - Add Homebrew detection logic to cmake/dependencies/testing.cmake - Check /opt/homebrew/opt/googletest and /usr/local/opt/googletest - Use brew --prefix googletest for dynamic detection - Create target aliases (gtest -> GTest::gtest) for compatibility - Only fetch from GitHub if no local installation found - Update macOS build docs with yaml-cpp and googletest installation Pattern mirrors existing yaml.cmake implementation. Complements the pre-existing yaml-cpp Homebrew fallback to minimize network dependencies. Tested with: brew install googletest (1.17.0, 2.4MB) Co-Authored-By: Claude --- cmake/dependencies/testing.cmake | 91 ++++++++++++++++++++++---- docs/public/build/build-from-source.md | 78 ++++++++-------------- 2 files changed, 107 insertions(+), 62 deletions(-) diff --git a/cmake/dependencies/testing.cmake b/cmake/dependencies/testing.cmake index 497cbfd6..fd62734f 100644 --- a/cmake/dependencies/testing.cmake +++ b/cmake/dependencies/testing.cmake @@ -10,17 +10,86 @@ include(cmake/dependencies.lock) message(STATUS "Setting up testing dependencies with CPM.cmake") -# Google Test (includes GMock) -CPMAddPackage( - NAME googletest - VERSION ${GTEST_VERSION} - GITHUB_REPOSITORY google/googletest - GIT_TAG v${GTEST_VERSION} - OPTIONS - "BUILD_GMOCK ON" - "INSTALL_GTEST OFF" - "gtest_force_shared_crt ON" -) +set(_YAZE_USE_SYSTEM_GTEST ${YAZE_USE_SYSTEM_DEPS}) + +# Detect Homebrew installation automatically (helps offline builds) +if(APPLE AND NOT _YAZE_USE_SYSTEM_GTEST) + set(_YAZE_GTEST_PREFIX_CANDIDATES + /opt/homebrew/opt/googletest + /usr/local/opt/googletest) + + foreach(_prefix IN LISTS _YAZE_GTEST_PREFIX_CANDIDATES) + if(EXISTS "${_prefix}") + list(APPEND CMAKE_PREFIX_PATH "${_prefix}") + message(STATUS "Added Homebrew googletest prefix: ${_prefix}") + set(_YAZE_USE_SYSTEM_GTEST ON) + break() + endif() + endforeach() + + if(NOT _YAZE_USE_SYSTEM_GTEST) + find_program(HOMEBREW_EXECUTABLE brew) + if(HOMEBREW_EXECUTABLE) + execute_process( + COMMAND "${HOMEBREW_EXECUTABLE}" --prefix googletest + OUTPUT_VARIABLE HOMEBREW_GTEST_PREFIX + OUTPUT_STRIP_TRAILING_WHITESPACE + RESULT_VARIABLE HOMEBREW_GTEST_RESULT + ERROR_QUIET) + if(HOMEBREW_GTEST_RESULT EQUAL 0 AND EXISTS "${HOMEBREW_GTEST_PREFIX}") + list(APPEND CMAKE_PREFIX_PATH "${HOMEBREW_GTEST_PREFIX}") + message(STATUS "Added Homebrew googletest prefix: ${HOMEBREW_GTEST_PREFIX}") + set(_YAZE_USE_SYSTEM_GTEST ON) + endif() + endif() + endif() +endif() + +# Try to use system packages first +if(_YAZE_USE_SYSTEM_GTEST) + find_package(GTest QUIET) + if(GTest_FOUND) + message(STATUS "Using system googletest") + # GTest found, targets should already be available + # Verify targets exist + if(NOT TARGET GTest::gtest) + message(WARNING "GTest::gtest target not found despite GTest_FOUND=TRUE; falling back to CPM download") + set(_YAZE_USE_SYSTEM_GTEST OFF) + else() + # Create aliases to match CPM target names + if(NOT TARGET gtest) + add_library(gtest ALIAS GTest::gtest) + endif() + if(NOT TARGET gtest_main) + add_library(gtest_main ALIAS GTest::gtest_main) + endif() + if(TARGET GTest::gmock AND NOT TARGET gmock) + add_library(gmock ALIAS GTest::gmock) + endif() + if(TARGET GTest::gmock_main AND NOT TARGET gmock_main) + add_library(gmock_main ALIAS GTest::gmock_main) + endif() + # Skip CPM fetch + set(_YAZE_GTEST_SYSTEM_USED ON) + endif() + elseif(YAZE_USE_SYSTEM_DEPS) + message(WARNING "System googletest not found despite YAZE_USE_SYSTEM_DEPS=ON; falling back to CPM download") + endif() +endif() + +# Use CPM to fetch googletest if not using system version +if(NOT _YAZE_GTEST_SYSTEM_USED) + CPMAddPackage( + NAME googletest + VERSION ${GTEST_VERSION} + GITHUB_REPOSITORY google/googletest + GIT_TAG v${GTEST_VERSION} + OPTIONS + "BUILD_GMOCK ON" + "INSTALL_GTEST OFF" + "gtest_force_shared_crt ON" + ) +endif() # Verify GTest and GMock targets are available if(NOT TARGET gtest) diff --git a/docs/public/build/build-from-source.md b/docs/public/build/build-from-source.md index cdd3a542..93ecf9bc 100644 --- a/docs/public/build/build-from-source.md +++ b/docs/public/build/build-from-source.md @@ -1,6 +1,8 @@ # Build Instructions -yaze uses a modern CMake build system with presets for easy configuration. This guide covers how to build yaze on macOS, Linux, and Windows. +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 @@ -25,52 +27,14 @@ yaze uses a modern CMake build system with presets for easy configuration. This The script checks for required tools like CMake, a C++23 compiler, and platform-specific dependencies. -## 2. Quick Start: Building with Presets +## 2. Using Presets -We use CMake Presets for simple, one-command builds. See the [CMake Presets Guide](presets.md) for a full list. - -### macOS -```bash -# Configure a debug build (Apple Silicon) -cmake --preset mac-dbg - -# Build the project -cmake --build --preset mac-dbg -``` - -### Linux -```bash -# Configure a debug build -cmake --preset lin-dbg - -# Build the project -cmake --build --preset lin-dbg -``` - -### Windows -```bash -# Configure a debug build for Visual Studio (x64) -cmake --preset win-dbg - -# Build the project -cmake --build --preset win-dbg - -# Enable the full AI/gRPC stack -cmake --preset win-ai -cmake --build --preset win-ai -``` - -### AI-Enabled Build (All Platforms) -To build with the `z3ed` AI agent features: -```bash -# macOS -cmake --preset mac-ai -cmake --build --preset mac-ai - -# Windows -cmake --preset win-ai -cmake --build --preset win-ai -``` +- 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 ` and build with `cmake --build --preset [--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 @@ -110,8 +74,15 @@ 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 @@ -120,10 +91,15 @@ sudo apt-get install -y build-essential cmake ninja-build pkg-config \ ``` ### Windows -- **Visual Studio 2022** is required, with the "Desktop development with C++" workload. -- The updated `verify-build-environment.ps1` script checks clang-cl, Ninja, vcpkg caches, and ROM assets. -- Run `.\scripts\setup-vcpkg-windows.ps1` once per machine to bootstrap vcpkg and prefetch SDL2/yaml-cpp. -- For building with gRPC, see the "Windows Build Optimization" section below. +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 @@ -170,7 +146,7 @@ ctest --test-dir build --label-exclude "ROM_DEPENDENT" ### 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`). +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.