Cpp Build Systems

bear -- make -j

Or compiledb:

compiledb make -j

Bazel

bazel build //...
bazel run @hedron_compile_commands//:refresh_all

Bazel requires the hedron_compile_commands rule. If not configured, suggest the user add it; do NOT try to hand-edit BUILD files.

Build failure triage (you fix common ones, escalate the rest)

1. CMake "could not find package X" → likely missing find_package(X REQUIRED) cleanup or wrong CMAKEPREFIXPATH. Suggest: cmake -L .build to inspect, or pass -DX_DIR=....

1. Linker "undefined reference" → missing source in target or missing link library. Check target_link_libraries(...) lists everything.

1. "No such file: " → missing target_include_directories or system header missing. For system headers, suggest installing the dev package.

1. Configure step fails on macOS → often missing Command Line Tools: xcode-select --install.

1. Anything cryptic → escalate: dispatch the cpp-build-doctor subagent with the full error log.

1. Anything you have now failed to fix twice → escalate, even if it looked obvious. The first

diagnosis is yours; a second failed attempt at the same failure means your hypothesis is the problem, and fresh context beats another iteration on a wrong prior. (Fixing it on the first try and moving on is the expected path — this is a repeat-failure trigger, not a "always delegate build errors" rule. The Session Pulse hook independently nudges at ≥3 repeats; this fires earlier and is yours to honour.)

Multi-config builds (Debug + Release + Sanitizer)

Keep separate build dirs:

.build/debug
.build/release
.build/asan

This is critical for cpp-sanitizers skill — the sanitizer build is a separate config, not a flag toggle on the same build.

When the user has NO build system yet

Don't pick one for them. Ask:

• Single-file experiment → suggest plain CMake (most portable)
• Header-only library → suggest CMake INTERFACE target
• Existing autotools project → keep it; just add bear for compile_commands.json
• Bazel monorepo → it's a one-way door, only suggest if user already uses it elsewhere

Detection helper

Run bash ${CLAUDE_PLUGIN_ROOT}/scripts/cpp-detect.sh --target . to get a JSON summary of what's present. Used by the SessionStart hook to gate C/C++ skills.

References

• See cmake-reference.md for CMake idioms used in this codebase / project conventions.
• See meson-reference.md for Meson equivalents.
• See compile-commands-guide.md for the deep-dive on compile_commands.json semantics.

When NOT to invoke this skill

• Pure C/C++ language questions (use docs / Context7 instead)
• Build performance tuning — separate concern; use after the build works
• Cross-compilation — out of scope for harness-anchor; consult build system docs

Calibrated uncertainty

If you propose a build fix you haven't verified by running the build:

> "I believe the fix is `. Please run cmake -S . -B .build && cmake --build .build` and share the output before we mark this resolved."

Looking up tool errors

Unfamiliar CMake/Meson/Bazel error or missing-package message? Don't guess — invoke the docs-lookup skill, which encodes the canonical Context7 → WebSearch → calibrated-uncertainty fallback chain (with explicit "Context7 is unavailable" detection so you don't silently degrade to guessing).

Typical entry queries: cmake find_package, meson dependency, bazel cc_binary, exact error string in quotes.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Redtropig
• Source: Redtropig/harness-anchor
• License: MIT

Install and usage instructions live in the source repository linked above.