From 63c2098a21a728c39cb4dfc08b449c10f0d583db Mon Sep 17 00:00:00 2001 From: scawful Date: Fri, 17 Oct 2025 12:10:25 -0400 Subject: [PATCH] chore: update gRPC version and compatibility notes - Upgraded gRPC from v1.67.1 to v1.75.1 for improved Windows compatibility. - Disabled BoringSSL ASM optimizations for better clang-cl support. - Updated documentation to reflect changes in build times and reasons for using FetchContent over vcpkg for gRPC. --- cmake/grpc.cmake | 13 +++-- cmake/grpc_windows.cmake | 3 +- docs/B1-build-instructions.md | 96 +++++++++++++++++-------------- docs/B2-platform-compatibility.md | 38 ++++++++---- 4 files changed, 88 insertions(+), 62 deletions(-) diff --git a/cmake/grpc.cmake b/cmake/grpc.cmake index 4db9865e..3d6cf611 100644 --- a/cmake/grpc.cmake +++ b/cmake/grpc.cmake @@ -118,12 +118,15 @@ endif() # Declare gRPC with platform-specific versions # - macOS/Linux: v1.75.1 (has ARM64 + modern Clang fixes) -# - Windows MSVC: v1.67.1 (proven stable with MSVC, fewer UPB issues) -if(WIN32 AND MSVC) - set(_GRPC_VERSION "v1.67.1") - set(_GRPC_VERSION_REASON "MSVC-compatible, avoids UPB compilation errors") +# - Windows: v1.75.1 (better NASM/clang-cl support than v1.67.1) +set(_GRPC_VERSION "v1.75.1") +if(WIN32) + set(_GRPC_VERSION_REASON "Windows clang-cl + MSVC compatibility") + # Disable BoringSSL ASM to avoid NASM build issues on Windows + # ASM optimizations cause NASM flag conflicts with clang-cl + set(OPENSSL_NO_ASM ON CACHE BOOL "" FORCE) + message(STATUS "Disabling BoringSSL ASM optimizations for Windows build compatibility") else() - set(_GRPC_VERSION "v1.75.1") set(_GRPC_VERSION_REASON "ARM64 macOS + modern Clang compatibility") endif() diff --git a/cmake/grpc_windows.cmake b/cmake/grpc_windows.cmake index 9da4992c..9d053d5d 100644 --- a/cmake/grpc_windows.cmake +++ b/cmake/grpc_windows.cmake @@ -242,7 +242,8 @@ if(WIN32 AND YAZE_USE_VCPKG_GRPC) message(STATUS " vcpkg gRPC not found (expected if removed from vcpkg.json)") message(STATUS " Using FetchContent build (faster with caching)") message(STATUS " First build: ~10-15 min, subsequent: <1 min (cached)") - message(STATUS " Using gRPC v1.67.1 for Windows compatibility") + message(STATUS " Using gRPC v1.75.1 with Windows compatibility fixes") + message(STATUS " Note: BoringSSL ASM disabled for clang-cl compatibility") message(STATUS "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━") endif() endif() diff --git a/docs/B1-build-instructions.md b/docs/B1-build-instructions.md index 9eec8c75..34acfa78 100644 --- a/docs/B1-build-instructions.md +++ b/docs/B1-build-instructions.md @@ -164,61 +164,69 @@ open build/yaze.xcodeproj ## 7. Windows Build Optimization -### gRPC v1.67.1 and MSVC Compatibility +### GitHub Actions / CI Builds -**Recent Update (October 2025):** The project has been upgraded to gRPC v1.67.1 which includes critical MSVC template fixes. This version resolves previous template instantiation errors that occurred with v1.62.0. +**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.67.1) - cached after first build +- **Caching**: Aggressive multi-tier caching (vcpkg + FetchContent + sccache) +- **Expected time**: + - First build: ~10-15 minutes + - Cached build: ~3-5 minutes -**MSVC-Specific Compiler Flags:** -The build system now automatically applies these flags for Windows builds: -- `/bigobj` - Allows large object files (gRPC generates many symbols) -- `/permissive-` - Enables standards conformance mode -- `/wd4267 /wd4244` - Suppresses harmless conversion warnings -- `/constexpr:depth2048` - Handles deep template instantiations (MSVC 2019+) +**Why Not vcpkg for gRPC?** +- 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 with Windows fixes) +- BoringSSL ASM disabled on Windows for clang-cl compatibility +- zlib conflict: gRPC's FetchContent builds its own zlib, conflicts with vcpkg's -### The Problem: Slow gRPC Builds -Building with gRPC on Windows (`-DYAZE_WITH_GRPC=ON`) can take **15-20 minutes** the first time, as it compiles gRPC v1.67.1 and its dependencies from source. +### Local Development -### Solution A: Use vcpkg for Pre-compiled Binaries (Recommended - FAST) +#### Fast Build (Recommended) -Using `vcpkg` to manage gRPC is the recommended approach for Windows developers who need GUI automation features. - -**Step 1: Install vcpkg and Dependencies** +Use FetchContent for all dependencies (matches CI): ```powershell -# This only needs to be done once -# Use the setup script for convenience: -.\scripts\setup-vcpkg-windows.ps1 - -# Or manually: -vcpkg install grpc:x64-windows protobuf:x64-windows abseil:x64-windows -``` - -**Step 2: Configure CMake to Use vcpkg** -Pass the `vcpkg.cmake` toolchain file to your configure command. - -```powershell -# Configure a build that uses vcpkg for gRPC -cmake -B build -G "Visual Studio 17 2022" -A x64 ` - -DCMAKE_TOOLCHAIN_FILE="vcpkg/scripts/buildsystems/vcpkg.cmake" - -# Build (will now be much faster: 5-10 minutes) -cmake --build build --config RelWithDebInfo --parallel -``` - -**Build Time:** ~5-10 minutes (uses pre-compiled gRPC) - -### Solution B: FetchContent Build (Slow but Automatic) - -If you don't want to use vcpkg, CMake will automatically download and build gRPC from source. - -```powershell -# Configure (will download and build gRPC v1.67.1 from source) +# Configure (first time: ~15 min, subsequent: ~2 min) cmake -B build -G "Visual Studio 17 2022" -A x64 -# Build (first time: ~45-60 minutes, subsequent: ~2-5 minutes) +# Build cmake --build build --config RelWithDebInfo --parallel ``` -**Build Time:** ~45-60 minutes first time, ~2-5 minutes subsequent builds (gRPC cached) +#### 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 diff --git a/docs/B2-platform-compatibility.md b/docs/B2-platform-compatibility.md index fc497c40..bccf685f 100644 --- a/docs/B2-platform-compatibility.md +++ b/docs/B2-platform-compatibility.md @@ -9,26 +9,40 @@ ### Windows **Build System:** -- Uses vcpkg for: SDL2, yaml-cpp, zlib (fast, pre-compiled) -- Uses FetchContent for: gRPC v1.67.1, abseil, protobuf (slower first time) +- 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) -**MSVC Flags Applied:** -- `/bigobj` - Support large object files -- `/permissive-` - Standards conformance -- `/wd4267 /wd4244` - Suppress conversion warnings -- `/constexpr:depth2048` - Deep template instantiation +**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 with Windows compatibility fixes +- 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 with - Windows SDK headers +- `__PRFCHWINTRIN_H` - Work around Clang 20 `_m_prefetchw` linkage clash **Build Times:** -- First build with FetchContent: ~45-60 minutes (compiles gRPC) -- Subsequent builds: ~2-5 minutes -- With vcpkg pre-compiled gRPC: ~5-10 minutes first time +- 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