| name | uni20-build-matrix |
| description | Run a machine-agnostic Uni20 configure/build/test matrix by detecting available compilers and applying a minimal coverage strategy. |
Uni20 Build Matrix
Overview
Run a compact but meaningful build matrix without assuming specific compiler install paths.
This skill is for compatibility checks, regressions, and release confidence. Keep matrix size proportional to the request.
Workflow
- Read
AGENTS.md, then .codex/instructions.local.md (if present).
- Detect available compilers on the current machine.
- Pick a minimal matrix that covers requested dimensions (compiler, build type, stacktrace/LTO toggles).
- Select an out-of-source build root from the local override, the user's
request, or a git-ignored default, then configure each cell under
<build-root>/<cell-name>.
- Summarize pass/fail per cell with failing targets/tests.
Compiler Detection
Prefer local toolchain overrides if documented. Otherwise auto-detect:
for cxx in g++ g++-16 g++-14 g++-13 clang++ clang++-21 clang++-20 clang++-19; do
command -v "$cxx" >/dev/null && echo "$cxx"
done | awk '!seen[$0]++'
Reject Clang versions below the supported Clang 19 floor. Prefer GCC 13 as the
compatibility baseline when it is available.
Matrix Construction Rules
- Always include one baseline cell (default compiler,
Debug).
- Add
Release when performance/packaging concerns are in scope.
- Add
UNI20_ENABLE_STACKTRACE=0 cell when async-debug/stacktrace behavior is relevant.
- Add
CMAKE_INTERPROCEDURAL_OPTIMIZATION=ON cell for LTO validation.
- Add second-compiler smoke cell only if another compiler is installed and requested.
Configure Templates
Baseline:
cmake -S . -B <build-root>/<cell-name> -DCMAKE_BUILD_TYPE=Debug
Compiler override:
cmake -S . -B <build-root>/<cell-name> \
-DCMAKE_C_COMPILER=<cc> \
-DCMAKE_CXX_COMPILER=<cxx> \
-DCMAKE_BUILD_TYPE=<Debug|Release>
Optional toggles:
-DUNI20_ENABLE_STACKTRACE=0-DCMAKE_INTERPROCEDURAL_OPTIMIZATION=ON
Build and Test
cmake --build <build-root>/<cell-name>
ctest --test-dir <build-root>/<cell-name> --output-on-failure
For quick smoke checks, run targeted tests first, then full ctest if requested.
Reporting Format
matrix: list of executed cells and optionsconfigure/build: pass/fail per celltests: pass/fail counts and failed test names per cellnotes: actionable follow-ups (cache cleanup, option conflict, compiler-specific failures)
