yaze/docs/public/build/platform-compatibility.md

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:

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

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

cmake -B build

Linux: CMake configuration fails

Cause: Missing system dependencies
Fix: Install required packages

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)

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

# 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.