scawful/yaze
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

backend-infra-engineer: Post v0.3.9-hotfix7 snapshot (build cleanup)

Browse Source
This commit is contained in:
scawful
2025-12-22 00:20:49 +00:00
parent 2934c82b75
commit 5c4cd57ff8
1259 changed files with 239160 additions and 43801 deletions
Download Patch File Download Diff File Expand all files Collapse all files

339
docs/internal/architecture/configuration_matrix.md Normal file
View File

@@ -0,0 +1,339 @@
# 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