1843 lines
65 KiB
Markdown
1843 lines
65 KiB
Markdown
# YAZE Dependency Architecture & Build Optimization
|
|
|
|
**Author**: Claude (Anthropic AI Assistant)
|
|
**Date**: 2025-10-13
|
|
**Status**: Reference Document
|
|
**Related Docs**: [C4-z3ed-refactoring.md](C4-z3ed-refactoring.md), [B6-zelda3-library-refactoring.md](B6-zelda3-library-refactoring.md), [A2-test-dashboard-refactoring.md](A2-test-dashboard-refactoring.md)
|
|
|
|
---
|
|
|
|
## Executive Summary
|
|
|
|
This document provides a comprehensive analysis of YAZE's dependency architecture, identifies optimization opportunities, and proposes a roadmap for reducing build times and improving maintainability.
|
|
|
|
### Key Findings
|
|
|
|
- **Current State**: 25+ static libraries with complex interdependencies
|
|
- **Main Issues**: Circular dependencies, over-linking, misplaced components
|
|
- **Build Impact**: Changes to foundation libraries trigger rebuilds of 10-15+ dependent libraries
|
|
- **Opportunity**: 40-60% faster incremental builds through proposed refactorings
|
|
|
|
### Quick Stats
|
|
|
|
| Metric | Current | After Refactoring |
|
|
|--------|---------|-------------------|
|
|
| Total Libraries | 28 | 35 (more granular) |
|
|
| Circular Dependencies | 2 | 0 |
|
|
| Average Link Depth | 5-7 layers | 3-4 layers |
|
|
| Incremental Build Time | Baseline | **40-60% faster** |
|
|
| Test Isolation | Poor | Excellent |
|
|
|
|
---
|
|
|
|
## 1. Complete Dependency Graph
|
|
|
|
### 1.1 Foundation Layer
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ External Dependencies │
|
|
│ • SDL2 (graphics, input, audio) │
|
|
│ • ImGui (UI framework) │
|
|
│ • Abseil (utilities, status, flags) │
|
|
│ • GoogleTest/GoogleMock (testing) │
|
|
│ • gRPC (optional - networking) │
|
|
│ • nlohmann_json (optional - JSON) │
|
|
│ • yaml-cpp (configuration) │
|
|
│ • FTXUI (terminal UI) │
|
|
│ • Asar (65816 assembler) │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
↓
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ yaze_common │
|
|
│ • Common platform definitions │
|
|
│ • No dependencies │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
↓
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ yaze_util │
|
|
│ • Logging, file I/O, SDL utilities │
|
|
│ • Depends on: yaze_common, absl, SDL2 │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### 1.2 Graphics Tier (Refactored)
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ yaze_gfx (INTERFACE - aggregates all gfx sub-libraries) │
|
|
└────────────────────────┬────────────────────────────────────────┘
|
|
│
|
|
┌──────────────────┼──────────────────┐
|
|
│ │ │
|
|
▼ ▼ ▼
|
|
┌──────────┐ ┌──────────────┐ ┌─────────────┐
|
|
│ gfx_debug│─────│ gfx_render │ │ gfx_util │
|
|
└──────────┘ └──────┬───────┘ └─────┬───────┘
|
|
│ │
|
|
└─────────┬─────────┘
|
|
▼
|
|
┌──────────────┐
|
|
│ gfx_core │
|
|
│ (Bitmap) │
|
|
└──────┬───────┘
|
|
│
|
|
┌────────────┼────────────┐
|
|
▼ ▼ ▼
|
|
┌────────────┐ ┌──────────┐ ┌──────────┐
|
|
│ gfx_types │ │gfx_resource│ │gfx_backend│
|
|
│ (SNES data)│ │ (Arena) │ │ (SDL2) │
|
|
└────────────┘ └──────────┘ └──────────┘
|
|
|
|
Dependencies:
|
|
• gfx_types → (none - foundation)
|
|
• gfx_backend → SDL2
|
|
• gfx_resource → gfx_backend
|
|
• gfx_core → gfx_types + gfx_resource
|
|
• gfx_render → gfx_core + gfx_backend
|
|
• gfx_util → gfx_core
|
|
• gfx_debug → gfx_util + gfx_render
|
|
```
|
|
|
|
**Note**: `gfx_resource` (Arena) depends on `gfx_render` (BackgroundBuffer) but this is acceptable as both are low-level resource management. Not circular because gfx_render doesn't depend back on gfx_resource.
|
|
|
|
### 1.3 GUI Tier (Refactored)
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ yaze_gui (INTERFACE - aggregates all gui sub-libraries) │
|
|
└────────────────────────┬────────────────────────────────────────┘
|
|
│
|
|
┌──────────────┼──────────────┐
|
|
│ │ │
|
|
▼ ▼ ▼
|
|
┌──────────┐ ┌────────────┐ ┌────────────┐
|
|
│ gui_app │ │gui_automation│ │gui_widgets │
|
|
└────┬─────┘ └─────┬──────┘ └─────┬──────┘
|
|
│ │ │
|
|
└──────────────┼───────────────┘
|
|
▼
|
|
┌──────────────────┐
|
|
│ gui_canvas │
|
|
└─────────┬────────┘
|
|
▼
|
|
┌──────────────────┐
|
|
│ gui_core │
|
|
│ (Theme, Input) │
|
|
└──────────────────┘
|
|
|
|
Dependencies:
|
|
• gui_core → yaze_util + ImGui + nlohmann_json
|
|
• gui_canvas → gui_core + yaze_gfx
|
|
• gui_widgets → gui_core + yaze_gfx
|
|
• gui_automation → gui_core
|
|
• gui_app → gui_core + gui_widgets + gui_automation
|
|
```
|
|
|
|
### 1.4 Zelda3 Library (Current - Monolithic)
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ yaze_zelda3 (MONOLITHIC - needs refactoring per B6) │
|
|
│ • Overworld (maps, tiles, warps) │
|
|
│ • Dungeon (rooms, objects, layouts) │
|
|
│ • Sprites (entities, overlords) │
|
|
│ • Screens (title, inventory, dungeon map) │
|
|
│ • Music (tracker - legacy Hyrule Magic code) │
|
|
│ • Labels & constants │
|
|
│ │
|
|
│ Depends on: yaze_gfx, yaze_util, yaze_common, absl │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
|
|
Warning: ISSUE: Located at src/app/zelda3/ but used by both app AND cli
|
|
Warning: ISSUE: Monolithic - any change rebuilds entire library
|
|
```
|
|
|
|
### 1.5 Zelda3 Library (Proposed - Tiered)
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ yaze_zelda3 (INTERFACE - aggregates sub-libraries) │
|
|
└────────────────────────┬────────────────────────────────────────┘
|
|
│
|
|
┌─────────────────┼─────────────────┐
|
|
│ │ │
|
|
▼ ▼ ▼
|
|
┌────────────┐ ┌────────────┐ ┌────────────┐
|
|
│zelda3_screen│───│zelda3_dungeon│──│zelda3_overworld│
|
|
└────────────┘ └──────┬─────┘ └──────┬──────┘
|
|
│ │
|
|
┌─────────────────┼─────────────────┘
|
|
│ │
|
|
▼ ▼
|
|
┌────────────┐ ┌────────────┐
|
|
│zelda3_music│ │zelda3_sprite│
|
|
└──────┬─────┘ └──────┬─────┘
|
|
│ │
|
|
└────────┬────────┘
|
|
▼
|
|
┌───────────────┐
|
|
│ zelda3_core │
|
|
│ (Labels, │
|
|
│ constants) │
|
|
└───────────────┘
|
|
|
|
Benefits:
|
|
Location: src/zelda3/ (proper top-level shared lib)
|
|
Granular: Change dungeon logic → only rebuilds dungeon + dependents
|
|
Clear boundaries: Separate overworld/dungeon/sprite concerns
|
|
Legacy isolation: Music tracker separated from modern code
|
|
```
|
|
|
|
### 1.6 Core Libraries
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ yaze_core_lib (Warning: CIRCULAR DEPENDENCY RISK) │
|
|
│ • ROM management (rom.cc) │
|
|
│ • Window/input (window.cc) │
|
|
│ • Asar wrapper (asar_wrapper.cc) │
|
|
│ • Platform utilities (file dialogs, fonts, clipboard) │
|
|
│ • Project management (project.cc) │
|
|
│ • Controller (controller.cc) │
|
|
│ • gRPC services (optional - test harness, ROM service) │
|
|
│ │
|
|
│ Depends on: yaze_util, yaze_gfx, yaze_zelda3, yaze_common, │
|
|
│ ImGui, asar-static, SDL2, (gRPC) │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
↓
|
|
Warning: CIRCULAR: yaze_gfx → depends on gfx_resource (Arena)
|
|
Arena.h includes background_buffer.h (from gfx_render)
|
|
gfx_render → gfx_core → gfx_resource
|
|
BUT yaze_core_lib → yaze_gfx
|
|
|
|
If anything in core_lib needs gfx_resource internals,
|
|
we get: core_lib → gfx → gfx_resource → (potentially) core_lib
|
|
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ yaze_emulator │
|
|
│ • CPU (65C816) │
|
|
│ • PPU (graphics) │
|
|
│ • APU (audio - SPC700 + DSP) │
|
|
│ • Memory, DMA │
|
|
│ • Input management │
|
|
│ • Debugger UI components │
|
|
│ │
|
|
│ Depends on: yaze_util, yaze_common, yaze_core_lib, absl, SDL2 │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ yaze_net │
|
|
│ • ROM version management │
|
|
│ • WebSocket client │
|
|
│ • Collaboration service │
|
|
│ • ROM service (gRPC - disabled) │
|
|
│ │
|
|
│ Depends on: yaze_util, yaze_common, absl, (OpenSSL), (gRPC) │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### 1.7 Application Layer
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ yaze_test_support (Warning: CIRCULAR WITH yaze_editor) │
|
|
│ • TestManager (core test infrastructure) │
|
|
│ • z3ed test suite │
|
|
│ │
|
|
│ Depends on: yaze_editor, yaze_core_lib, yaze_gui, yaze_zelda3, │
|
|
│ yaze_gfx, yaze_util, yaze_common, yaze_agent │
|
|
└────────────────────────┬────────────────────────────────────────┘
|
|
│
|
|
│ Warning: CIRCULAR DEPENDENCY
|
|
↓
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ yaze_editor │
|
|
│ • Dungeon editor │
|
|
│ • Overworld editor │
|
|
│ • Sprite editor │
|
|
│ • Graphics/palette editors │
|
|
│ • Message editor │
|
|
│ • Assembly editor │
|
|
│ • System editors (settings, commands) │
|
|
│ • Agent integration (AI features) │
|
|
│ │
|
|
│ Depends on: yaze_core_lib, yaze_gfx, yaze_gui, yaze_zelda3, │
|
|
│ yaze_emulator, yaze_util, yaze_common, ImGui, │
|
|
│ [yaze_agent], [yaze_test_support] (conditional) │
|
|
└────────────────────────┬────────────────────────────────────────┘
|
|
│
|
|
│ Links back to test_support when YAZE_BUILD_TESTS=ON
|
|
└───────────────────────────────────────────┐
|
|
│
|
|
▼
|
|
Warning: CIRCULAR DEPENDENCY
|
|
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ yaze_agent (Warning: LINKS TO ALMOST EVERYTHING) │
|
|
│ • Command handlers (resource, dungeon, overworld, graphics) │
|
|
│ • AI services (Ollama, Gemini) │
|
|
│ • GUI automation client │
|
|
│ • TUI system (enhanced terminal UI) │
|
|
│ • Planning/proposal system │
|
|
│ • Test generation │
|
|
│ • Conversation management │
|
|
│ │
|
|
│ Depends on: yaze_common, yaze_util, yaze_gfx, yaze_gui, │
|
|
│ yaze_core_lib, yaze_zelda3, yaze_emulator, absl, │
|
|
│ yaml-cpp, ftxui, (gRPC), (nlohmann_json), (OpenSSL) │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
|
|
Warning: ISSUE: yaze_agent is massive and pulls in the entire application stack
|
|
Even simple CLI commands link against graphics, GUI, emulator, etc.
|
|
```
|
|
|
|
### 1.8 Executables
|
|
|
|
```
|
|
┌────────────────────────────────────────────────────────────────┐
|
|
│ yaze (Main Application) │
|
|
│ │
|
|
│ Links: yaze_editor, yaze_emulator, yaze_core_lib, yaze_agent, │
|
|
│ [yaze_test_support] (conditional), ImGui, SDL2 │
|
|
│ │
|
|
│ Transitively gets: All libraries through yaze_editor │
|
|
└────────────────────────────────────────────────────────────────┘
|
|
|
|
┌────────────────────────────────────────────────────────────────┐
|
|
│ z3ed (CLI Tool) │
|
|
│ │
|
|
│ Links: yaze_agent, yaze_core_lib, yaze_zelda3, ftxui │
|
|
│ │
|
|
│ Transitively gets: All libraries through yaze_agent (!) │
|
|
│ Warning: ISSUE: CLI tool rebuilds if GUI/graphics/emulator changes │
|
|
└────────────────────────────────────────────────────────────────┘
|
|
|
|
┌────────────────────────────────────────────────────────────────┐
|
|
│ yaze_emu (Standalone Emulator) │
|
|
│ │
|
|
│ Links: yaze_emulator, yaze_core_lib, ImGui, SDL2 │
|
|
│ │
|
|
│ Warning: Conditionally built with YAZE_BUILD_EMU=ON │
|
|
└────────────────────────────────────────────────────────────────┘
|
|
|
|
┌────────────────────────────────────────────────────────────────┐
|
|
│ Test Executables │
|
|
│ │
|
|
│ yaze_test_stable: │
|
|
│ - Unit tests (asar, rom, gfx, gui, zelda3, cli) │
|
|
│ - Integration tests (dungeon, overworld, editor) │
|
|
│ - Links: yaze_test_support, gmock_main, gtest_main │
|
|
│ │
|
|
│ yaze_test_gui: │
|
|
│ - E2E GUI tests with ImGuiTestEngine │
|
|
│ - Links: yaze_test_support, ImGuiTestEngine │
|
|
│ │
|
|
│ yaze_test_rom_dependent: │
|
|
│ - Tests requiring actual ROM file │
|
|
│ - Only built when YAZE_ENABLE_ROM_TESTS=ON │
|
|
│ │
|
|
│ yaze_test_experimental: │
|
|
│ - AI integration tests (vision, tile placement) │
|
|
│ │
|
|
│ yaze_test_benchmark: │
|
|
│ - Performance benchmarks │
|
|
└────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## 2. Current Dependency Issues
|
|
|
|
### 2.1 Circular Dependencies
|
|
|
|
#### Issue 1: yaze_test_support ↔ yaze_editor
|
|
|
|
```
|
|
yaze_test_support
|
|
├─→ yaze_editor (for EditorManager, Canvas, etc.)
|
|
└─→ yaze_core_lib, yaze_gui, yaze_zelda3, ...
|
|
|
|
yaze_editor (when YAZE_BUILD_TESTS=ON)
|
|
└─→ yaze_test_support (for TestManager)
|
|
|
|
Result: Neither can be built first, causes linking issues
|
|
```
|
|
|
|
**Impact**:
|
|
- Confusing build order
|
|
- Test dashboard cannot be excluded from release builds cleanly
|
|
- Changes to test infrastructure force editor rebuilds
|
|
|
|
**Solution** (from A2-test-dashboard-refactoring.md):
|
|
```
|
|
test_framework (core logic only)
|
|
├─→ yaze_util, absl (no app dependencies)
|
|
|
|
test_suites (actual tests)
|
|
├─→ test_framework
|
|
└─→ yaze_zelda3, yaze_gfx (only what's needed)
|
|
|
|
test_dashboard (GUI component - OPTIONAL)
|
|
├─→ test_framework
|
|
├─→ yaze_gui
|
|
└─→ Conditionally linked to yaze app
|
|
|
|
yaze_editor
|
|
└─→ (no test dependencies)
|
|
```
|
|
|
|
#### Issue 2: Potential yaze_core_lib ↔ yaze_gfx Cycle
|
|
|
|
```
|
|
yaze_core_lib
|
|
└─→ yaze_gfx (for graphics operations)
|
|
|
|
yaze_gfx
|
|
└─→ gfx_resource (Arena)
|
|
|
|
gfx_resource (Arena)
|
|
└─→ Includes background_buffer.h (from gfx_render)
|
|
└─→ Has BackgroundBuffer members (bg1_, bg2_)
|
|
|
|
If yaze_core_lib internals ever need gfx_resource specifics:
|
|
yaze_core_lib → yaze_gfx → gfx_resource → (back to) core_lib ❌
|
|
```
|
|
|
|
**Current Status**: Not a problem yet, but risky
|
|
**Solution**: Split yaze_core_lib into foundation vs services
|
|
|
|
### 2.2 Over-Linking Problems
|
|
|
|
#### Problem 1: yaze_test_support Links to Everything
|
|
|
|
```
|
|
yaze_test_support dependencies:
|
|
├─→ yaze_editor (Warning: Brings in entire app stack)
|
|
├─→ yaze_core_lib
|
|
├─→ yaze_gui (Warning: Brings in all GUI widgets)
|
|
├─→ yaze_zelda3
|
|
├─→ yaze_gfx (Warning: All 7 gfx libraries)
|
|
├─→ yaze_util
|
|
├─→ yaze_common
|
|
└─→ yaze_agent (Warning: Brings in AI services, emulator, etc.)
|
|
|
|
Result: Test executables link against THE ENTIRE APPLICATION
|
|
```
|
|
|
|
**Impact**:
|
|
- Test binaries are massive (100+ MB)
|
|
- Any change to any library forces test relink
|
|
- Slow CI/CD pipeline
|
|
- Cannot build minimal test suites
|
|
|
|
**Solution**:
|
|
- Separate test framework from test suites
|
|
- Each test suite links only to what it tests
|
|
- Remove yaze_editor from test framework
|
|
|
|
#### Problem 2: yaze_agent Links to Everything
|
|
|
|
```
|
|
yaze_agent dependencies:
|
|
├─→ yaze_common
|
|
├─→ yaze_util
|
|
├─→ yaze_gfx (all 7 libs)
|
|
├─→ yaze_gui (all 5 libs)
|
|
├─→ yaze_core_lib
|
|
├─→ yaze_zelda3
|
|
├─→ yaze_emulator
|
|
├─→ absl
|
|
├─→ yaml-cpp
|
|
├─→ ftxui
|
|
├─→ [gRPC]
|
|
├─→ [nlohmann_json]
|
|
└─→ [OpenSSL]
|
|
|
|
Result: z3ed CLI tool rebuilds if GUI changes!
|
|
```
|
|
|
|
**Impact**:
|
|
- CLI tool (`z3ed`) is 80+ MB
|
|
- Any GUI/graphics change forces CLI rebuild
|
|
- Cannot build minimal agent for server deployment
|
|
- Tight coupling between CLI and GUI
|
|
|
|
**Solution**:
|
|
```
|
|
yaze_agent_core (minimal)
|
|
├─→ Command handling abstractions
|
|
├─→ TUI system (FTXUI)
|
|
├─→ yaze_util, yaze_common
|
|
└─→ NO graphics, NO gui, NO emulator
|
|
|
|
yaze_agent_services (full stack)
|
|
├─→ yaze_agent_core
|
|
├─→ yaze_gfx, yaze_gui (for GUI automation)
|
|
├─→ yaze_emulator (for emulator commands)
|
|
└─→ yaze_zelda3 (for game logic queries)
|
|
|
|
z3ed executable
|
|
└─→ yaze_agent_core (minimal build)
|
|
└─→ Optional: yaze_agent_services (full features)
|
|
```
|
|
|
|
#### Problem 3: yaze_editor Links to 8+ Major Libraries
|
|
|
|
```
|
|
yaze_editor dependencies:
|
|
├─→ yaze_core_lib
|
|
├─→ yaze_gfx (7 libs transitively)
|
|
├─→ yaze_gui (5 libs transitively)
|
|
├─→ yaze_zelda3
|
|
├─→ yaze_emulator
|
|
├─→ yaze_util
|
|
├─→ yaze_common
|
|
├─→ ImGui
|
|
├─→ [yaze_agent] (conditional)
|
|
└─→ [yaze_test_support] (conditional)
|
|
|
|
Result: Changes to ANY of these trigger editor rebuild
|
|
```
|
|
|
|
**Impact**:
|
|
- 60+ second editor rebuilds on gfx changes
|
|
- Tight coupling across entire application
|
|
- Difficult to isolate editor features
|
|
- Hard to test individual editors
|
|
|
|
**Mitigation** (already done for gfx/gui):
|
|
- gfx refactored into 7 granular libs
|
|
- gui refactored into 5 granular libs
|
|
- Next: Refactor zelda3 into 6 granular libs
|
|
- Next: Split editor into editor modules
|
|
|
|
### 2.3 Misplaced Components
|
|
|
|
#### Issue 1: zelda3 Library Location
|
|
|
|
```
|
|
Current: src/app/zelda3/
|
|
└─→ Implies it's part of GUI application
|
|
|
|
Reality: Used by both yaze app AND z3ed CLI
|
|
└─→ Should be top-level shared library
|
|
|
|
Problem: cli/ cannot depend on app/ (architectural violation)
|
|
```
|
|
|
|
**Solution** (from B6-zelda3-library-refactoring.md):
|
|
- Move: `src/app/zelda3/` → `src/zelda3/`
|
|
- Update all includes: `#include "app/zelda3/...` → `#include "zelda3/...`
|
|
- Establish as proper shared core component
|
|
|
|
#### Issue 2: Test Infrastructure Mixed into App
|
|
|
|
```
|
|
Current: src/app/test/
|
|
└─→ test_manager.cc (core logic + GUI dashboard)
|
|
└─→ z3ed_test_suite.cc (test implementation)
|
|
|
|
Problem: Cannot exclude test dashboard from release builds
|
|
Cannot build minimal test framework
|
|
```
|
|
|
|
**Solution** (from A2-test-dashboard-refactoring.md):
|
|
- Move: `src/app/test/` → `src/test/framework/` + `src/test/suites/`
|
|
- Separate: `TestManager` (core) from `TestDashboard` (GUI)
|
|
- Make: `test_dashboard` conditionally compiled
|
|
|
|
---
|
|
|
|
## 3. Build Time Impact Analysis
|
|
|
|
### 3.1 Current Rebuild Cascades
|
|
|
|
#### Scenario 1: Change snes_tile.cc (gfx_types)
|
|
|
|
```
|
|
snes_tile.cc (gfx_types)
|
|
↓
|
|
yaze_gfx_core (depends on gfx_types)
|
|
↓
|
|
yaze_gfx_util + yaze_gfx_render (depend on gfx_core)
|
|
↓
|
|
yaze_gfx_debug (depends on gfx_util + gfx_render)
|
|
↓
|
|
yaze_gfx (INTERFACE - aggregates all)
|
|
↓
|
|
yaze_gui_core + yaze_canvas + yaze_gui_widgets (depend on yaze_gfx)
|
|
↓
|
|
yaze_gui (INTERFACE - aggregates all)
|
|
↓
|
|
yaze_core_lib (depends on yaze_gfx + yaze_gui)
|
|
↓
|
|
yaze_editor + yaze_agent + yaze_net (depend on core_lib)
|
|
↓
|
|
yaze_test_support (depends on yaze_editor)
|
|
↓
|
|
All test executables (depend on yaze_test_support)
|
|
↓
|
|
yaze + z3ed + yaze_emu (main executables)
|
|
|
|
TOTAL: 20+ libraries rebuilt, 6+ executables relinked
|
|
TIME: 5-10 minutes on CI, 2-3 minutes locally
|
|
```
|
|
|
|
#### Scenario 2: Change overworld_map.cc (zelda3)
|
|
|
|
```
|
|
overworld_map.cc (yaze_zelda3 - monolithic)
|
|
↓
|
|
yaze_zelda3 (ENTIRE library rebuilt)
|
|
↓
|
|
yaze_core_lib (depends on yaze_zelda3)
|
|
↓
|
|
yaze_editor + yaze_agent (depend on core_lib)
|
|
↓
|
|
yaze_test_support (depends on yaze_editor + yaze_agent)
|
|
↓
|
|
All test executables
|
|
↓
|
|
yaze + z3ed executables
|
|
|
|
TOTAL: 8+ libraries rebuilt, 6+ executables relinked
|
|
TIME: 3-5 minutes on CI, 1-2 minutes locally
|
|
```
|
|
|
|
#### Scenario 3: Change test_manager.cc
|
|
|
|
```
|
|
test_manager.cc (yaze_test_support)
|
|
↓
|
|
yaze_test_support
|
|
↓
|
|
yaze_editor (links to test_support when YAZE_BUILD_TESTS=ON)
|
|
↓
|
|
yaze + z3ed (link to yaze_editor)
|
|
↓
|
|
All test executables (link to yaze_test_support)
|
|
|
|
TOTAL: 3 libraries rebuilt, 8+ executables relinked
|
|
TIME: 1-2 minutes
|
|
|
|
Warning: CIRCULAR: Editor change forces test rebuild,
|
|
Test change forces editor rebuild
|
|
```
|
|
|
|
### 3.2 Optimized Rebuild Cascades (After Refactoring)
|
|
|
|
#### Scenario 1: Change snes_tile.cc (gfx_types) - Optimized
|
|
|
|
```
|
|
snes_tile.cc (gfx_types)
|
|
↓
|
|
yaze_gfx_core (depends on gfx_types)
|
|
↓
|
|
yaze_gfx_util + yaze_gfx_render (depend on gfx_core)
|
|
|
|
STOP: Changes don't affect gfx_backend or gfx_resource
|
|
STOP: gui libraries still use old gfx INTERFACE
|
|
|
|
Only rebuilt if consumers explicitly use changed APIs:
|
|
- yaze_zelda3 (if it uses modified tile functions)
|
|
- Specific editor modules (if they use modified functions)
|
|
|
|
TOTAL: 3-5 libraries rebuilt, 1-2 executables relinked
|
|
TIME: 30-60 seconds on CI, 15-30 seconds locally
|
|
SAVINGS: 80% faster!
|
|
```
|
|
|
|
#### Scenario 2: Change overworld_map.cc (zelda3) - Optimized
|
|
|
|
```
|
|
With refactored zelda3:
|
|
|
|
overworld_map.cc (zelda3_overworld sub-library)
|
|
↓
|
|
yaze_zelda3_overworld (only this sub-library rebuilt)
|
|
|
|
STOP: zelda3_dungeon, zelda3_sprite unchanged
|
|
STOP: zelda3_screen depends on overworld but may not need rebuild
|
|
|
|
Only rebuilt if consumers use changed APIs:
|
|
- yaze_editor_overworld_module
|
|
- Specific overworld tests
|
|
- z3ed overworld commands
|
|
|
|
TOTAL: 2-3 libraries rebuilt, 1-2 executables relinked
|
|
TIME: 30-45 seconds on CI, 15-20 seconds locally
|
|
SAVINGS: 70% faster!
|
|
```
|
|
|
|
#### Scenario 3: Change test_manager.cc - Optimized
|
|
|
|
```
|
|
With separated test infrastructure:
|
|
|
|
test_manager.cc (test_framework)
|
|
↓
|
|
test_framework
|
|
|
|
STOP: test_suites may not need rebuild (depends on interface changes)
|
|
STOP: test_dashboard is separate, doesn't rebuild
|
|
STOP: yaze_editor has NO dependency on test system
|
|
|
|
Only rebuilt:
|
|
- test_framework
|
|
- Test executables (yaze_test_*)
|
|
|
|
TOTAL: 1 library rebuilt, 5 test executables relinked
|
|
TIME: 20-30 seconds on CI, 10-15 seconds locally
|
|
SAVINGS: 60% faster!
|
|
|
|
Warning: BONUS: Release builds exclude test_dashboard entirely
|
|
→ Smaller binary, faster builds, cleaner architecture
|
|
```
|
|
|
|
### 3.3 Build Time Savings Summary
|
|
|
|
| Change Type | Current Time | After Refactoring | Savings |
|
|
|-------------|--------------|-------------------|---------|
|
|
| gfx_types change | 5-10 min | 30-60 sec | **80%** |
|
|
| zelda3 change | 3-5 min | 30-45 sec | **70%** |
|
|
| Test infrastructure | 1-2 min | 20-30 sec | **60%** |
|
|
| GUI widget change | 4-6 min | 45-90 sec | **65%** |
|
|
| Agent change | 2-3 min | 30-45 sec | **50%** |
|
|
|
|
**Overall Incremental Build Improvement**: **40-60% faster** across common development scenarios
|
|
|
|
---
|
|
|
|
## 4. Proposed Refactoring Initiatives
|
|
|
|
### 4.1 Priority 1: Execute Existing Proposals
|
|
|
|
#### A. Test Dashboard Separation (A2)
|
|
|
|
**Status**: Proposed
|
|
**Priority**: HIGH
|
|
**Effort**: Medium (2-3 days)
|
|
**Impact**: 60% faster test builds, cleaner release builds
|
|
|
|
**Implementation**:
|
|
1. Create `src/test/framework/` directory
|
|
- Move `test_manager.h/cc` (core logic only)
|
|
- Remove UI code from TestManager
|
|
- Library: `yaze_test_framework`
|
|
- Dependencies: `yaze_util`, `absl`
|
|
|
|
2. Create `src/test/suites/` directory
|
|
- Move all `*_test_suite.h` files
|
|
- Move `z3ed_test_suite.cc`
|
|
- Library: `yaze_test_suites`
|
|
- Dependencies: `yaze_test_framework`, specific yaze libs
|
|
|
|
3. Create `src/app/gui/testing/` directory
|
|
- New `TestDashboard` class
|
|
- Move `DrawTestDashboard` from TestManager
|
|
- Library: `yaze_test_dashboard`
|
|
- Dependencies: `yaze_test_framework`, `yaze_gui`
|
|
- Conditional: `YAZE_WITH_TEST_DASHBOARD=ON`
|
|
|
|
4. Update build system
|
|
- Root CMake: Add `option(YAZE_WITH_TEST_DASHBOARD "..." ON)`
|
|
- app.cmake: Conditionally link `yaze_test_dashboard`
|
|
- Remove circular dependency
|
|
|
|
**Benefits**:
|
|
- No circular dependencies
|
|
- Release builds exclude test dashboard
|
|
- Test changes don't rebuild editor
|
|
- Cleaner architecture
|
|
|
|
#### B. Zelda3 Library Refactoring (B6)
|
|
|
|
**Status**: Proposed
|
|
**Priority**: HIGH
|
|
**Effort**: Large (4-5 days)
|
|
**Impact**: 70% faster zelda3 builds, proper shared library
|
|
|
|
**Phase 1: Physical Move**
|
|
```bash
|
|
# Move directory
|
|
mv src/app/zelda3 src/zelda3
|
|
|
|
# Update CMakeLists.txt
|
|
sed -i 's|include(zelda3/zelda3_library.cmake)|include(zelda3/zelda3_library.cmake)|' src/CMakeLists.txt
|
|
|
|
# Global include update
|
|
find . -type f \( -name "*.cc" -o -name "*.h" \) -exec sed -i 's|#include "app/zelda3/|#include "zelda3/|g' {} +
|
|
|
|
# Test build
|
|
cmake --preset mac-dev && cmake --build --preset mac-dev
|
|
```
|
|
|
|
**Phase 2: Decompose into Sub-Libraries**
|
|
|
|
```cmake
|
|
# src/zelda3/zelda3_library.cmake
|
|
|
|
# 1. Foundation
|
|
set(ZELDA3_CORE_SRC
|
|
zelda3/common.h
|
|
zelda3/zelda3_labels.cc
|
|
zelda3/palette_constants.cc
|
|
zelda3/dungeon/dungeon_rom_addresses.h
|
|
)
|
|
add_library(yaze_zelda3_core STATIC ${ZELDA3_CORE_SRC})
|
|
target_link_libraries(yaze_zelda3_core PUBLIC yaze_util)
|
|
|
|
# 2. Sprite (shared by dungeon + overworld)
|
|
set(ZELDA3_SPRITE_SRC
|
|
zelda3/sprite/sprite.cc
|
|
zelda3/sprite/sprite_builder.cc
|
|
zelda3/sprite/overlord.h
|
|
)
|
|
add_library(yaze_zelda3_sprite STATIC ${ZELDA3_SPRITE_SRC})
|
|
target_link_libraries(yaze_zelda3_sprite PUBLIC yaze_zelda3_core)
|
|
|
|
# 3. Dungeon
|
|
set(ZELDA3_DUNGEON_SRC
|
|
zelda3/dungeon/room.cc
|
|
zelda3/dungeon/room_layout.cc
|
|
zelda3/dungeon/room_object.cc
|
|
zelda3/dungeon/object_parser.cc
|
|
zelda3/dungeon/object_drawer.cc
|
|
zelda3/dungeon/dungeon_editor_system.cc
|
|
zelda3/dungeon/dungeon_object_editor.cc
|
|
)
|
|
add_library(yaze_zelda3_dungeon STATIC ${ZELDA3_DUNGEON_SRC})
|
|
target_link_libraries(yaze_zelda3_dungeon PUBLIC
|
|
yaze_zelda3_core
|
|
yaze_zelda3_sprite
|
|
)
|
|
|
|
# 4. Overworld
|
|
set(ZELDA3_OVERWORLD_SRC
|
|
zelda3/overworld/overworld.cc
|
|
zelda3/overworld/overworld_map.cc
|
|
)
|
|
add_library(yaze_zelda3_overworld STATIC ${ZELDA3_OVERWORLD_SRC})
|
|
target_link_libraries(yaze_zelda3_overworld PUBLIC
|
|
yaze_zelda3_core
|
|
yaze_zelda3_sprite
|
|
)
|
|
|
|
# 5. Screen
|
|
set(ZELDA3_SCREEN_SRC
|
|
zelda3/screen/title_screen.cc
|
|
zelda3/screen/inventory.cc
|
|
zelda3/screen/dungeon_map.cc
|
|
zelda3/screen/overworld_map_screen.cc
|
|
)
|
|
add_library(yaze_zelda3_screen STATIC ${ZELDA3_SCREEN_SRC})
|
|
target_link_libraries(yaze_zelda3_screen PUBLIC
|
|
yaze_zelda3_dungeon
|
|
yaze_zelda3_overworld
|
|
)
|
|
|
|
# 6. Music (legacy isolation)
|
|
set(ZELDA3_MUSIC_SRC
|
|
zelda3/music/tracker.cc
|
|
)
|
|
add_library(yaze_zelda3_music STATIC ${ZELDA3_MUSIC_SRC})
|
|
target_link_libraries(yaze_zelda3_music PUBLIC yaze_zelda3_core)
|
|
|
|
# Aggregate INTERFACE library
|
|
add_library(yaze_zelda3 INTERFACE)
|
|
target_link_libraries(yaze_zelda3 INTERFACE
|
|
yaze_zelda3_core
|
|
yaze_zelda3_sprite
|
|
yaze_zelda3_dungeon
|
|
yaze_zelda3_overworld
|
|
yaze_zelda3_screen
|
|
yaze_zelda3_music
|
|
)
|
|
```
|
|
|
|
**Benefits**:
|
|
- Proper top-level shared library
|
|
- Granular rebuilds (change dungeon → only dungeon + screen rebuild)
|
|
- Clear domain boundaries
|
|
- Legacy code isolated
|
|
|
|
#### C. z3ed Command Abstraction (C4)
|
|
|
|
**Status**: **COMPLETED**
|
|
**Priority**: N/A (already done)
|
|
**Impact**: 1300+ lines eliminated, 50-60% smaller command implementations
|
|
|
|
**Achievements**:
|
|
- Command abstraction layer (`CommandContext`, `ArgumentParser`, `OutputFormatter`)
|
|
- Enhanced TUI with themes and autocomplete
|
|
- Comprehensive test coverage
|
|
- AI-friendly predictable structure
|
|
|
|
**Next Steps**: None required, refactoring complete
|
|
|
|
### 4.2 Priority 2: New Refactoring Proposals
|
|
|
|
#### D. Split yaze_core_lib to Prevent Cycles
|
|
|
|
**Status**: Proposed (New)
|
|
**Priority**: MEDIUM
|
|
**Effort**: Medium (2-3 days)
|
|
**Impact**: Prevents future circular dependencies, cleaner separation
|
|
|
|
**Problem**:
|
|
```
|
|
yaze_core_lib currently contains:
|
|
├─→ ROM management (rom.cc)
|
|
├─→ Window/input (window.cc)
|
|
├─→ Asar wrapper (asar_wrapper.cc)
|
|
├─→ Platform utilities (file_dialog, fonts)
|
|
├─→ Project management (project.cc)
|
|
├─→ Controller (controller.cc)
|
|
└─→ gRPC services (test_harness, rom_service)
|
|
|
|
All mixed together in one library
|
|
If core_lib needs gfx internals → potential cycle
|
|
```
|
|
|
|
**Solution**:
|
|
```
|
|
yaze_core_foundation:
|
|
├─→ ROM management (rom.cc)
|
|
├─→ Window basics (window.cc)
|
|
├─→ Asar wrapper (asar_wrapper.cc)
|
|
├─→ Platform utilities (file_dialog, fonts)
|
|
└─→ Dependencies: yaze_util, yaze_common, asar, SDL2
|
|
(NO yaze_gfx, NO yaze_zelda3)
|
|
|
|
yaze_core_services:
|
|
├─→ Project management (project.cc) - needs zelda3 for labels
|
|
├─→ Controller (controller.cc) - coordinates editors
|
|
├─→ gRPC services (test_harness, rom_service)
|
|
└─→ Dependencies: yaze_core_foundation, yaze_gfx, yaze_zelda3
|
|
|
|
yaze_core_lib (INTERFACE):
|
|
└─→ Aggregates: yaze_core_foundation + yaze_core_services
|
|
```
|
|
|
|
**Benefits**:
|
|
- Clear separation: foundation vs services
|
|
- Prevents cycles: gfx → core_foundation → gfx ❌ (no longer possible)
|
|
- Selective linking: CLI can use foundation only
|
|
- Better testability
|
|
|
|
**Migration**:
|
|
```cmake
|
|
# src/app/core/core_library.cmake
|
|
|
|
set(CORE_FOUNDATION_SRC
|
|
core/asar_wrapper.cc
|
|
app/core/window.cc
|
|
app/rom.cc
|
|
app/platform/font_loader.cc
|
|
app/platform/asset_loader.cc
|
|
app/platform/file_dialog_nfd.cc # or .mm for macOS
|
|
)
|
|
|
|
add_library(yaze_core_foundation STATIC ${CORE_FOUNDATION_SRC})
|
|
target_link_libraries(yaze_core_foundation PUBLIC
|
|
yaze_util
|
|
yaze_common
|
|
asar-static
|
|
SDL2
|
|
)
|
|
|
|
set(CORE_SERVICES_SRC
|
|
app/core/project.cc
|
|
app/core/controller.cc
|
|
# gRPC services if enabled
|
|
)
|
|
|
|
add_library(yaze_core_services STATIC ${CORE_SERVICES_SRC})
|
|
target_link_libraries(yaze_core_services PUBLIC
|
|
yaze_core_foundation
|
|
yaze_gfx
|
|
yaze_zelda3
|
|
ImGui
|
|
)
|
|
|
|
# Aggregate
|
|
add_library(yaze_core_lib INTERFACE)
|
|
target_link_libraries(yaze_core_lib INTERFACE
|
|
yaze_core_foundation
|
|
yaze_core_services
|
|
)
|
|
```
|
|
|
|
#### E. Split yaze_agent for Minimal CLI
|
|
|
|
**Status**: Proposed (New)
|
|
**Priority**: MEDIUM-LOW
|
|
**Effort**: Medium (3-4 days)
|
|
**Impact**: 50% smaller z3ed builds, faster CLI development
|
|
|
|
**Problem**:
|
|
```
|
|
yaze_agent currently links to EVERYTHING:
|
|
├─→ yaze_gfx (all 7 libs)
|
|
├─→ yaze_gui (all 5 libs)
|
|
├─→ yaze_core_lib
|
|
├─→ yaze_zelda3
|
|
├─→ yaze_emulator
|
|
└─→ Result: 80+ MB z3ed binary, slow rebuilds
|
|
```
|
|
|
|
**Solution**:
|
|
```
|
|
yaze_agent_core (minimal):
|
|
├─→ Command registry & dispatcher
|
|
├─→ TUI system (FTXUI)
|
|
├─→ Argument parsing (from C4 refactoring)
|
|
├─→ Output formatting (from C4 refactoring)
|
|
├─→ Command context (from C4 refactoring)
|
|
├─→ Dependencies: yaze_util, yaze_common, ftxui, yaml-cpp
|
|
└─→ Size: ~15 MB binary
|
|
|
|
yaze_agent_services (full stack):
|
|
├─→ yaze_agent_core
|
|
├─→ AI services (Ollama, Gemini)
|
|
├─→ GUI automation client
|
|
├─→ Emulator commands
|
|
├─→ Proposal system
|
|
├─→ Dependencies: ALL yaze libraries
|
|
└─→ Size: +65 MB (total 80+ MB)
|
|
|
|
z3ed executable:
|
|
└─→ Links: yaze_agent_core (default)
|
|
└─→ Optional: yaze_agent_services (with --enable-full-features)
|
|
```
|
|
|
|
**Benefits**:
|
|
- 80% smaller CLI binary for basic commands
|
|
- Faster CLI development (no GUI rebuilds)
|
|
- Server deployments can use minimal agent
|
|
- Clear separation: core vs services
|
|
|
|
**Implementation**:
|
|
```cmake
|
|
# src/cli/agent.cmake
|
|
|
|
set(AGENT_CORE_SRC
|
|
cli/flags.cc
|
|
cli/handlers/command_handlers.cc
|
|
cli/service/command_registry.cc
|
|
cli/service/agent/tool_dispatcher.cc
|
|
cli/service/agent/enhanced_tui.cc
|
|
cli/service/resources/command_context.cc
|
|
cli/service/resources/command_handler.cc
|
|
cli/service/resources/resource_catalog.cc
|
|
# Minimal command handlers (resource queries, basic ROM ops)
|
|
)
|
|
|
|
add_library(yaze_agent_core STATIC ${AGENT_CORE_SRC})
|
|
target_link_libraries(yaze_agent_core PUBLIC
|
|
yaze_common
|
|
yaze_util
|
|
ftxui::component
|
|
yaml-cpp
|
|
)
|
|
|
|
set(AGENT_SERVICES_SRC
|
|
# All AI, GUI automation, emulator integration
|
|
cli/service/ai/ai_service.cc
|
|
cli/service/ai/ollama_ai_service.cc
|
|
cli/service/ai/gemini_ai_service.cc
|
|
cli/service/gui/gui_automation_client.cc
|
|
cli/handlers/tools/emulator_commands.cc
|
|
# ... all other advanced features
|
|
)
|
|
|
|
add_library(yaze_agent_services STATIC ${AGENT_SERVICES_SRC})
|
|
target_link_libraries(yaze_agent_services PUBLIC
|
|
yaze_agent_core
|
|
yaze_gfx
|
|
yaze_gui
|
|
yaze_core_lib
|
|
yaze_zelda3
|
|
yaze_emulator
|
|
# ... all dependencies
|
|
)
|
|
|
|
# z3ed can choose which to link
|
|
```
|
|
|
|
### 4.3 Priority 3: Future Optimizations
|
|
|
|
#### F. Editor Modularization
|
|
|
|
**Status**: Future
|
|
**Priority**: LOW
|
|
**Effort**: Large (1-2 weeks)
|
|
**Impact**: Parallel development, isolated testing
|
|
|
|
**Concept**:
|
|
```
|
|
yaze_editor_dungeon:
|
|
└─→ Only dungeon editor code
|
|
|
|
yaze_editor_overworld:
|
|
└─→ Only overworld editor code
|
|
|
|
yaze_editor_system:
|
|
└─→ Settings, commands, workspace
|
|
|
|
yaze_editor (INTERFACE):
|
|
└─→ Aggregates all editor modules
|
|
```
|
|
|
|
**Benefits**:
|
|
- Parallel development on different editors
|
|
- Isolated testing per editor
|
|
- Faster incremental builds
|
|
|
|
**Defer**: After zelda3 refactoring, test separation complete
|
|
|
|
#### G. Precompiled Headers Optimization
|
|
|
|
**Status**: Future
|
|
**Priority**: LOW
|
|
**Effort**: Small (1 day)
|
|
**Impact**: 10-20% faster full rebuilds
|
|
|
|
**Current**: PCH in `src/yaze_pch.h` but not fully optimized
|
|
|
|
**Improvements**:
|
|
- Split into foundation PCH and app PCH
|
|
- More aggressive PCH usage
|
|
- Benchmark impact
|
|
|
|
#### H. Unity Builds for Third-Party Code
|
|
|
|
**Status**: Future
|
|
**Priority**: LOW
|
|
**Effort**: Small (1 day)
|
|
**Impact**: Faster clean builds
|
|
|
|
**Concept**: Combine multiple translation units for faster compilation
|
|
|
|
---
|
|
|
|
## 5. Conditional Compilation Matrix
|
|
|
|
### Build Configurations
|
|
|
|
| Configuration | Purpose | Test Dashboard | Agent | gRPC | ROM Tests |
|
|
|---------------|---------|----------------|-------|------|-----------|
|
|
| **Debug** | Local development | ON | ON | ON | ❌ OFF |
|
|
| **Debug-AI** | AI feature development | ON | ON | ON | ❌ OFF |
|
|
| **Release** | Production | ❌ OFF | ❌ OFF | ❌ OFF | ❌ OFF |
|
|
| **CI-Linux** | Ubuntu CI/CD | ❌ OFF | ON | ON | ❌ OFF |
|
|
| **CI-Windows** | Windows CI/CD | ❌ OFF | ON | ON | ❌ OFF |
|
|
| **CI-macOS** | macOS CI/CD | ❌ OFF | ON | ON | ❌ OFF |
|
|
| **Dev-ROM** | ROM testing | ON | ON | ON | ON |
|
|
|
|
### Feature Flags
|
|
|
|
| Flag | Default | Effect |
|
|
|------|---------|--------|
|
|
| `YAZE_BUILD_APP` | ON | Build main application |
|
|
| `YAZE_BUILD_Z3ED` | ON | Build CLI tool |
|
|
| `YAZE_BUILD_EMU` | OFF | Build standalone emulator |
|
|
| `YAZE_BUILD_TESTS` | ON | Build test suites |
|
|
| `YAZE_BUILD_LIB` | OFF | Build C API library |
|
|
| `YAZE_WITH_GRPC` | ON | Enable gRPC (networking) |
|
|
| `YAZE_WITH_JSON` | ON | Enable JSON (AI services) |
|
|
| `YAZE_WITH_TEST_DASHBOARD` | ON | Include test dashboard in app |
|
|
| `YAZE_ENABLE_ROM_TESTS` | OFF | Enable ROM-dependent tests |
|
|
| `YAZE_MINIMAL_BUILD` | OFF | Minimal build (no agent/tests) |
|
|
|
|
### Library Availability Matrix
|
|
|
|
| Library | Always Built | Conditional | Notes |
|
|
|---------|--------------|-------------|-------|
|
|
| yaze_util | | - | Foundation |
|
|
| yaze_common | | - | Foundation |
|
|
| yaze_gfx | | - | Core graphics |
|
|
| yaze_gui | | - | Core GUI |
|
|
| yaze_zelda3 | | - | Game logic |
|
|
| yaze_core_lib | | - | ROM management |
|
|
| yaze_emulator | | - | SNES emulation |
|
|
| yaze_net | | JSON/gRPC | Networking |
|
|
| yaze_editor | | APP | Main editor |
|
|
| yaze_agent | | Z3ED | CLI features |
|
|
| yaze_test_support | ❌ | TESTS | Test infrastructure |
|
|
| yaze_test_dashboard | ❌ | TEST_DASHBOARD | GUI test dashboard |
|
|
|
|
### Executable Build Matrix
|
|
|
|
| Executable | Build Condition | Dependencies |
|
|
|------------|-----------------|--------------|
|
|
| yaze | `YAZE_BUILD_APP=ON` | editor, emulator, core_lib, [agent], [test_dashboard] |
|
|
| z3ed | `YAZE_BUILD_Z3ED=ON` | agent, core_lib, zelda3 |
|
|
| yaze_emu | `YAZE_BUILD_EMU=ON` | emulator, core_lib |
|
|
| yaze_test_stable | `YAZE_BUILD_TESTS=ON` | test_support, all libs |
|
|
| yaze_test_gui | `YAZE_BUILD_TESTS=ON` | test_support, ImGuiTestEngine |
|
|
| yaze_test_rom_dependent | `YAZE_ENABLE_ROM_TESTS=ON` | test_support + ROM |
|
|
|
|
---
|
|
|
|
## 6. Migration Roadmap
|
|
|
|
### Phase 1: Foundation Fixes ( This PR)
|
|
|
|
**Timeline**: Immediate
|
|
**Status**: In Progress
|
|
|
|
**Tasks**:
|
|
1. Fix `BackgroundBuffer` constructor in `Arena::Arena()`
|
|
2. Add `yaze_core_lib` dependency to `yaze_emulator`
|
|
3. Document current architecture in this file
|
|
|
|
**Expected Outcome**:
|
|
- Ubuntu CI passes
|
|
- No build regressions
|
|
- Complete architectural documentation
|
|
|
|
### Phase 2: Test Separation (Next Sprint)
|
|
|
|
**Timeline**: 1 week
|
|
**Status**: Proposed
|
|
**Reference**: A2-test-dashboard-refactoring.md
|
|
|
|
**Tasks**:
|
|
1. Create `src/test/framework/` directory structure
|
|
2. Split `TestManager` into core + dashboard
|
|
3. Move test suites to `src/test/suites/`
|
|
4. Create `test_dashboard` conditional library
|
|
5. Update CMake build system
|
|
6. Update all test executables
|
|
7. Verify clean release builds
|
|
|
|
**Expected Outcome**:
|
|
- No circular dependencies
|
|
- 60% faster test builds
|
|
- Cleaner release binaries
|
|
- Isolated test framework
|
|
|
|
### Phase 3: Zelda3 Refactoring (Week 2-3)
|
|
|
|
**Timeline**: 1.5-2 weeks
|
|
**Status**: Proposed
|
|
**Reference**: B6-zelda3-library-refactoring.md
|
|
|
|
**Tasks**:
|
|
1. **Week 1**: Physical move
|
|
- Move `src/app/zelda3/` → `src/zelda3/`
|
|
- Update all `#include` directives (300+ files)
|
|
- Update CMake paths
|
|
- Verify builds
|
|
|
|
2. **Week 2**: Decomposition
|
|
- Create 6 sub-libraries (core, sprite, dungeon, overworld, screen, music)
|
|
- Establish dependency graph
|
|
- Update consumers
|
|
- Verify incremental builds
|
|
|
|
3. **Week 3**: Testing & Documentation
|
|
- Update test suite organization
|
|
- Benchmark build times
|
|
- Update documentation
|
|
- Migration guide
|
|
|
|
**Expected Outcome**:
|
|
- Proper top-level shared library
|
|
- 70% faster zelda3 incremental builds
|
|
- Clear domain boundaries
|
|
- Legacy code isolated
|
|
|
|
### Phase 4: Core Library Split (Week 4)
|
|
|
|
**Timeline**: 1 week
|
|
**Status**: Proposed
|
|
**Reference**: Section 4.2.D (this document)
|
|
|
|
**Tasks**:
|
|
1. Create `yaze_core_foundation` library
|
|
- Move ROM, window, asar, platform utilities
|
|
- Dependencies: util, common, SDL2, asar
|
|
|
|
2. Create `yaze_core_services` library
|
|
- Move project, controller, gRPC services
|
|
- Dependencies: core_foundation, gfx, zelda3
|
|
|
|
3. Update `yaze_core_lib` INTERFACE
|
|
- Aggregate foundation + services
|
|
|
|
4. Update all consumers
|
|
- Verify dependency chains
|
|
- No circular dependencies
|
|
|
|
**Expected Outcome**:
|
|
- Prevents future circular dependencies
|
|
- Cleaner separation of concerns
|
|
- Minimal CLI can use foundation only
|
|
|
|
### Phase 5: Agent Split (Week 5)
|
|
|
|
**Timeline**: 1 week
|
|
**Status**: Proposed
|
|
**Reference**: Section 4.2.E (this document)
|
|
|
|
**Tasks**:
|
|
1. Create `yaze_agent_core` library
|
|
- Command registry, TUI, parsers
|
|
- Dependencies: util, common, ftxui
|
|
|
|
2. Create `yaze_agent_services` library
|
|
- AI services, GUI automation, emulator integration
|
|
- Dependencies: agent_core, all yaze libs
|
|
|
|
3. Update `z3ed` executable
|
|
- Link minimal agent_core by default
|
|
- Optional full services
|
|
|
|
**Expected Outcome**:
|
|
- 80% smaller CLI binary
|
|
- 50% faster CLI development
|
|
- Server-friendly minimal agent
|
|
|
|
### Phase 6: Benchmarking & Optimization (Week 6)
|
|
|
|
**Timeline**: 3-4 days
|
|
**Status**: Future
|
|
|
|
**Tasks**:
|
|
1. Benchmark build times
|
|
- Before vs after comparisons
|
|
- Common development scenarios
|
|
- CI/CD pipeline times
|
|
|
|
2. Profile bottlenecks
|
|
- Identify remaining slow builds
|
|
- Measure header include costs
|
|
- Analyze link times
|
|
|
|
3. Optimize as needed
|
|
- PCH improvements
|
|
- Unity builds for third-party
|
|
- Parallel build tuning
|
|
|
|
**Expected Outcome**:
|
|
- Data-driven optimization
|
|
- Documented build time improvements
|
|
- Tuned build system
|
|
|
|
### Phase 7: Documentation & Polish (Week 7)
|
|
|
|
**Timeline**: 2-3 days
|
|
**Status**: Future
|
|
|
|
**Tasks**:
|
|
1. Update all documentation
|
|
- Architecture diagrams
|
|
- Build guides
|
|
- Migration guides
|
|
|
|
2. Create developer onboarding
|
|
- Quick start guide
|
|
- Common workflows
|
|
- Troubleshooting
|
|
|
|
3. CI/CD optimization
|
|
- Parallel build strategies
|
|
- Caching improvements
|
|
- Test parallelization
|
|
|
|
**Expected Outcome**:
|
|
- Complete documentation
|
|
- Smooth onboarding
|
|
- Optimized CI/CD
|
|
|
|
---
|
|
|
|
## 7. Expected Build Time Improvements
|
|
|
|
### Baseline Measurements (Current)
|
|
|
|
Measured on Apple M1 Max, 32 GB RAM, macOS 14.0
|
|
|
|
| Scenario | Current Time | Notes |
|
|
|----------|--------------|-------|
|
|
| Clean build (all features) | 8-10 min | Debug, gRPC, JSON, Tests |
|
|
| Clean build (minimal) | 5-6 min | No tests, no agent |
|
|
| Incremental (gfx change) | 2-3 min | Rebuilds 20+ libs |
|
|
| Incremental (zelda3 change) | 1-2 min | Rebuilds 8+ libs |
|
|
| Incremental (test change) | 45-60 sec | Circular rebuild |
|
|
| Incremental (editor change) | 1-2 min | Many dependents |
|
|
|
|
### Projected Improvements (After All Refactoring)
|
|
|
|
| Scenario | Projected Time | Savings | Notes |
|
|
|----------|----------------|---------|-------|
|
|
| Clean build (all features) | 7-8 min | 15-20% | Better parallelization |
|
|
| Clean build (minimal) | 3-4 min | 35-40% | Fewer conditional libs |
|
|
| Incremental (gfx change) | 30-45 sec | **75-80%** | Isolated gfx changes |
|
|
| Incremental (zelda3 change) | 20-30 sec | **70-75%** | Sub-library isolation |
|
|
| Incremental (test change) | 15-20 sec | **65-70%** | No circular rebuild |
|
|
| Incremental (editor change) | 30-45 sec | **60-65%** | Modular editors |
|
|
|
|
### CI/CD Improvements
|
|
|
|
| Pipeline | Current | Projected | Savings |
|
|
|----------|---------|-----------|---------|
|
|
| Ubuntu stable tests | 12-15 min | 8-10 min | **30-35%** |
|
|
| macOS stable tests | 15-18 min | 10-12 min | **30-35%** |
|
|
| Windows stable tests | 18-22 min | 12-15 min | **30-35%** |
|
|
| Full matrix (3 platforms) | 45-55 min | 30-37 min | **30-35%** |
|
|
|
|
### Developer Experience Improvements
|
|
|
|
| Workflow | Current | Projected | Impact |
|
|
|----------|---------|-----------|--------|
|
|
| Fix gfx bug → test | 3-4 min | 45-60 sec | **Much faster iteration** |
|
|
| Add zelda3 feature → test | 2-3 min | 30-45 sec | **Rapid prototyping** |
|
|
| Modify test → verify | 60-90 sec | 20-30 sec | **Tight feedback loop** |
|
|
| CLI-only development | Rebuilds GUI! | No GUI rebuild | **Isolated development** |
|
|
|
|
---
|
|
|
|
## 8. Detailed Library Specifications
|
|
|
|
### 8.1 Foundation Libraries
|
|
|
|
#### yaze_common
|
|
|
|
**Purpose**: Platform definitions, common macros
|
|
**Location**: `src/common/`
|
|
**Source Files**: (header-only)
|
|
**Dependencies**: None
|
|
**Dependents**: All libraries (foundation)
|
|
**Build Impact**: Header-only, minimal
|
|
**Priority**: N/A (stable)
|
|
|
|
#### yaze_util
|
|
|
|
**Purpose**: Logging, file I/O, SDL utilities
|
|
**Location**: `src/util/`
|
|
**Source Files**: 8-10 .cc files
|
|
**Dependencies**: yaze_common, absl, SDL2
|
|
**Dependents**: All libraries
|
|
**Build Impact**: Changes trigger rebuild of EVERYTHING
|
|
**Priority**: N/A (stable, rarely changes)
|
|
|
|
### 8.2 Graphics Libraries
|
|
|
|
#### yaze_gfx_types
|
|
|
|
**Purpose**: SNES color/palette/tile data structures
|
|
**Location**: `src/app/gfx/types/`
|
|
**Source Files**: 3 .cc files
|
|
**Dependencies**: None (foundation)
|
|
**Dependents**: gfx_core, gfx_util
|
|
**Build Impact**: Medium (4-6 libs)
|
|
**Priority**: DONE (refactored)
|
|
|
|
#### yaze_gfx_backend
|
|
|
|
**Purpose**: SDL2 renderer abstraction
|
|
**Location**: `src/app/gfx/backend/`
|
|
**Source Files**: 1 .cc file
|
|
**Dependencies**: SDL2
|
|
**Dependents**: gfx_resource, gfx_render
|
|
**Build Impact**: Low (2-3 libs)
|
|
**Priority**: DONE (refactored)
|
|
|
|
#### yaze_gfx_resource
|
|
|
|
**Purpose**: Memory management (Arena)
|
|
**Location**: `src/app/gfx/resource/`
|
|
**Source Files**: 2 .cc files
|
|
**Dependencies**: gfx_backend, gfx_render (BackgroundBuffer)
|
|
**Dependents**: gfx_core
|
|
**Build Impact**: Medium (3-4 libs)
|
|
**Priority**: DONE (refactored)
|
|
**Note**: Fixed BackgroundBuffer constructor issue in this PR
|
|
|
|
#### yaze_gfx_core
|
|
|
|
**Purpose**: Bitmap class
|
|
**Location**: `src/app/gfx/core/`
|
|
**Source Files**: 1 .cc file
|
|
**Dependencies**: gfx_types, gfx_resource
|
|
**Dependents**: gfx_util, gfx_render, gui_canvas
|
|
**Build Impact**: High (8+ libs)
|
|
**Priority**: DONE (refactored)
|
|
|
|
#### yaze_gfx_render
|
|
|
|
**Purpose**: Advanced rendering (Atlas, BackgroundBuffer)
|
|
**Location**: `src/app/gfx/render/`
|
|
**Source Files**: 4 .cc files
|
|
**Dependencies**: gfx_core, gfx_backend
|
|
**Dependents**: gfx_debug, zelda3
|
|
**Build Impact**: Medium (5-7 libs)
|
|
**Priority**: DONE (refactored)
|
|
|
|
#### yaze_gfx_util
|
|
|
|
**Purpose**: Compression, format conversion
|
|
**Location**: `src/app/gfx/util/`
|
|
**Source Files**: 4 .cc files
|
|
**Dependencies**: gfx_core
|
|
**Dependents**: gfx_debug, editor
|
|
**Build Impact**: Medium (4-6 libs)
|
|
**Priority**: DONE (refactored)
|
|
|
|
#### yaze_gfx_debug
|
|
|
|
**Purpose**: Performance profiling, optimization
|
|
**Location**: `src/app/gfx/debug/`
|
|
**Source Files**: 3 .cc files
|
|
**Dependencies**: gfx_util, gfx_render
|
|
**Dependents**: editor (optional)
|
|
**Build Impact**: Low (1-2 libs)
|
|
**Priority**: DONE (refactored)
|
|
|
|
### 8.3 GUI Libraries
|
|
|
|
#### yaze_gui_core
|
|
|
|
**Purpose**: Theme, input, style management
|
|
**Location**: `src/app/gui/core/`
|
|
**Source Files**: 7 .cc files
|
|
**Dependencies**: yaze_util, ImGui, nlohmann_json
|
|
**Dependents**: All other GUI libs
|
|
**Build Impact**: High (8+ libs)
|
|
**Priority**: DONE (refactored)
|
|
|
|
#### yaze_gui_canvas
|
|
|
|
**Purpose**: Drawable canvas with pan/zoom
|
|
**Location**: `src/app/gui/canvas/`
|
|
**Source Files**: 9 .cc files
|
|
**Dependencies**: gui_core, yaze_gfx
|
|
**Dependents**: editor (all editors use Canvas)
|
|
**Build Impact**: Very High (10+ libs)
|
|
**Priority**: DONE (refactored)
|
|
|
|
#### yaze_gui_widgets
|
|
|
|
**Purpose**: Reusable UI widgets
|
|
**Location**: `src/app/gui/widgets/`
|
|
**Source Files**: 6 .cc files
|
|
**Dependencies**: gui_core, yaze_gfx
|
|
**Dependents**: editor
|
|
**Build Impact**: Medium (5-7 libs)
|
|
**Priority**: DONE (refactored)
|
|
|
|
#### yaze_gui_automation
|
|
|
|
**Purpose**: Widget discovery, state capture, testing
|
|
**Location**: `src/app/gui/automation/`
|
|
**Source Files**: 4 .cc files
|
|
**Dependencies**: gui_core
|
|
**Dependents**: gui_app, agent (GUI automation)
|
|
**Build Impact**: Low (2-3 libs)
|
|
**Priority**: DONE (refactored)
|
|
|
|
#### yaze_gui_app
|
|
|
|
**Purpose**: High-level app components (chat, collaboration)
|
|
**Location**: `src/app/gui/app/`
|
|
**Source Files**: 4 .cc files
|
|
**Dependencies**: gui_core, gui_widgets, gui_automation
|
|
**Dependents**: editor
|
|
**Build Impact**: Low (1-2 libs)
|
|
**Priority**: DONE (refactored)
|
|
|
|
### 8.4 Game Logic Libraries
|
|
|
|
#### yaze_zelda3 (Current)
|
|
|
|
**Purpose**: All Zelda3 game logic
|
|
**Location**: `src/app/zelda3/` Warning: (wrong location)
|
|
**Source Files**: 21 .cc files (monolithic)
|
|
**Dependencies**: yaze_gfx, yaze_util
|
|
**Dependents**: core_lib, editor, agent
|
|
**Build Impact**: Very High (any change rebuilds 8+ libs)
|
|
**Priority**: HIGH (refactor per B6) 🔴
|
|
**Issues**:
|
|
- Wrong location (should be `src/zelda3/`)
|
|
- Monolithic (should be 6 sub-libraries)
|
|
|
|
#### yaze_zelda3_core (Proposed)
|
|
|
|
**Purpose**: Labels, constants, common data
|
|
**Location**: `src/zelda3/` (after move)
|
|
**Source Files**: 3-4 .cc files
|
|
**Dependencies**: yaze_util
|
|
**Dependents**: All other zelda3 libs
|
|
**Build Impact**: High (if changed, rebuilds all zelda3)
|
|
**Priority**: HIGH (implement B6) 🔴
|
|
|
|
#### yaze_zelda3_sprite (Proposed)
|
|
|
|
**Purpose**: Sprite management
|
|
**Location**: `src/zelda3/sprite/`
|
|
**Source Files**: 3 .cc files
|
|
**Dependencies**: zelda3_core
|
|
**Dependents**: zelda3_dungeon, zelda3_overworld
|
|
**Build Impact**: Medium (2-3 libs)
|
|
**Priority**: HIGH (implement B6) 🔴
|
|
|
|
#### yaze_zelda3_dungeon (Proposed)
|
|
|
|
**Purpose**: Dungeon system
|
|
**Location**: `src/zelda3/dungeon/`
|
|
**Source Files**: 7 .cc files
|
|
**Dependencies**: zelda3_core, zelda3_sprite
|
|
**Dependents**: zelda3_screen, editor_dungeon
|
|
**Build Impact**: Low (1-2 libs)
|
|
**Priority**: HIGH (implement B6) 🔴
|
|
|
|
#### yaze_zelda3_overworld (Proposed)
|
|
|
|
**Purpose**: Overworld system
|
|
**Location**: `src/zelda3/overworld/`
|
|
**Source Files**: 2 .cc files
|
|
**Dependencies**: zelda3_core, zelda3_sprite
|
|
**Dependents**: zelda3_screen, editor_overworld
|
|
**Build Impact**: Low (1-2 libs)
|
|
**Priority**: HIGH (implement B6) 🔴
|
|
|
|
#### yaze_zelda3_screen (Proposed)
|
|
|
|
**Purpose**: Game screens (title, inventory, map)
|
|
**Location**: `src/zelda3/screen/`
|
|
**Source Files**: 4 .cc files
|
|
**Dependencies**: zelda3_dungeon, zelda3_overworld
|
|
**Dependents**: editor_screen
|
|
**Build Impact**: Very Low (1 lib)
|
|
**Priority**: HIGH (implement B6) 🔴
|
|
|
|
#### yaze_zelda3_music (Proposed)
|
|
|
|
**Purpose**: Legacy music tracker
|
|
**Location**: `src/zelda3/music/`
|
|
**Source Files**: 1 .cc file (legacy C code)
|
|
**Dependencies**: zelda3_core
|
|
**Dependents**: editor_music
|
|
**Build Impact**: Very Low (1 lib)
|
|
**Priority**: HIGH (implement B6) 🔴
|
|
|
|
### 8.5 Core System Libraries
|
|
|
|
#### yaze_core_lib (Current)
|
|
|
|
**Purpose**: ROM, window, asar, project, services
|
|
**Location**: `src/app/core/`
|
|
**Source Files**: 10+ .cc files (mixed concerns) Warning:
|
|
**Dependencies**: yaze_util, yaze_gfx, yaze_zelda3, ImGui, asar, SDL2, [gRPC]
|
|
**Dependents**: editor, agent, emulator, net
|
|
**Build Impact**: Very High (10+ libs)
|
|
**Priority**: MEDIUM (split into foundation + services) 🟡
|
|
**Issues**:
|
|
- Mixed concerns (foundation vs services)
|
|
- Potential circular dependency with gfx
|
|
|
|
#### yaze_core_foundation (Proposed)
|
|
|
|
**Purpose**: ROM, window, asar, platform utilities
|
|
**Location**: `src/app/core/`
|
|
**Source Files**: 6-7 .cc files
|
|
**Dependencies**: yaze_util, yaze_common, asar, SDL2
|
|
**Dependents**: core_services, emulator, agent_core
|
|
**Build Impact**: Medium (5-7 libs)
|
|
**Priority**: MEDIUM (implement section 4.2.D) 🟡
|
|
|
|
#### yaze_core_services (Proposed)
|
|
|
|
**Purpose**: Project, controller, gRPC services
|
|
**Location**: `src/app/core/`
|
|
**Source Files**: 4-5 .cc files
|
|
**Dependencies**: core_foundation, yaze_gfx, yaze_zelda3, ImGui, [gRPC]
|
|
**Dependents**: editor, agent_services
|
|
**Build Impact**: Medium (4-6 libs)
|
|
**Priority**: MEDIUM (implement section 4.2.D) 🟡
|
|
|
|
#### yaze_emulator
|
|
|
|
**Purpose**: SNES emulation (CPU, PPU, APU)
|
|
**Location**: `src/app/emu/`
|
|
**Source Files**: 30+ .cc files
|
|
**Dependencies**: yaze_util, yaze_common, yaze_core_lib, absl, SDL2
|
|
**Dependents**: editor, agent (emulator commands)
|
|
**Build Impact**: Medium (3-5 libs)
|
|
**Priority**: LOW (stable)
|
|
**Note**: Fixed missing core_lib dependency in this PR
|
|
|
|
#### yaze_net
|
|
|
|
**Purpose**: Networking, collaboration
|
|
**Location**: `src/app/net/`
|
|
**Source Files**: 3 .cc files
|
|
**Dependencies**: yaze_util, yaze_common, absl, [OpenSSL], [gRPC]
|
|
**Dependents**: gui (collaboration panel)
|
|
**Build Impact**: Low (1-2 libs)
|
|
**Priority**: LOW (stable)
|
|
|
|
### 8.6 Application Layer Libraries
|
|
|
|
#### yaze_editor
|
|
|
|
**Purpose**: All editor functionality
|
|
**Location**: `src/app/editor/`
|
|
**Source Files**: 45+ .cc files (large, complex)
|
|
**Dependencies**: core_lib, gfx, gui, zelda3, emulator, util, common, ImGui, [agent], [test_support]
|
|
**Dependents**: test_support, yaze app
|
|
**Build Impact**: Very High (ANY change affects main app + tests)
|
|
**Priority**: LOW-FUTURE (modularize per section 4.3.F) 🔵
|
|
**Issues**:
|
|
- Too many dependencies (8+ major libs)
|
|
- Circular dependency with test_support
|
|
|
|
#### yaze_agent (Current)
|
|
|
|
**Purpose**: CLI functionality, AI services
|
|
**Location**: `src/cli/`
|
|
**Source Files**: 60+ .cc files (massive) Warning:
|
|
**Dependencies**: common, util, gfx, gui, core_lib, zelda3, emulator, absl, yaml, ftxui, [gRPC], [JSON], [OpenSSL]
|
|
**Dependents**: editor (agent integration), z3ed
|
|
**Build Impact**: Very High (15+ libs)
|
|
**Priority**: MEDIUM (split into core + services) 🟡
|
|
**Issues**:
|
|
- Links to entire application stack
|
|
- CLI tool rebuilds on GUI changes
|
|
|
|
#### yaze_agent_core (Proposed)
|
|
|
|
**Purpose**: Minimal CLI (commands, TUI, parsing)
|
|
**Location**: `src/cli/`
|
|
**Source Files**: 20-25 .cc files
|
|
**Dependencies**: common, util, ftxui, yaml
|
|
**Dependents**: agent_services, z3ed
|
|
**Build Impact**: Low (2-3 libs)
|
|
**Priority**: MEDIUM (implement section 4.2.E) 🟡
|
|
|
|
#### yaze_agent_services (Proposed)
|
|
|
|
**Purpose**: Full CLI features (AI, GUI automation, emulator)
|
|
**Location**: `src/cli/`
|
|
**Source Files**: 35-40 .cc files
|
|
**Dependencies**: agent_core, gfx, gui, core_lib, zelda3, emulator, [gRPC], [JSON], [OpenSSL]
|
|
**Dependents**: editor (agent integration), z3ed (optional)
|
|
**Build Impact**: High (10+ libs)
|
|
**Priority**: MEDIUM (implement section 4.2.E) 🟡
|
|
|
|
#### yaze_test_support (Current)
|
|
|
|
**Purpose**: Test manager + test suites
|
|
**Location**: `src/app/test/`
|
|
**Source Files**: 2 .cc files (mixed concerns) Warning:
|
|
**Dependencies**: editor, core_lib, gui, zelda3, gfx, util, common, agent
|
|
**Dependents**: editor (CIRCULAR Warning:), all test executables
|
|
**Build Impact**: Very High (10+ libs)
|
|
**Priority**: HIGH (separate per A2) 🔴
|
|
**Issues**:
|
|
- Circular dependency with editor
|
|
- Cannot exclude from release builds
|
|
- Mixes core logic with GUI
|
|
|
|
#### yaze_test_framework (Proposed)
|
|
|
|
**Purpose**: Core test infrastructure (no GUI)
|
|
**Location**: `src/test/framework/`
|
|
**Source Files**: 1 .cc file
|
|
**Dependencies**: yaze_util, absl
|
|
**Dependents**: test_suites, test_dashboard
|
|
**Build Impact**: Low (2-3 libs)
|
|
**Priority**: HIGH (implement A2) 🔴
|
|
|
|
#### yaze_test_suites (Proposed)
|
|
|
|
**Purpose**: Actual test implementations
|
|
**Location**: `src/test/suites/`
|
|
**Source Files**: 1 .cc file
|
|
**Dependencies**: test_framework, specific yaze libs (what's being tested)
|
|
**Dependents**: test executables
|
|
**Build Impact**: Low (1-2 libs per suite)
|
|
**Priority**: HIGH (implement A2) 🔴
|
|
|
|
#### yaze_test_dashboard (Proposed)
|
|
|
|
**Purpose**: In-app test GUI (optional)
|
|
**Location**: `src/app/gui/testing/`
|
|
**Source Files**: 1-2 .cc files
|
|
**Dependencies**: test_framework, yaze_gui
|
|
**Dependents**: yaze app (conditionally)
|
|
**Build Impact**: Low (1 lib)
|
|
**Priority**: HIGH (implement A2) 🔴
|
|
**Conditional**: `YAZE_WITH_TEST_DASHBOARD=ON`
|
|
|
|
---
|
|
|
|
## 9. References & Related Documents
|
|
|
|
### Primary Documents
|
|
|
|
- **C4-z3ed-refactoring.md**: CLI command abstraction (COMPLETED )
|
|
- **B6-zelda3-library-refactoring.md**: Zelda3 move & decomposition (PROPOSED 🔴)
|
|
- **A2-test-dashboard-refactoring.md**: Test infrastructure separation (PROPOSED 🔴)
|
|
- **This Document (A1)**: Comprehensive dependency analysis (NEW 📄)
|
|
|
|
### Related Refactoring Documents
|
|
|
|
- **docs/gfx-refactor.md**: Graphics tier decomposition (COMPLETED )
|
|
- **docs/gui-refactor.md**: GUI tier decomposition (COMPLETED )
|
|
- **docs/G3-renderer-migration-complete.md**: Renderer abstraction (COMPLETED )
|
|
|
|
### Build System Documentation
|
|
|
|
- **Root CMakeLists.txt**: Main build configuration
|
|
- **src/CMakeLists.txt**: Library orchestration
|
|
- **test/CMakeLists.txt**: Test suite configuration
|
|
- **scripts/build_cleaner.py**: Automated source list maintenance
|
|
|
|
### Architecture Documentation
|
|
|
|
- **docs/CLAUDE.md**: Project overview and guidelines
|
|
- **docs/B2-platform-compatibility.md**: Platform notes, Windows Clang
|
|
workarounds, and CI/CD guidance
|
|
- **docs/B4-git-workflow.md**: Git workflow and branching
|
|
|
|
### External Resources
|
|
|
|
- [CMake Documentation](https://cmake.org/documentation/)
|
|
- [Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html)
|
|
- [Abseil C++ Libraries](https://abseil.io/)
|
|
- [SDL2 Documentation](https://wiki.libsdl.org/)
|
|
- [ImGui Documentation](https://github.com/ocornut/imgui)
|
|
|
|
---
|
|
|
|
## 10. Conclusion
|
|
|
|
This document provides a comprehensive analysis of YAZE's dependency architecture and proposes a clear roadmap for optimization. The key takeaways are:
|
|
|
|
1. **Current State**: Complex interdependencies causing slow builds
|
|
2. **Root Causes**: Circular dependencies, over-linking, misplaced components
|
|
3. **Solution**: Execute existing proposals (A2, B6) + new splits (core_lib, agent)
|
|
4. **Expected Impact**: 40-60% faster incremental builds, cleaner architecture
|
|
5. **Timeline**: 6-7 weeks for complete refactoring
|
|
|
|
By following this roadmap, YAZE will achieve:
|
|
- Faster development iteration
|
|
- Cleaner architecture
|
|
- Better testability
|
|
- Easier maintenance
|
|
- Improved CI/CD performance
|
|
|
|
The proposed changes are backwards-compatible and can be implemented incrementally without disrupting ongoing development.
|
|
|
|
---
|
|
|
|
**Document Version**: 1.0
|
|
**Last Updated**: 2025-10-13
|
|
**Maintainer**: YAZE Development Team
|
|
**Status**: Living Document (update as architecture evolves)
|