C++ Insights: Perceiving Code Through the Compiler's Lens

C++ Insights is a specialized tool built upon the Clang framework that performs source-to-source transformation. Its primary objective is to peel back the curtain on the implicit operations that the C++ compiler performs automatically.

The core mission of C++ Insights is to render visible the "magic" that typically happens behind the scenes to make our code functional.

Understanding the Transformation

In standard development, we write concise code, but the compiler sees something much more verbose. Mathematically, we can view this as a transformation function: $\text{Source}_{\text{concise}} \xrightarrow{\text{C++ Insights}} \text{Source}_{\text{expanded}}$

Consider this basic snippet:

class Base { }; 
class Derived : public Base { }; 

int main () { 
    Derived d; 
    Derived d2 = d; 
    d2 = d; 
    Base b = d; 
}

While the above looks simple, the compiler actually processes it as follows:

class Base { 
public: 
    // inline constexpr Base() noexcept = default; 
    // inline constexpr Base(const Base ) noexcept = default; 
    // inline constexpr Base operator=(const Base ) noexcept = default; 
}; 

class Derived : public Base { 
public: 
    // inline constexpr Derived() noexcept = default; 
    // inline constexpr Derived(const Derived ) noexcept = default; 
    // inline constexpr Derived operator=(const Derived ) noexcept = default; 
}; 

int main () { 
    Derived d; 
    Derived d2 = Derived (d); 
    d2.operator =(d); 
    Base b = static_cast<Base>(d); 
    return 0 ; 
}

By using this tool, hidden implicit special member functions and static_cast upcasts become explicitly visible.

---

The Motivation: Why This Tool Exists?

The creator began exploring the advancements of C++11, C++14, and C++17 in 2017. While features like structured bindings, lambdas, and range-based for-loops are powerful, they can be opaque.

The Problem with Existing Tools:

• ASTs (Abstract Syntax Trees): Too abstract for most learners.
• Compiler Explorer: Shows assembly, which is not the language C++ developers write in.

C++ Insights fills this gap by transforming high-level syntax into the "compiler-internal" version of C++. It reveals exactly where auto is resolved, how lambdas are expanded, and where operators are triggered.

Tooling Workflow

---

Technical Implementation & Building

C++ Insights relies heavily on Clang's understanding of the AST. It is currently being updated to support C++20 features.

Build Options Summary

Detailed Build Instructions

1. Arch Linux Specifics

To avoid conflicts between libclangAST.so and libLLVM*.a (as detailed in Arch Bug #60512), use these flags:

• -DINSIGHTS_USE_SYSTEM_INCLUDES=off
• -DCLANG_LINK_CLANG_DYLIB=on
• -DLLVM_LINK_LLVM_DYLIB=on

2. Building Outside the Clang Tree

Ensure Clang is installed and accessible in your path, then run:

git clone https://github.com/andreasfertig/cppinsights.git
mkdir build && cd build
cmake -G"Ninja" ../cppinsights
ninja

The resulting executable is named insights.

3. Building Inside the Clang Tree

The most efficient method is utilizing the LLVM_EXTERNAL_PROJECTS option:

git clone https://github.com/llvm/llvm-project.git
git clone https://github.com/andreasfertig/cppinsights.git
mkdir build && cd build
cmake -G Ninja -DCMAKE_BUILD_TYPE=Release \
      -DLLVM_EXTERNAL_PROJECTS=cppinsights \
      -DLLVM_EXTERNAL_CPPINSIGHTS_SOURCE_DIR=PATH/TO/cppinsights

---

Project Status & Contribution

• Basic source-to-source transformation
• Support for C++11/14/17
• Full C++20 feature parity (In Progress)

If you are interested in helping, please check the CONTRIBUTING.md and CODE_OF_CONDUCT.md files in the repository. Support is also available via Patreon.