# Dependency & Build Overview

_Last reviewed: November 2025. All information in this document is derived from the current
`src/CMakeLists.txt` tree and shipped presets._

This guide explains how the major YAZE libraries fit together, which build switches control
them, and when a code change actually forces a full rebuild. It is intentionally concise so you
can treat it as a quick reference while editing.

## Build Switches & Presets

| CMake option | Default | Effect |
| --- | --- | --- |
| `YAZE_BUILD_APP` | `ON` | Build the main GUI editor (`yaze`). Disable when you only need CLI/tests. |
| `YAZE_BUILD_Z3ED` | `ON` | Build the `z3ed` automation tool and supporting agent libraries. |
| `YAZE_BUILD_EMU` | `OFF` | Build the standalone emulator binary. Always enabled inside the GUI build. |
| `YAZE_BUILD_TESTS` | `ON` in `*-dbg` presets | Compiles test helpers plus `yaze_test`. Required for GUI test dashboard. |
| `YAZE_ENABLE_GRPC` | `OFF` | Pulls in gRPC/protobuf for automation and remote control features. |
| `YAZE_MINIMAL_BUILD` | `OFF` | Skips optional editors/assets. Useful for CI smoke builds. |
| `YAZE_BUILD_LIB` | `OFF` | Produces the `yaze_core` INTERFACE target used by external tooling. |
| `YAZE_BUILD_AGENT_UI` | `ON` when `YAZE_BUILD_GUI` is `ON` | Compiles ImGui chat widgets. Disable for lighter GUI builds. |
| `YAZE_ENABLE_REMOTE_AUTOMATION` | `OFF` in `win-*` core presets | Builds gRPC servers/clients plus proto generation. |
| `YAZE_ENABLE_AI_RUNTIME` | `OFF` in `win-*` core presets | Enables Gemini/Ollama transports, proposal planning, and advanced routing code. |
| `YAZE_ENABLE_AGENT_CLI` | `ON` when `YAZE_BUILD_CLI` is `ON` | Compiles the conversational agent stack used by `z3ed`. |

Use the canned presets from `CMakePresets.json` so these options stay consistent across
platforms: `mac-dbg`, `mac-ai`, `lin-dbg`, `win-dbg`, etc. The `*-ai` presets enable both
`YAZE_BUILD_Z3ED` and `YAZE_ENABLE_GRPC` so the CLI and agent features match what ships.

## Library Layers

### 1. Foundation (`src/util`, `incl/`)
- **`yaze_common`**: cross-platform macros, generated headers, and lightweight helpers shared by
  every other target.
- **`yaze_util`**: logging, file I/O, BPS patch helpers, and the legacy flag system. Only depends
  on `yaze_common` plus optional gRPC/Abseil symbols.
- **Third-party**: SDL2, ImGui, Abseil, yaml-cpp, FTXUI, Asar. They are configured under
  `cmake/dependencies/*.cmake` and linked where needed.

Touching headers in this layer effectively invalidates most of the build. Keep common utilities
stable and prefer editor-specific helpers instead of bloating `yaze_util`.

### 2. Graphics & UI (`src/app/gfx`, `src/app/gui`)
- **`yaze_gfx`**: bitmap containers, palette math, deferred texture arena, canvas abstractions.
  Depends on SDL2 + `yaze_util`.
- **`yaze_gui`**: shared ImGui widgets, docking layout utilities, and theme plumbing. Depends on
  ImGui + `yaze_gfx`.

Changes here rebuild all editors but do not touch the lower-level Zelda 3 logic. Use the graphics
layer for rendering and asset streaming primitives; keep domain logic in the Zelda 3 library.

### 3. Game Domain (`src/zelda3`, `src/app/editor`)
- **`yaze_zelda3`**: map/room/sprite models, parsers, and ROM serialization. It links
  `yaze_gfx`, `yaze_util`, and Abseil.
- **`yaze_editor`**: ImGui editors (overworld, dungeon, palette, etc.). Depends on
  `yaze_gui`, `yaze_zelda3`, `yaze_gfx`, and optional agent/test hooks.
- **`yaze_emulator`**: CPU, PPU, and APU subsystems plus the debugger UIs (`src/app/emu`). The GUI
  app links this to surface emulator panels.

Touching Zelda 3 headers triggers rebuilds of the editor and CLI but leaves renderer-only changes
alone. Touching editor UI code does **not** require rebuilding `yaze_emulator`.

### 4. Tooling & Export Targets
- **`yaze_agent`** (`src/cli/agent`): shared logic behind the CLI and AI workflows. Built whenever
  `YAZE_ENABLE_AGENT_CLI` is enabled (automatically true when `YAZE_BUILD_Z3ED=ON`). When both the CLI and the agent UI are disabled, CMake now emits a lightweight stub target so GUI-only builds don't drag in unnecessary dependencies.
- **`z3ed` binary** (`src/cli/z3ed.cmake`): links `yaze_agent`, `yaze_zelda3`, `yaze_gfx`, and
  Abseil/FTXUI.
- **`yaze_core_lib`** (`src/core`): static library that exposes project management helpers and the
  Asar integration. When `YAZE_BUILD_LIB=ON` it can be consumed by external tools.
- **`yaze_test_support`** (`src/app/test`): harness for the in-editor dashboard and `yaze_test`.
- **`yaze_grpc_support`**: server-only aggregation of gRPC/protobuf code, gated by `YAZE_ENABLE_REMOTE_AUTOMATION`. CLI clients (`cli/service/gui/**`, `cli/service/planning/**`) now live solely in `yaze_agent` so GUI builds can opt out entirely.

### 5. Final Binaries
- **`yaze`**: GUI editor. Links every layer plus `yaze_test_support` when tests are enabled.
- **`yaze_test`**: GoogleTest runner (unit, integration, e2e). Built from `test/CMakeLists.txt`.
- **`z3ed`**: CLI + TUI automation tool. Built when `YAZE_BUILD_Z3ED=ON`.
- **`yaze_emu`**: optional standalone emulator for fast boot regression tests.

## Rebuild Cheatsheet

| Change | Targets Affected |
| --- | --- |
| `src/util/*.h` or `incl/yaze/*.h` | Everything (foundation dependency) |
| `src/app/gfx/**` | `yaze_gfx`, `yaze_gui`, editors, CLI. Emulator core unaffected. |
| `src/zelda3/**` | All editors, CLI, tests. Rebuild does **not** touch renderer-only changes. |
| `src/app/editor/**` | GUI editor + CLI (shared panels). Emulator/test support untouched. |
| `src/app/emu/**` | Emulator panels + GUI app. CLI and Zelda 3 libraries unaffected. |
| `src/cli/**` | `yaze_agent`, `z3ed`. No impact on GUI/editor builds. |
| `src/app/test/**` | `yaze_test_support`, `yaze_test`, GUI app (only when tests enabled). |

Use this table when deciding whether to invalidate remote build caches or to schedule longer CI
runs. Whenever possible, localize changes to the upper layers to avoid rebuilding the entire
stack.

## Tips for Faster Iteration

1. **Leverage presets** – `cmake --build --preset mac-ai --target yaze` automatically enables
   precompiled headers and shared dependency trees.
2. **Split work by layer** – renderer bugs usually live in `yaze_gfx`; leave Zelda 3 logic alone
   unless you need ROM serialization tweaks.
3. **Turn off unused targets** – set `YAZE_BUILD_Z3ED=OFF` when working purely on GUI features to
   shave a few hundred object files.
4. **Test without ROMs** – `docs/public/developer/testing-without-roms.md` documents the mock ROM
   harness so you do not need to rebuild assets between iterations.
5. **See also** – for deep dives into refactors or planned changes, read the internal blueprints in
   `docs/internal/blueprints/` instead of bloating the public docs.