yaze 0.3.2
Link to the Past ROM Editor
 
Loading...
Searching...
No Matches
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 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

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