SYSTEM mode: misleading failures when host GCC/libstdc++ versions are incomplete (category B)

[lm-sousa]

Context

The system-header verification findings of 22 Aug 2026 separated SYSTEM-mode "file not found" errors into two independent causes:

• Category A (dumper-side) — missing Clang resource directory in relocated binaries. Already fixed in the dumper: fix: fall back to system Clang resource dir when default is missing clang-dumper#26 self-heals by discovering a matching-major system Clang resource dir and passing -resource-dir=. No Clava changes needed.
• Category B (host environment) — this issue.

The problem (F3 in the findings)

When parsing C++ in SYSTEM mode, Clang picks the newest installed GCC (gcc-N) and requires the matching libstdc++-N-dev headers. It does not fall back to an older, fully-installed GCC toolchain. So a machine with gcc-13 + a complete gcc-12/g++-12 fails on <string> after removing only libstdc++-13-dev, even though c++/12 headers are present and working.

This reproduces exactly (Ubuntu 24.04, clang 18): force-remove libstdc++-13-dev → 'string' file not found; reinstalling that single package fixes it immediately.

Historically these breakages were misdiagnosed: F2 shows installing libstdc++ packages can never repair a stddef.h failure — that was category A all along. Past fixes worked by accident or fixed only one of the two simultaneous errors.

What Clava should do

Per the findings' recommendations, Clava should diagnose, never paper over:

1. Separate the categories before parsing starts, with two cheap probes:
   • C probe (stddef.h) failing → artifact problem (now covered by dumper PR Invocation of base class' constructor doubled in initialisation list #26's own diagnostics).
   • C succeeding but C++ failing on <string> → user environment; the error should name the exact missing package (e.g. libstdc++-13-dev), not dump dozens of parse errors.
2. Reject unsupported combinations clearly: a libstdc++ newer than the supported/tested range should produce a single "unsupported combination" error instead of cascading parse errors.
3. Consider surfacing the probe result in AUTO mode: today the libc probe runs the dumper bare, so on hosts where category B is present it just silently falls back to bundled includes — reasonable, but the user never learns why their explicit SYSTEM-mode parse fails.

References

• Findings report: https://clava-system-header-findings-20260822.lmsousa.workers.dev/
• Dumper fix for category A (PR): fix: fall back to system Clang resource dir when default is missing clang-dumper#26
• Fix write-up with overhead numbers and diagrams: https://clava-issue-a-fix-report-20260822.lmsousa.workers.dev/

Relevant existing machinery in this repo: ClangResources.detectLibC / LibcMode probing, and findSystemClangResourceDir.