https://github.com/andreasfertig/cppinsights Skip to content Toggle navigation Sign in * Product + Actions Automate any workflow + Packages Host and manage packages + Security Find and fix vulnerabilities + Codespaces Instant dev environments + Copilot Write better code with AI + Code review Manage code changes + Issues Plan and track work + Discussions Collaborate outside of code Explore + All features + Documentation + GitHub Skills + Blog * Solutions For + Enterprise + Teams + Startups + Education By Solution + CI/CD & Automation + DevOps + DevSecOps Resources + Learning Pathways + White papers, Ebooks, Webinars + Customer Stories + Partners * Open Source + GitHub Sponsors Fund open source developers + The ReadME Project GitHub community articles Repositories + Topics + Trending + Collections * Pricing Search or jump to... Search code, repositories, users, issues, pull requests... Search [ ] Clear Search syntax tips Provide feedback We read every piece of feedback, and take your input very seriously. [ ] [ ] Include my email address so I can be contacted Cancel Submit feedback Saved searches Use saved searches to filter your results more quickly Name [ ] Query [ ] To see all available qualifiers, see our documentation. Cancel Create saved search Sign in Sign up You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert {{ message }} andreasfertig / cppinsights Public * * Notifications * Fork 153 * Star 3k * C++ Insights - See your source code with the eyes of a compiler cppinsights.io License MIT license 3k stars 153 forks Branches Tags Activity Star Notifications * Code * Issues 13 * Pull requests 0 * Actions * Projects 0 * Security * Insights Additional navigation options * Code * Issues * Pull requests * Actions * Projects * Security * Insights andreasfertig/cppinsights This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository. main BranchesTags Go to file Code Folders and files Last Last Name Name commit commit message date Latest commit History 1,016 Commits .github .github artwork artwork docs docs scripts scripts tests tests .clang-format .clang-format .clang-tidy .clang-tidy .clang-tidy-ignore .clang-tidy-ignore .gitignore .gitignore .gitpod.yml .gitpod.yml ASTHelpers.cpp ASTHelpers.cpp ASTHelpers.h ASTHelpers.h CMakeLists.txt CMakeLists.txt CODE_OF_CONDUCT.md CODE_OF_CONDUCT.md CONTRIBUTING.md CONTRIBUTING.md CfrontCodeGenerator.cpp CfrontCodeGenerator.cpp ClangCompat.h ClangCompat.h CodeGenerator.cpp CodeGenerator.cpp CodeGenerator.h CodeGenerator.h CodeGeneratorTypes.h CodeGeneratorTypes.h Coroutines.md Coroutines.md CoroutinesCodeGenerator.cpp CoroutinesCodeGenerator.cpp DPrint.cpp DPrint.cpp DPrint.h DPrint.h Insights.cpp Insights.cpp Insights.h Insights.h InsightsHelpers.cpp InsightsHelpers.cpp InsightsHelpers.h InsightsHelpers.h InsightsOnce.h InsightsOnce.h InsightsOptions.def InsightsOptions.def InsightsStaticStrings.h InsightsStaticStrings.h InsightsStrCat.h InsightsStrCat.h InsightsStrongTypes.h InsightsStrongTypes.h InsightsUtility.h InsightsUtility.h LICENSE LICENSE LifetimeTracker.cpp LifetimeTracker.cpp NumberIterator.h NumberIterator.h OutputFormatHelper.cpp OutputFormatHelper.cpp OutputFormatHelper.h OutputFormatHelper.h Readme.md Readme.md Readme_Windows.md Readme_Windows.md StackList.h StackList.h TODO.md TODO.md codecov.yml codecov.yml version.h.in version.h.in View all files Repository files navigation * README * Code of conduct * MIT license cpp insights logo C++ Insights - See your source code with the eyes of a compiler. License download Build Status codecov Try online Documentation patreon Open in Gitpod Contents * What * Why * Building * Usage * Get Involved * Support What C++ Insights is a Clang-based tool that does a source-to-source transformation. The goal of C++ Insights is to make things visible that 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; Derived d2 = d; d2 = d; Base& b = d; } Nothing special, and of course, it compiles. This is the compiler's view on it: 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(d); return 0; } You can see all the compiler-provided special member functions and the downcast from Derived to Base. Why C++ Insights is a Clang-based tool that does a source-to-source transformation. The goal of C++ Insights is to make things visible that 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. In 2017, 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 to start thinking about how it would be if we could see with the eyes of the compiler. Sure, there is an AST dump, at least for Clang. We can see what code the compiler generates from a C++ source snippet with tools like Compiler Explorer. However, what we see is assembler. Neither the AST nor the Compiler Explorer output is in the language I write code. Hence, I'm not very familiar with this output. 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 that can 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 did much more than initially planned. It shows where operators are invoked and places in which the compiler does some casting. C++ Insights can deduce the type behind auto or decltype. The goal is to produce compilable code. However, this is not possible in all places. You can see, for example, the transformation of a lambda, range-based for-loop, or auto. Of course, you can transform any other C++ snippet. See yourself. C++ Insights is available online: cppinsights.io. Still, there is work to do. I do not claim to get all the things right. I'm also working on supporting features from new standards, like C++20, at the moment. Please remember that C++ Insights is based on Clang and its understanding of the AST. I did a couple of talks about C++ Insights since I released C++ Insights. For example, at C++ now. Here are the slides and the video. Building C++ Insights can be built inside the Clang source tree or outside. Building on Windows See Readme_Windows.md Building on Arch Linux To build with extra/clang use the following extra flags: -DINSIGHTS_USE_SYSTEM_INCLUDES=off -DCLANG_LINK_CLANG_DYLIB=on -DLLVM_LINK_LLVM_DYLIB=on See #186 for an explanation of why INSIGHTS_USE_SYSTEM_INCLUDES needs to be turned off. extra/clang and extra/llvm provide /usr/lib/ {libclangAST.so,libLLVM*.a,libLLVM.so}. libclangAST.so needs libLLVM.so and there would be a conflict if libLLVM*.a (instead of libLLVM.so) are linked. See https://bugs.archlinux.org/task/60512 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 under llvm-project: cd llvm-project/clang-tools-extra/ git clone https://github.com/andreasfertig/cppinsights.git echo "add_subdirectory(cppinsights)" >> CMakeLists.txt To activate the C++ Insights build you have to set -DLLVM_ENABLE_PROJECTS="clang;clang-tools-extra" for cmake: cmake -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_PROJECTS="clang;clang-tools-extra" -G "Unix Makefiles" ../llvm-project Then, build Clang as you normally do. cmake options There are a couple of options that can be enabled with cmake: Option Description Default INSIGHTS_STRIP Strip insight after build ON INSIGHTS_STATIC Use static linking OFF INSIGHTS_COVERAGE Enable code coverage OFF INSIGHTS_USE_LIBCPP Use libc++ for tests OFF DEBUG Enable debug OFF Building for ARM on macOS It seems best to supply the architecture during configuration: cmake -DCMAKE_OSX_ARCHITECTURES=arm64 ../cppinsights 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 -- -std=c++17 Things get complicated when it comes to the system-include paths. These paths are hard-coded in the binary, which seems to come from the compiler C++ Insights was built with. To help with that, check out scripts/getinclude.py. The script tries to collect the system-include paths from the compiler. Without an option, getinclude.py 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 -- -std=c++17 `./scripts/getinclude.py` Custom GCC installation In case you have a custom build of the GCC compiler, for example, gcc-11.2.0, and NOT installed in the compiler in the default system path, then after building, Clang fails to find the correct libstdc++ path (GCC's STL). If you run into this situation, you can use "--gcc-toolchain=/path/GCC-1x.x.x/installed/path" to tell Clang/C++ Insights the location of the STL: ./cppinsights Insights.cpp -- --gcc-toolchain=${GCC_11_2_0_INSTALL_PATH} -std=c++20 Here "${GCC_11_2_0_INSTALL_PATH}" is the installation directory of your customized-built GCC. The option for Clang is described here. Ready to use Docker container There is also another GitHub project that sets up a docker container with the latest C++ Insights version in it: C++ Insights - Docker C++ Insights @ Vim A plugin for Vim is available at here. C++ Insights @ VSCode An extension for Visual Studio Code is available at the VS Code marketplace: C++ Insights - VSCode Extension. C++ Insights @ brew At least for macOS, you can install C++ Insights via Homebrew thanks to this formulae: brew install cppinsights Compatibility I aim for the repository to compile with the latest version of Clang and at least the one before. The website tries to stay close to the latest release of Clang. However, due to certain issues (building Clang for Windows), the website's version is often delayed by a few months. C++ Insights @ YouTube I created a YouTube channel where I release a new video each month. In these videos, I use C++ Insights to show and explain certain C++ constructs, and sometimes I explain C++ Insights as well. ToDo's See TODO. Get Involved * Report bugs/issues by submitting a GitHub issue. * Submit contributions using pull requests. See Contributing Support If you like to support the project, consider submitting a patch. Another alternative is to become a GitHub Sponsor or a Patreon supporter. About C++ Insights - See your source code with the eyes of a compiler cppinsights.io Topics cplusplus cpp llvm cpp14 ast clang cpp11 cpp17 cplusplus-14 cplusplus-11 cplusplus-17 cpp20 cplusplus-20 cplusplus-23 cpp23 cpp2 Resources Readme License MIT license Code of conduct Code of conduct Activity Stars 3k stars Watchers 62 watching Forks 153 forks Report repository Releases 11 v_17.0 Latest Apr 3, 2024 + 10 releases Sponsor this project * * patreon patreon.com/cppinsights Learn more about GitHub Sponsors Contributors 16 * @andreasfertig * @grishavanika * @devtbi * @e-kwsm * @meysholdt * @mys721tx * @pravic * @kl7107 * @galorojo * @HFTrader * @lexasub * @ayazhafiz * @mergify[bot] * @NKID00 + 2 contributors Languages * C++ 91.7% * CMake 4.6% * Python 2.4% * Other 1.3% Footer (c) 2024 GitHub, Inc. Footer navigation * Terms * Privacy * Security * Status * Docs * Contact * Manage cookies * Do not share my personal information You can't perform that action at this time.