scawful/yaze
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
42ae359abc2ee416fad56574af50cbde120be8a1
yaze/docs/internal/architecture/configuration_matrix.md

12 KiB
Raw Blame History

Configuration Matrix Documentation

This document defines all CMake configuration flags, their interactions, and the tested configuration combinations for the yaze project.

Last Updated: 2025-11-20 Owner: CLAUDE_MATRIX_TEST (Platform Matrix Testing Specialist)

1. CMake Configuration Flags

Core Build Options

Flag Default Purpose Notes
YAZE_BUILD_GUI ON Build GUI application (ImGui-based editor) Required for desktop users
YAZE_BUILD_CLI ON Build CLI tools (shared libraries) Needed for z3ed CLI
YAZE_BUILD_Z3ED ON Build z3ed CLI executable Requires YAZE_BUILD_CLI=ON
YAZE_BUILD_EMU ON Build emulator components Optional; adds ~50MB to binary
YAZE_BUILD_LIB ON Build static library (libyaze.a) For library consumers
YAZE_BUILD_TESTS ON Build test suite Required for CI validation

Feature Flags

Flag Default Purpose Dependencies
YAZE_ENABLE_GRPC ON Enable gRPC agent support Requires protobuf, gRPC libraries
YAZE_ENABLE_JSON ON Enable JSON support (nlohmann) Used by AI services
YAZE_ENABLE_AI ON Enable AI agent features (legacy) Deprecated: use YAZE_ENABLE_AI_RUNTIME
YAZE_ENABLE_REMOTE_AUTOMATION depends on YAZE_ENABLE_GRPC Enable remote GUI automation (gRPC servers) Requires YAZE_ENABLE_GRPC=ON
YAZE_ENABLE_AI_RUNTIME depends on YAZE_ENABLE_AI Enable AI runtime (Gemini/Ollama, advanced routing) Requires YAZE_ENABLE_AI=ON
YAZE_BUILD_AGENT_UI depends on YAZE_BUILD_GUI Build ImGui agent/chat panels in GUI Requires YAZE_BUILD_GUI=ON
YAZE_ENABLE_AGENT_CLI depends on YAZE_BUILD_CLI Build conversational agent CLI stack Auto-enabled if YAZE_BUILD_CLI=ON or YAZE_BUILD_Z3ED=ON
YAZE_ENABLE_HTTP_API depends on YAZE_ENABLE_AGENT_CLI Enable HTTP REST API server Requires YAZE_ENABLE_AGENT_CLI=ON

Optimization & Debug Flags

Flag Default Purpose Notes
YAZE_ENABLE_LTO OFF Link-time optimization Increases build time by ~30%
YAZE_ENABLE_SANITIZERS OFF AddressSanitizer/UBSanitizer For memory safety debugging
YAZE_ENABLE_COVERAGE OFF Code coverage tracking For testing metrics
YAZE_UNITY_BUILD OFF Unity (Jumbo) builds May hide include issues

Development & CI Options

Flag Default Purpose Notes
YAZE_ENABLE_ROM_TESTS OFF Enable ROM-dependent tests Requires zelda3.sfc file
YAZE_MINIMAL_BUILD OFF Minimal CI build (skip optional features) Used in resource-constrained CI
YAZE_SUPPRESS_WARNINGS ON Suppress compiler warnings Use OFF for verbose builds

2. Flag Interactions & Constraints

Automatic Constraint Resolution

The CMake configuration automatically enforces these constraints:

# REMOTE_AUTOMATION forces GRPC
if(YAZE_ENABLE_REMOTE_AUTOMATION AND NOT YAZE_ENABLE_GRPC)
  set(YAZE_ENABLE_GRPC ON CACHE BOOL ... FORCE)
endif()

# Disabling REMOTE_AUTOMATION forces GRPC OFF
if(NOT YAZE_ENABLE_REMOTE_AUTOMATION)
  set(YAZE_ENABLE_GRPC OFF CACHE BOOL ... FORCE)
endif()

# AI_RUNTIME forces AI enabled
if(YAZE_ENABLE_AI_RUNTIME AND NOT YAZE_ENABLE_AI)
  set(YAZE_ENABLE_AI ON CACHE BOOL ... FORCE)
endif()

# Disabling AI_RUNTIME forces AI OFF
if(NOT YAZE_ENABLE_AI_RUNTIME)
  set(YAZE_ENABLE_AI OFF CACHE BOOL ... FORCE)
endif()

# BUILD_CLI or BUILD_Z3ED forces AGENT_CLI ON
if((YAZE_BUILD_CLI OR YAZE_BUILD_Z3ED) AND NOT YAZE_ENABLE_AGENT_CLI)
  set(YAZE_ENABLE_AGENT_CLI ON CACHE BOOL ... FORCE)
endif()

# HTTP_API forces AGENT_CLI ON
if(YAZE_ENABLE_HTTP_API AND NOT YAZE_ENABLE_AGENT_CLI)
  set(YAZE_ENABLE_AGENT_CLI ON CACHE BOOL ... FORCE)
endif()

# AGENT_UI requires BUILD_GUI
if(YAZE_BUILD_AGENT_UI AND NOT YAZE_BUILD_GUI)
  set(YAZE_BUILD_AGENT_UI OFF CACHE BOOL ... FORCE)
endif()

Dependency Graph

YAZE_ENABLE_REMOTE_AUTOMATION
  ├─ Requires: YAZE_ENABLE_GRPC
  └─ Requires: gRPC libraries, protobuf

YAZE_ENABLE_AI_RUNTIME
  ├─ Requires: YAZE_ENABLE_AI
  ├─ Requires: yaml-cpp, OpenSSL
  └─ Requires: Gemini/Ollama HTTP clients

YAZE_BUILD_AGENT_UI
  ├─ Requires: YAZE_BUILD_GUI
  └─ Requires: ImGui bindings

YAZE_ENABLE_AGENT_CLI
  ├─ Requires: YAZE_BUILD_CLI OR YAZE_BUILD_Z3ED
  └─ Requires: ftxui, various CLI handlers

YAZE_ENABLE_HTTP_API
  ├─ Requires: YAZE_ENABLE_AGENT_CLI
  └─ Requires: cpp-httplib

YAZE_ENABLE_JSON
  ├─ Requires: nlohmann_json
  └─ Used by: Gemini AI service, HTTP API

3. Tested Configuration Matrix

Rationale

Testing all 2^N combinations is infeasible (18 flags = 262,144 combinations). Instead, we test:

  1. Baseline: All defaults (realistic user scenario)
  2. Extremes: All ON, All OFF (catch hidden assumptions)
  3. Interactions: Known problematic combinations
  4. CI Presets: Predefined workflows (dev, ci, minimal, release)
  5. Platform-specific: Windows GRPC, macOS universal binary, Linux GCC

Matrix Definition

Tier 1: Core Platform Builds (CI Standard)

These run on every PR and push:

Name Platform GRPC AI AGENT_UI CLI Tests Purpose
ci-linux Linux ON OFF OFF ON ON Server-side agent
ci-macos macOS ON OFF ON ON ON Agent UI + CLI
ci-windows Windows ON OFF OFF ON ON Core Windows build

Tier 2: Feature Combination Tests (Nightly or On-Demand)

These test specific flag combinations:

Name GRPC REMOTE_AUTO JSON AI AI_RUNTIME AGENT_UI HTTP_API Tests
minimal OFF OFF ON OFF OFF OFF OFF ON
grpc-only ON OFF ON OFF OFF OFF OFF ON
full-ai ON ON ON ON ON ON ON ON
cli-only ON ON ON ON ON OFF ON ON
gui-only OFF OFF ON OFF OFF ON OFF ON
http-api ON ON ON ON ON OFF ON ON
no-json ON ON OFF ON OFF OFF OFF ON
all-off OFF OFF OFF OFF OFF OFF OFF ON

Tier 3: Platform-Specific Builds

Name Platform Configuration Special Notes
win-ai Windows Full AI + gRPC CI Windows-specific preset
win-arm Windows ARM64 Debug, no AI ARM64 architecture test
mac-uni macOS Universal binary ARM64 + x86_64
lin-ai Linux Full AI + gRPC Server-side full stack

4. Problematic Combinations

Known Issue Patterns

Pattern A: GRPC Without REMOTE_AUTOMATION

Status: FIXED IN CMAKE Symptom: gRPC headers included but no automation server compiled Why it matters: Causes link errors if server code missing Resolution: REMOTE_AUTOMATION now forces GRPC=ON via CMake constraint

Pattern B: HTTP_API Without AGENT_CLI

Status: FIXED IN CMAKE Symptom: HTTP API endpoints defined but no CLI handler context Why it matters: REST API has no command dispatcher Resolution: HTTP_API now forces AGENT_CLI=ON via CMake constraint

Pattern C: AGENT_UI Without BUILD_GUI

Status: FIXED IN CMAKE Symptom: ImGui panels compiled for headless build Why it matters: Wastes space, may cause UI binding issues Resolution: AGENT_UI now disabled if BUILD_GUI=OFF

Pattern D: AI_RUNTIME Without JSON

Status: TESTING Symptom: Gemini service requires JSON parsing Why it matters: Gemini HTTPS support needs JSON deserialization Resolution: Gemini only linked when both AI_RUNTIME AND JSON enabled

Pattern E: Windows + GRPC + gRPC v1.67.1

Status: DOCUMENTED Symptom: MSVC compatibility issues with older gRPC versions Why it matters: gRPC <1.68.0 has MSVC ABI mismatches Resolution: ci-windows preset pins to tested stable version

Pattern F: macOS ARM64 + Unknown Dependencies

Status: DOCUMENTED Symptom: Homebrew brew dependencies may not have arm64 support Why it matters: Cross-architecture builds fail silently Resolution: mac-uni preset tests both architectures

5. Test Coverage by Configuration

What Each Configuration Validates

Minimal Build

  • Core editor functionality without AI/CLI
  • Smallest binary size
  • Most compatible (no gRPC, no network)
  • Target users: GUI-only, offline users

gRPC Only

  • Server-side agent without AI services
  • GUI automation without language model
  • Useful for: Headless automation

Full AI Stack

  • All features enabled
  • Gemini + Ollama support
  • Advanced routing + proposal planning
  • Target users: AI-assisted ROM hacking

CLI Only

  • z3ed command-line tool
  • No GUI components
  • Server-side focused
  • Target users: Scripting, CI/CD integration

GUI Only

  • Traditional desktop editor
  • No network services
  • Suitable for: Casual players

HTTP API

  • REST endpoints for external tools
  • Integration with other ROM editors
  • JSON-based communication

No JSON

  • Validates JSON is truly optional
  • Tests Ollama-only mode (no Gemini)
  • Smaller binary alternative

All Off

  • Validates minimum viable configuration
  • Basic ROM reading/writing only
  • Edge case handling

6. Running Configuration Matrix Tests

Local Testing

# Run entire local matrix
./scripts/test-config-matrix.sh

# Run specific configuration
./scripts/test-config-matrix.sh --config minimal
./scripts/test-config-matrix.sh --config full-ai

# Smoke test only (no full build)
./scripts/test-config-matrix.sh --smoke

# Verbose output
./scripts/test-config-matrix.sh --verbose

CI Testing

Matrix tests run nightly via .github/workflows/matrix-test.yml:

# Automatic testing of all Tier 2 combinations on all platforms
# Run time: ~45 minutes (parallel execution)
# Triggered: On schedule (2 AM UTC daily) or manual dispatch

Building Specific Preset

# Linux
cmake --preset ci-linux -B build_ci -DYAZE_ENABLE_GRPC=ON
cmake --build build_ci

# Windows
cmake --preset ci-windows -B build_ci
cmake --build build_ci --config RelWithDebInfo

# macOS Universal
cmake --preset mac-uni -B build_uni -DCMAKE_OSX_ARCHITECTURES="arm64;x86_64"
cmake --build build_uni

7. Configuration Dependencies Reference

For Pull Requests

Use this checklist when modifying CMake configuration:

  • Added new option()? Document in Section 1 above
  • New dependency? Document in Section 2 (Dependency Graph)
  • New feature flag? Add to relevant Tier in Section 3
  • Problematic combination? Document in Section 4
  • Update test matrix script if testing approach changes

For Developers

Quick reference when debugging build issues:

  1. gRPC link errors? Check: YAZE_ENABLE_GRPC=ON requires YAZE_ENABLE_REMOTE_AUTOMATION=ON (auto-enforced)
  2. Gemini compile errors? Verify: YAZE_ENABLE_AI_RUNTIME=ON AND YAZE_ENABLE_JSON=ON
  3. Agent UI missing? Check: YAZE_BUILD_GUI=ON AND YAZE_BUILD_AGENT_UI=ON
  4. CLI commands not found? Verify: YAZE_ENABLE_AGENT_CLI=ON (auto-forced by YAZE_BUILD_CLI=ON)
  5. HTTP API endpoints undefined? Check: YAZE_ENABLE_HTTP_API=ON forces YAZE_ENABLE_AGENT_CLI=ON

8. Future Improvements

Potential enhancements as project evolves:

  • Separate AI_RUNTIME from ENABLE_AI (currently coupled)
  • Add YAZE_ENABLE_GRPC_STRICT flag for stricter server-side validation
  • Document platform-specific library version constraints
  • Add automated configuration lint tool
  • Track binary size impact per feature flag combination
  • Add performance benchmarks for each Tier 2 configuration
Reference in New Issue View Git Blame Copy Permalink