How andreasfertig/cppinsights works
Project Type & Purpose
• This is an open-source, command-line tool (“C++ Insights”) that uses Clang’s AST to perform a source-to-source transformation of C++ code (revealing compiler-injected constructs).
• It is not a web app or microservices system but a single binary built on modular C++ libraries, with extensive test suites, documentation generators, and deployment scripts.
Top-Level Components
a. CLI Frontend
• Entry point (main from CodeGenerator.cpp/ASTHelpers.cpp).
• Argument parsing (via LLVM/Clang command-line infrastructure).
• Dispatch to core engine.
b. Core Engine
• AST Helpers (ASTHelpers.*) – utilities to traverse/manipulate Clang AST.
• Insights Options & Static Strings (Insights*.h/.cpp) – centralized configuration, feature toggles.
• Lifetime/Number/Stack utilities (LifetimeTracker.cpp, NumberIterator.h, StackList.h).
c. Transformation Modules
• CfrontCodeGenerator.cpp – handles old-style conversion.
• CoroutinesCodeGenerator.cpp – coroutine lowering.
• CodeGenerator.* (and types) – orchestrates per-construct generators.
• OutputFormatHelper.* – formats the transformed AST back to C++ source.
d. Infrastructure & Utilities
• DPrint (debug/logging).
• Read/write configuration (InsightsOptions.def).
• Scripts (scripts/*.sh/.py) – CI checks, release, include path discovery, bash completion.
• CMakeLists.txt – build orchestration, external project integration.
e. External Dependencies
• Clang / LLVM libraries (libclangAST, libLLVM).
• Python (for docs post-processing).
• Bash (for shell scripts).
f. Documentation & Examples
• docs/ – Doxygen config, markdown guides, example transformations, OptionDocumentationGenerator.
• artwork/logo, style.css, header/footer for HTML.
g. Testing Harness
• tests/ – hundreds of feature tests, shell scripts (testSTDIN.sh, runTest.py), expected outputs.
• GitHub Actions workflow (ci.yml) for build, test, coverage (codecov).
Relationships & Data Flow
1) User invokes insights <file> [-- options] → CLI Frontend parses arguments.
2) CLI Frontend feeds the file and flags into the Core Engine.
3) Core Engine uses Clang AST to parse input, then hands over AST nodes to Transformation Modules.
4) Each Transformation Module applies specific source-to-source rules, building an internal representation of rewritten code.
5) OutputFormatHelper serializes the internal representation back to valid C++ code.
6) CLI Frontend writes the output to stdout or file.
7) Tests invoke the binary, capture stdout, compare against expected files.
8) Documentation generators scan InsightsOptions and examples to produce human-readable docs.
Architectural Patterns & Principles
• Modular design: each language feature transformation is a separate code generator plugin.
• Separation of concerns: parsing (Clang), transformation (Insights modules), formatting (OutputFormatHelper).
• Build-time extensibility: CMake plugins allow integration inside or outside LLVM projects.
• Extensive automation: CI/CD scripts for formatting, linting, coverage.
Technologies & Frameworks
• C++17 (with optional C++20 support flags)
• Clang/LLVM libraries
• CMake (with Ninja or Visual Studio generators)
• Python (docs post-processing, getinclude.py)
• Bash (autocomplete, CI scripts)
• Doxygen (API and option docs)
• GitHub Actions for CI
Final Recommendation
• Overlay CI/CD pipeline alongside: GitHub Actions → codecov.
• Extensibility points (e.g., how to add a new generator).