cmake-xray

cmake-xray ist ein Analyse- und Diagnosewerkzeug fuer CMake-basierte C++-Builds. Es liest compile_commands.json und optional CMake-File-API-Reply-Daten, rankt auffaellige Translation Units, leitet heuristische Include-Hotspots ab, analysiert Datei-Impact, zeigt betroffene Targets an und vergleicht zwei Analyze-JSON-Berichte. Ergebnisse werden als Konsolen-, Markdown-, JSON-, Graphviz-DOT- oder eigenstaendiger HTML-Report ausgegeben; JSON, DOT, HTML und Compare folgen den versionierten Vertraegen in spec/report-json.md, spec/report-dot.md, spec/report-html.md und spec/report-compare.md. Die ausgegebene App-Version ist via cmake-xray --version einzusehen; der historische Funktionsverlauf je Releaselinie steht in CHANGELOG.md.

Status

Der Funktionsumfang umfasst:

• CLI mit analyze, impact und compare
• Validierung von compile_commands.json
• deterministisches Translation-Unit-Ranking auf Basis von arg_count, include_path_count und define_count
• heuristische Include-Hotspots und dateibasierte Impact-Analyse
• CMake File API als optionale zweite Eingabequelle via --cmake-file-api
• Target-Zuordnung: Translation Units werden ihren CMake-Targets zugeordnet ([targets: app, core])
• targetbezogene Impact-Ausgabe mit direct, direct_dependent, transitive_dependent und heuristic Evidenzklassen
• Reverse-Target-Graph-Priorisierung ueber --impact-target-depth und harte Target-Graph-Anforderung ueber --require-target-graph
• Include-Filter ueber --include-scope und --include-depth
• Analyseauswahl und Schwellenwerte ueber --analysis, --tu-threshold, --min-hotspot-tus, --target-hub-in-threshold und --target-hub-out-threshold
• Vergleich zweier Analyze-JSON-Berichte ueber cmake-xray compare
• Analyse auch ohne compile_commands.json, wenn File-API-Daten ausreichen
• Report-Ausgabe als console, markdown, json, dot oder html
• atomisches Schreiben von Markdown-, JSON-, DOT- und HTML-Reports via --output
• versionierter, schemavalidierter JSON-Reportvertrag fuer Tooling und CI
• Graphviz-DOT-Visualisierung von Top-Ranking, Include-Hotspots, Targets und Impact-Beziehungen
• portabler, eigenstaendiger HTML5-Bericht mit inline CSS, ohne externe Ressourcen oder JavaScript
• versionierte Golden-Files, Referenzdaten und Performance-Baselines
• Docker-basierte Test-, Coverage- und Quality-Gates
• command-lokale CLI-Modi --quiet und --verbose an analyze und impact; gegenseitig exklusiv

Nicht Ziel des aktuellen Stands sind insbesondere:

• Ersatz fuer CMake
• vollstaendige CMake-Interpretation
• IDE-Integration

Voraussetzungen

Referenzplattform ist Linux mit:

• CMake >= 3.20
• C++20-faehigem Compiler
• Git fuer FetchContent

Mindestversionen sind in tests/platform/toolchain-minimums.json versioniert; CMake (3.20), GCC (10), Clang (12), AppleClang (13) und MSVC (19.29) werden beim Configure jeder Plattform fail-fast geprueft. Anhebungen laufen synchron ueber JSON, cmake_minimum_required, README und docs/user/guide.md.

Als reproduzierbare Referenzumgebung steht das Multi-Stage-Dockerfile zur Verfuegung.

Plattformstatus

M5 unterscheidet drei Statusklassen:

• supported — offiziell freigegeben, dokumentiert und releasefaehig.
• validated_smoke — Build-, Atomic-Replace- und CLI-Pflicht-Smokes laufen gruen, aber ohne offizielle Releasefreigabe.
• known_limited — ein Pflichtgate ist nicht vollstaendig gruen, fehlt oder der Status wird nur ueber dokumentierte Einschraenkungen erreicht.

Aktueller M5-Stand:

Plattform	Status
Linux x86_64	supported
macOS arm64	validated_smoke
Windows x86_64	validated_smoke

Linux ist die einzige offizielle Releaseplattform; macOS arm64 und Windows x86_64 sind seit 2026-04-30 als validated_smoke freigegeben, nachdem Branch-Protection auf main die Native (...)-Required-Checks verankert hat und build.yml run 25153798452 als gruener Post-Protection-Lauf auditiert ist. Die nativen Jobs fahren via ctest die Atomic-Replace- und CLI-Pflicht-Smokes (Tranchen B und C.1), die UNC/Extended-Length-Adaptertests (C.2) und auf Windows zusaetzlich den PowerShell-Pflicht-Smoke (D.1). Detaillierte Gate-Erklaerungen, Required-Check-Namen und die Atomic-Replace-Matrix stehen in docs/user/quality.md "Plattformstatus (AP M5-1.7)"; Release- und Preview-Grenzen in docs/user/releasing.md "Plattformartefakte macOS und Windows".

Installation und Ausfuehrung

Fuer normale Nutzung wird die CLI als cmake-xray aufgerufen. Releases stellen dafuer ein versioniertes Linux-CLI-Artefakt und ein OCI-kompatibles Container-Image bereit, damit Linux-Nutzer nicht auf interne Build-Pfade angewiesen sind. Nutzer auf macOS arm64 oder Windows x86_64 (validated_smoke) bauen das Binary direkt aus dem Source (siehe "Quellbuild aus Source" weiter unten); dieser Weg ist auf diesen Plattformen voll unterstuetzt und nicht nur "fuer Entwicklung".

Release-Artefakt entpacken:

tar -xzf cmake-xray_X.Y.Z_linux_x86_64.tar.gz
mkdir -p "$HOME/.local/bin"
install -m 0755 cmake-xray "$HOME/.local/bin/cmake-xray"
export PATH="$HOME/.local/bin:$PATH"
cmake-xray --help

Container-Image ziehen und verwenden:

docker pull ghcr.io/pt9912/cmake-xray:X.Y.Z
docker run --rm ghcr.io/pt9912/cmake-xray:X.Y.Z --help
docker run --rm ghcr.io/pt9912/cmake-xray:X.Y.Z --version

Dabei bezeichnet X.Y.Z die Release-Version ohne fuehrendes v; der OCI-Tag spiegelt die App-Version, der Git-Tag den Release-Anker (vX.Y.Z). Beide Werte sind ueber validate-release-tag.sh gegen das gleiche SemVer-Muster gepinnt (siehe docs/user/releasing.md).

Fuer regulaere Releases (kein Prerelease-Suffix) wird zusaetzlich der Tag :latest aktualisiert, sobald der versionierte Tag erfolgreich gepusht und der Digest validiert wurde:

docker pull ghcr.io/pt9912/cmake-xray:latest
docker run --rm ghcr.io/pt9912/cmake-xray:latest --version

Vorabversionen (-rc.N, -alpha.N usw.) bleiben auf ihren Versions-Tag beschraenkt und aktualisieren :latest nicht.

Quellbuild aus Source (Entwicklung auf jeder Plattform sowie unterstuetzter Nutzungsweg auf macOS arm64 und Windows x86_64):

make dev

Resultat:

• Linux/macOS: ./build/cmake-xray
• Windows (Visual-Studio-Generator): ./build/Release/cmake-xray.exe

Auf macOS und Windows wird die so gebaute Binary anschliessend wie ein installiertes cmake-xray in den PATH gelegt; auf Linux liefert das versionierte Release-Artefakt das supported Binary, der Quellbuild ist dort fuer Endnutzer-Aufrufe nicht empfohlen.

Runtime-Image bauen:

make runtime

Nutzung

Hilfe

cmake-xray --help
cmake-xray analyze --help
cmake-xray impact --help

Projektanalyse in der Konsole

cmake-xray analyze \
  --compile-commands tests/e2e/testdata/m3/report_project/compile_commands.json \
  --top 10

Projektanalyse als Markdown auf stdout

cmake-xray analyze \
  --compile-commands tests/e2e/testdata/m3/report_project/compile_commands.json \
  --format markdown \
  --top 10

Projektanalyse als Markdown-Datei

cmake-xray analyze \
  --compile-commands tests/e2e/testdata/m3/report_project/compile_commands.json \
  --format markdown \
  --output build/reports/analyze.md \
  --top 10

Projektanalyse als HTML-Datei

cmake-xray analyze \
  --compile-commands tests/e2e/testdata/m3/report_project/compile_commands.json \
  --format html \
  --output build/reports/analyze.html \
  --top 10

Die HTML-Ausgabe ist ein eigenstaendiges HTML5-Dokument mit inline CSS und ohne externe Ressourcen; es eignet sich als CI-Artefakt oder fuer Reviews ohne Browser-Plugins. Wird --output weggelassen, schreibt cmake-xray das Dokument vollstaendig auf stdout.

Impact-Analyse

cmake-xray impact \
  --compile-commands tests/e2e/testdata/m3/report_impact_header/compile_commands.json \
  --changed-file include/common/config.h

Impact-Analyse als Markdown

cmake-xray impact \
  --compile-commands tests/e2e/testdata/m3/report_impact_header/compile_commands.json \
  --changed-file include/common/config.h \
  --format markdown \
  --output build/reports/impact.md

Analyse mit CMake File API (Target-Sicht)

cmake-xray analyze \
  --cmake-file-api build/.cmake/api/v1/reply

Als Wert fuer --cmake-file-api wird entweder das Build-Verzeichnis (mit .cmake/api/v1/reply darunter) oder direkt das Reply-Verzeichnis akzeptiert. Die Option ist fuer analyze und impact verfuegbar und kann allein oder zusammen mit --compile-commands verwendet werden.

Analyse mit Compile Database und File API (Mischpfad)

cmake-xray analyze \
  --compile-commands build/compile_commands.json \
  --cmake-file-api build

Im Mischpfad bleibt die Compile Database die autoritative Grundlage fuer Ranking, Hotspots und Impact. Die File API reichert passende Beobachtungen um Target-Kontext an.

Include-Filter und Schwellenwerte

cmake-xray analyze \
  --compile-commands build/compile_commands.json \
  --include-scope project \
  --include-depth direct \
  --tu-threshold include_path_count=2 \
  --min-hotspot-tus 3

--include-scope begrenzt Hotspots auf all, project oder external; --include-depth begrenzt auf all, direct oder indirect. --tu-threshold <metric>=<n> filtert Translation Units vor Ranking und --min-hotspot-tus filtert Include-Hotspots nach betroffenen Translation Units.

Analyseauswahl

cmake-xray analyze \
  --cmake-file-api build \
  --analysis tu-ranking,target-graph \
  --top 10

--analysis akzeptiert all, tu-ranking, include-hotspots, target-graph und target-hubs. target-hubs setzt target-graph voraus; deaktivierte Sections bleiben in JSON/HTML als Section-State sichtbar.

Impact-Analyse mit Target-Ausgabe

cmake-xray impact \
  --cmake-file-api build \
  --changed-file src/main.cpp

Bei geladener Target-Sicht zeigt impact zusaetzlich betroffene Targets mit Evidenzklassifikation. Die Reverse-Target-Graph-Tiefe ist per --impact-target-depth steuerbar:

cmake-xray impact \
  --cmake-file-api build \
  --changed-file src/main.cpp \
  --impact-target-depth 2

Wenn fehlende Target-Graph-Daten in CI ein harter Fehler sein sollen:

cmake-xray impact \
  --compile-commands build/compile_commands.json \
  --changed-file src/main.cpp \
  --require-target-graph

Analyze-Berichte vergleichen

cmake-xray compare \
  --baseline build/reports/analyze-before.json \
  --current build/reports/analyze-after.json \
  --format markdown \
  --output build/reports/analyze-diff.md

compare akzeptiert in M6 nur Analyze-JSON mit format_version=6 auf beiden Seiten. Die Kompatibilitaetsmatrix steht in spec/compare-matrix.md; der Compare-JSON- Vertrag in spec/report-compare.md.

Pfadaufloesung fuer --changed-file

Relative --changed-file-Pfade werden relativ zum Verzeichnis der uebergebenen compile_commands.json interpretiert. Im File-API-Only-Pfad (ohne --compile-commands) werden sie relativ zum im Codemodel angegebenen Top-Level-Source-Verzeichnis interpretiert.

CLI-Modi: --quiet und --verbose

analyze und impact akzeptieren je --quiet und --verbose als command-lokale Flags. Beide sind gegenseitig exklusiv und muessen hinter dem Subcommand stehen; eine globale Position vor dem Subcommand wird abgelehnt.

cmake-xray analyze \
  --compile-commands tests/e2e/testdata/m3/report_project/compile_commands.json \
  --quiet --top 2

cmake-xray analyze \
  --compile-commands tests/e2e/testdata/m3/report_project/compile_commands.json \
  --verbose --top 2

--quiet reduziert den Console-Report auf wenige Pflichtzeilen und ist fuer Markdown, JSON, DOT und HTML reportinhaltlich ein Noop: stdout bleibt byte-stabil zum Normalmodus, geschriebene --output-Dateien sind byte-identisch zum Normalmodus, stderr bleibt im Erfolgsfall leer. --quiet unterdrueckt keine Fehler und veraendert keine Exit-Codes.

--verbose schreibt im Console-Modus zusaetzliche Diagnose-Sections nach stdout. Fuer Artefaktformate bleibt stdout byte-stabil zum Normalmodus, und ein zusaetzlicher verbose: ...-Block geht ausschliesslich nach stderr. Bei Fehlern ergaenzt --verbose die normale Fehlermeldung um vier verbose:-Zeilen mit command, format, output und validation_stage; Stacktraces oder C++-Typnamen werden nie ausgegeben.

Heuristik-Hinweis

Include-Hotspots und Header-Impact beruhen auf heuristischer Include-Aufloesung. cmake-xray kennzeichnet diese Ergebnisse explizit und gibt Datenluecken als Diagnostics aus. Direkte Treffer auf bekannte Quelldateien werden ohne heuristische Klassifikation ausgewiesen. Target-Aussagen erscheinen nur, wenn File-API-Daten ueber --cmake-file-api bereitgestellt werden.

Beispielausgaben

Kuratierte Beispielartefakte liegen unter [docs/examples](./docs/examples):

Ohne Target-Sicht (nur compile_commands.json):

• docs/examples/analyze-console.txt
• docs/examples/analyze-report.md
• docs/examples/analyze-report.html
• docs/examples/analyze-report.json
• docs/examples/analyze-report.dot
• docs/examples/impact-console.txt
• docs/examples/impact-report.md
• docs/examples/impact-report.html
• docs/examples/impact-report.json
• docs/examples/impact-report.dot

Mit Target-Sicht (File API, historische M4/M5-Beispiele):

• docs/examples/analyze-console-targets.txt
• docs/examples/analyze-report-targets.md
• docs/examples/analyze-report-targets.html
• docs/examples/analyze-report-targets.json
• docs/examples/analyze-report-targets.dot
• docs/examples/impact-console-targets.txt
• docs/examples/impact-report-targets.md
• docs/examples/impact-report-targets.html
• docs/examples/impact-report-targets.json
• docs/examples/impact-report-targets.dot

M6 Target-Graph, Include-Filter, Schwellenwerte und Compare:

• docs/examples/analyze-target-graph-loaded.txt
• docs/examples/analyze-target-graph-partial.txt
• docs/examples/analyze-include-scope-project.md
• docs/examples/analyze-include-depth-direct.md
• docs/examples/analyze-thresholds.md
• docs/examples/analyze-disabled-target-hubs.md
• docs/examples/impact-prioritised.md
• docs/examples/impact-require-target-graph-error.txt
• docs/examples/compare-typical.md
• docs/examples/compare-config-drift.md
• docs/examples/compare-project-identity-drift.md

Exit-Codes

Code	Bedeutung	Typischer Ausloeser
0	Erfolg	gueltige CLI-Verwendung und gueltige Eingabedaten
1	Laufzeit- oder Report-Schreibfehler	nicht beschreibbarer --output-Pfad, unerwarteter Fehler
2	CLI-Verwendungsfehler	unbekanntes Unterkommando, fehlendes Pflichtargument, ungueltige Optionskombination
3	Eingabedatei nicht lesbar	Datei fehlt, kein Zugriff, Pfad ungueltig; gilt auch fuer explizite --cmake-file-api-Pfade
4	Eingabedaten ungueltig	JSON fehlerhaft, kein Array, leer, Pflichtfelder fehlen; gilt auch fuer ungueltige oder strukturell unzureichende File-API-Reply-Daten

Tests und Quality Gates

Docker-basierte Referenzpfade ueber das Makefile:

make docker-gates
make runtime

Separat verfuegbare Reports:

make coverage-report
make quality-report

Performance-Baseline

Die versionierten Referenzprojekte liegen unter tests/reference. Die dokumentierte Baseline fuer scale_250, scale_500 und scale_1000 sowie die Impact-Stichprobe steht in docs/user/performance.md. Die zugehoerigen Messartefakte werden unter build/reports/performance/ erzeugt.

Dokumente

Weitere Dokumentation:

• spec/lastenheft.md
• docs/user/guide.md
• spec/design.md
• spec/architecture.md
• docs/planning/in-progress/roadmap.md
• docs/user/releasing.md
• docs/user/quality.md
• docs/user/performance.md

Lizenz

Das Projekt steht unter der MIT-Lizenz.

Changelog

Aenderungen werden in CHANGELOG.md dokumentiert.