C++ Insights - See your source code with the eyes of a compiler
Switch branches/tags
Clone or download
andreasfertig Merge pull request #100 from andreasfertig/fixClang8Build
Add ConstantExpr which seems to be new in clang-8
Latest commit ee15034 Dec 1, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
artwork Generate documentation and upload it to andreasfertig.github.io Aug 31, 2018
docker_buildenv Update Dockerfile to clang-8 Aug 30, 2018
docker_travis CMake cleanup and added missing things. Oct 3, 2018
docs Generate documentation and upload it to andreasfertig.github.io Aug 31, 2018
scripts Fixed collecting code coverage info. Jun 23, 2018
tests Fixed lambda capturing this by copy. Nov 25, 2018
.clang-format Initial commit May 13, 2018
.travis.yml Add hostname to ssh known hosts Sep 29, 2018
AutoStmtHandler.cpp Rename FindLocationAfterToken and GetSourceRangeAfterToken. Nov 25, 2018
AutoStmtHandler.h AutoStmtHandler does also handle structured bindings. Jul 16, 2018
CMakeLists.txt Fixed #96: in-tree build does generate all necessary files. Dec 1, 2018
CODE_OF_CONDUCT.md Generate documentation and upload it to andreasfertig.github.io Aug 31, 2018
CONTRIBUTING.md Generate documentation and upload it to andreasfertig.github.io Aug 31, 2018
ClangCompat.h Added test for complex float and int. Nov 2, 2018
CodeGenerator.cpp Add ConstantExpr which seems to be new in clang-8 Dec 1, 2018
CodeGenerator.h Add ConstantExpr which seems to be new in clang-8 Dec 1, 2018
CodeGeneratorTypes.h Add ConstantExpr which seems to be new in clang-8 Dec 1, 2018
CompilerGeneratedHandler.cpp Dedicated function to insert indented text to keep repetitions low. Nov 25, 2018
CompilerGeneratedHandler.h Initial commit May 13, 2018
DPrint.cpp Add to_string to StrCat to get rid of all the to_string calls in the Nov 14, 2018
DPrint.h Initial commit May 13, 2018
FunctionDeclHandler.cpp Rename FindLocationAfterToken and GetSourceRangeAfterToken. Nov 25, 2018
FunctionDeclHandler.h Major rewrite to catch even more statements. Jul 14, 2018
ImplicitCastHandler.cpp Major rewrite to catch even more statements. Jul 14, 2018
ImplicitCastHandler.h Initial commit May 13, 2018
Insights.cpp Use docker in travis to get a recent Ubuntu (18.04) for static linking. Sep 29, 2018
InsightsBase.cpp Dedicated function to insert indented text to keep repetitions low. Nov 25, 2018
InsightsBase.h Dedicated function to insert indented text to keep repetitions low. Nov 25, 2018
InsightsHelpers.cpp Add ConstantExpr which seems to be new in clang-8 Dec 1, 2018
InsightsHelpers.h Rename FindLocationAfterToken and GetSourceRangeAfterToken. Nov 25, 2018
InsightsMatchers.h Added variable templates support. Nov 25, 2018
InsightsStaticStrings.h Major rewrite to catch even more statements. Jul 14, 2018
InsightsStrCat.h Add to_string to StrCat to get rid of all the to_string calls in the Nov 14, 2018
InsightsStrongTypes.h Initial commit May 13, 2018
LICENSE Initial commit May 13, 2018
NumberIterator.h Added support for expansion of class templates. Jun 16, 2018
OutputFormatHelper.cpp Remove unused code. Sep 10, 2018
OutputFormatHelper.h Remove unused code. Sep 10, 2018
Readme.md Generate documentation and upload it to andreasfertig.github.io Aug 31, 2018
StackList.h Major rewrite to catch even more statements. Jul 14, 2018
StaticAssertHandler.cpp Rename FindLocationAfterToken and GetSourceRangeAfterToken. Nov 25, 2018
StaticAssertHandler.h Initial commit May 13, 2018
TODO.md Generate documentation and upload it to andreasfertig.github.io Aug 31, 2018
TemplateHandler.cpp Fix clang 6 build to keep it alive for now. Nov 30, 2018
TemplateHandler.h Fixed #62: Create valid names for parameter pack variables. Nov 14, 2018
UserDefinedLiteralHandler.cpp Major rewrite to catch even more statements. Jul 14, 2018
UserDefinedLiteralHandler.h Initial commit May 13, 2018
version.h.in Improve compatibility handling and use modern C++. Aug 29, 2018

Readme.md

cpp insights logo

C++ Insights - See your source code with the eyes of a compiler.

License download Build Status codecov Try online patreon

Contents

What

C++ Insights is a clang-based tool which does a source to source transformation. Its goal is it to make things visible which normally, and intentionally, happen behind the scenes. It's about the magic the compiler does for us to make things work.

Take this piece of code for example:

class Base {
};

class Derived : public Base {
};

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

Nothing special and of course it compiles. This is the compilers view on it:

class Base {
/* public: inline constexpr Base() noexcept; */
/* public: inline ~Base(); */
/* public: inline constexpr Base(const Base &); */
/* public: inline constexpr Base(Base &&); */
};

class Derived : public Base {
/* public: inline constexpr Derived() noexcept; */
/* public: inline constexpr Derived(const Derived &); */
/* public: inline constexpr Derived(Derived &&); */
};

int main(){
  Derived d;
  Base& b = static_cast<Base&>(d);
}

You can see all the compiler provided functions. Also the downcast from Derived to Base.

I do not claim to get all the things right. This is just the initial version of insights I consider good enough to hand it to the public. Keep also in mind that is solely based on clang and it's understanding of the AST.

Why

C++ Insights is a clang-based tool which does a source to source transformation. Its goal is to make things visible which normally, and intentionally, happen behind the scenes. It's about the magic the compiler does for us to make things work. Or looking through the classes of a compiler.

Some time ago I started looking into some new things we got with C++11, C++14 and C++17. Amazing things like lambdas, range-based for-loops and structured bindings. I put it together in a talk. You can find the slides and a video online.

However, all that research and some of my training and teaching got me start thinking how it would be, if we could see with the eyes of the compiler. Sure, there is an AST-dump at least for clang. With tools like Compiler Explorer we can see what code the compiler generates from a C++ source snippet. However, what we see is assembler. Neither the AST nor the Compiler Explorer output is in the language I write code and therefore I'm most familiar with. Plus when teaching students C++ showing an AST and explaining that it is all there, was not quite satisfying for me.

I started to write a clang-based tool able to transform a range-based for-loop into the compiler-internal version. Then, I did the same for structured bindings and lambdas. In the end, I ended up with doing a lot more as initially planned. It shows where operators are invoked, places in which the compiler does some casting. C++ Insights is able to deduce the type behind auto or decltype. The goal is to produce compilable code. However, this is not possible in all places.

Still, there is work to do.

I do not claim to get all the things right. This is just the initial version of C++ Insights I consider good enough to hand it to the public. Also, keep in mind that it is solely based on clang and my understanding of C++ and the AST.

You can see, for example the transformation of a lamda, range-based for-loop or auto. Of course, you can transform any other C++ snippet.

See yourself, C++ Insights is available online: cppinsights.io.

Building

C++ Insights can be build inside the clang-source tree or outside.

Building outside clang

You need to have a clang installation in the search path.

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

The resulting binary (insights) can be found in the build-folder.

Building inside clang

For building it inside the clang-source tree, assuming you have your source-tree already prepared:

cd llvm/tools/clang/tools/extra
git clone https://github.com/andreasfertig/cppinsights.git

echo "add_subdirectory(cppinsights)" >> CMakeLists.txt

Then build clang as you normally do.

cmake options

There are a couple of options which can be enable with !cmake:

Option Description Default
INSIGHTS_STRIP Strip insight after build ON
INSIGHTS_STATIC Use static linking OFF
INSIGHTS_COVERAGE Enable code coverage OFF
DEBUG Enable debug OFF

Use it with Cevelop

git clone https://github.com/andreasfertig/cppinsights.git
mkdir build_eclipse
cd build_eclipse
cmake -G"Eclipse CDT4 - Unix Makefiles" ../cppinsights/

Then in Cevelop Import -> General -> Existing Project into Workspace. Select build_eclipse. Enjoy editing with Cevelop.

Usage

Using C++ Insights is fairly simple:

insights <YOUR_CPP_FILE> -- -std=c++17

Things get complicate with when it comes to the system include paths. There are path hard-coded in the binary which seem to come from the compiler C++ Insights was build with. To help with that check out scripts/getinclude.py. It tries to collect the system include paths from the compiler. Without an option it uses g++, you can also pass another compiler as a first argument.

Here is an example:

./scripts/getinclude.py 
-isystem/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/../include/c++/v1 -isystem/usr/local/include -isystem/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/../lib/clang/7.3.0/include -isystem/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/include -isystem/usr/include 

The script can be used together with C++ Insights:

insights <YOUR_CPP_FILE> -- -std=c++17 `./scripts/getinclude.py`

There is also another github project which sets up a docker container with the latest C++ Insights version in it: C++ Insights - Docker

Get Involved

Support

If you like to support the project consider submitting a patch. Another alternative is to become a Patreon supporter.