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.

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.
Split heavy modules (e.g., app/editor, app/emu) into more granular targets if they are frequently touched independently.
Add caching hints (ccache, sccache) in the build scripts/presets for all platforms.

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.
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.
Ensure CI workflows skip optional tasks unless explicitly requested (e.g., via workflow inputs).

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.
Integrate a summary step in CI (maybe a bash step) that records build duration per preset and uploads as an artifact or comment.
Document how agents should capture metrics when running builds (e.g., use time wrappers, log output to logs/build_<preset>.log).

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)
Provide short README in scripts/agents/ explaining parameters, sample usage, and expected output files for logging back to the coordination board.
Update AGENTS.md to reference these scripts so every persona knows the canonical tooling.

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).

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.

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.