340 lines
12 KiB
Markdown
340 lines
12 KiB
Markdown
# 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:
|
|
|
|
```cmake
|
|
# 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
|
|
|
|
```bash
|
|
# 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`:
|
|
|
|
```yaml
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|