e36d81f357
Fixes linker error on Linux where yaze_gfx_debug.a (performance_dashboard.cc) was calling AtlasRenderer::Get() and AtlasRenderer::GetStats() but wasn't linking against yaze_gfx_render which contains atlas_renderer.cc. Root cause: yaze_gfx_debug was only linking to yaze_gfx_types and yaze_gfx_resource, missing the yaze_gfx_render dependency. This also fixes the undefined reference errors for HttpServer methods which were already properly included in the agent.cmake source list. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
69 lines
4.2 KiB
Markdown
69 lines
4.2 KiB
Markdown
# Build Performance & Agent-Friendly Tooling (November 2025)
|
||
|
||
Status: **Draft**
|
||
Owner: CODEX (open to CLAUDE/GEMINI participation)
|
||
|
||
## Goals
|
||
- Reduce incremental build times on all platforms by tightening target boundaries, isolating optional
|
||
components, and providing cache-friendly presets.
|
||
- Allow long-running or optional tasks (e.g., asset generation, documentation, verification scripts)
|
||
to run asynchronously or on-demand so agents don’t block on them.
|
||
- Provide monitoring/metrics hooks so agents and humans can see where build time is spent.
|
||
- Organize helper scripts (build, verification, CI triggers) so agents can call them predictably.
|
||
|
||
## Plan Overview
|
||
|
||
### 1. Library Scoping & Optional Targets
|
||
1. Audit `src/CMakeLists.txt` and per-module cmake files for broad `add_subdirectory` usage.
|
||
- Identify libraries that can be marked `EXCLUDE_FROM_ALL` and only built when needed (e.g.,
|
||
optional tools, emulator targets).
|
||
- Leverage `YAZE_MINIMAL_BUILD`, `YAZE_BUILD_Z3ED`, etc., but ensure presets reflect the smallest
|
||
viable dependency tree.
|
||
2. Split heavy modules (e.g., `app/editor`, `app/emu`) into more granular targets if they are
|
||
frequently touched independently.
|
||
3. Add caching hints (ccache, sccache) in the build scripts/presets for all platforms.
|
||
|
||
### 2. Background / Async Tasks
|
||
1. Move long-running scripts (asset bundling, doc generation, lints) into optional targets invoked by
|
||
a convenience meta-target (e.g., `yaze_extras`) so normal builds stay lean.
|
||
2. Provide `scripts/run-background-tasks.sh` that uses `nohup`/`start` to launch doc builds, GH
|
||
workflow dispatch, or other heavy processes asynchronously; log their status for monitoring.
|
||
3. Ensure CI workflows skip optional tasks unless explicitly requested (e.g., via workflow inputs).
|
||
|
||
### 3. Monitoring & Metrics
|
||
1. Add a lightweight timing report to `scripts/verify-build-environment.*` or a new
|
||
`scripts/measure-build.sh` that runs `cmake --build` with `--trace-expand`/`ninja -d stats` and
|
||
reports hotspots.
|
||
2. Integrate a summary step in CI (maybe a bash step) that records build duration per preset and
|
||
uploads as an artifact or comment.
|
||
3. Document how agents should capture metrics when running builds (e.g., use `time` wrappers, log
|
||
output to `logs/build_<preset>.log`).
|
||
|
||
### 4. Agent-Friendly Script Organization
|
||
1. Gather recurring helper commands into `scripts/agents/`:
|
||
- `run-gh-workflow.sh` (wrapper around `gh workflow run`)
|
||
- `smoke-build.sh <preset>` (configures & builds a preset in a dedicated directory, records time)
|
||
- `run-tests.sh <preset> <labels>` (standardizes test selections)
|
||
2. Provide short README in `scripts/agents/` explaining parameters, sample usage, and expected output
|
||
files for logging back to the coordination board.
|
||
3. Update `AGENTS.md` to reference these scripts so every persona knows the canonical tooling.
|
||
|
||
### 5. Deliverables / Tracking
|
||
- Update CMake targets/presets to reflect modular build improvements.
|
||
- New scripts under `scripts/agents/` + documentation.
|
||
- Monitoring notes in CI (maybe via job summary) and local scripts.
|
||
- Coordination board entries per major milestone (library scoping, background tooling, metrics,
|
||
script rollout).
|
||
|
||
## Dependencies / Risks
|
||
- Coordinate with CLAUDE_AIINF when touching presets or build scripts—they may modify the same files
|
||
for AI workflow fixes.
|
||
- When changing CMake targets, ensure existing presets still configure successfully (run verification
|
||
scripts + smoke builds on mac/linux/win).
|
||
- Adding background tasks/scripts should not introduce new global dependencies; use POSIX Bash and
|
||
PowerShell equivalents where required.
|
||
## Windows Stability Focus (New)
|
||
- **Tooling verification**: expand `scripts/verify-build-environment.ps1` to check for Visual Studio workload, Ninja, and vcpkg caches so Windows builds fail fast when the environment is incomplete.
|
||
- **CMake structure**: ensure optional components (HTTP API, emulator, CLI helpers) are behind explicit options and do not affect default Windows presets; verify each target links the right runtime/library deps even when `YAZE_ENABLE_*` flags change.
|
||
- **Preset validation**: add Windows smoke builds (Ninja + VS) to the helper scripts/CI so we can trigger focused runs when changes land.
|