{"id":13436709,"url":"https://github.com/andreasfertig/cppinsights","last_synced_at":"2025-05-13T20:22:09.251Z","repository":{"id":32073343,"uuid":"131510015","full_name":"andreasfertig/cppinsights","owner":"andreasfertig","description":"C++ Insights - See your source code with the eyes of a compiler","archived":false,"fork":false,"pushed_at":"2025-04-07T16:24:21.000Z","size":3180,"stargazers_count":4252,"open_issues_count":20,"forks_count":251,"subscribers_count":66,"default_branch":"main","last_synced_at":"2025-04-28T11:55:45.447Z","etag":null,"topics":["ast","clang","cplusplus","cplusplus-11","cplusplus-14","cplusplus-17","cplusplus-20","cplusplus-23","cpp","cpp11","cpp14","cpp17","cpp20","cpp23","cpp26","llvm"],"latest_commit_sha":null,"homepage":"https://cppinsights.io","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/andreasfertig.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["andreasfertig"],"patreon":"cppinsights"}},"created_at":"2018-04-29T16:21:08.000Z","updated_at":"2025-04-25T07:27:50.000Z","dependencies_parsed_at":"2024-02-23T15:26:47.647Z","dependency_job_id":"59c9b58e-4fbb-49f7-8cb4-a2a9745dc6bb","html_url":"https://github.com/andreasfertig/cppinsights","commit_stats":{"total_commits":646,"total_committers":20,"mean_commits":32.3,"dds":0.4009287925696594,"last_synced_commit":"cba412fbd7c6528f77d4d0cedbf64e2b2eb35542"},"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andreasfertig%2Fcppinsights","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andreasfertig%2Fcppinsights/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andreasfertig%2Fcppinsights/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andreasfertig%2Fcppinsights/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andreasfertig","download_url":"https://codeload.github.com/andreasfertig/cppinsights/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251311332,"owners_count":21569008,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ast","clang","cplusplus","cplusplus-11","cplusplus-14","cplusplus-17","cplusplus-20","cplusplus-23","cpp","cpp11","cpp14","cpp17","cpp20","cpp23","cpp26","llvm"],"created_at":"2024-07-31T03:00:51.466Z","updated_at":"2025-04-28T11:56:09.493Z","avatar_url":"https://github.com/andreasfertig.png","language":"C++","readme":"![cpp insights logo](artwork/logo_cppinsights.png)\n# C++ Insights - See your source code with the eyes of a compiler.\n\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![download](https://img.shields.io/badge/latest-download-blue.svg)](https://github.com/andreasfertig/cppinsights/releases) [![Build Status](https://github.com/andreasfertig/cppinsights/workflows/ci/badge.svg)](https://github.com/andreasfertig/cppinsights/actions/)\n[![codecov](https://codecov.io/gh/andreasfertig/cppinsights/branch/main/graph/badge.svg)](https://codecov.io/gh/andreasfertig/cppinsights)\n[![Try online](https://img.shields.io/badge/try-online-blue.svg)](https://cppinsights.io)\n[![Documentation](https://img.shields.io/badge/view-documentation-blue)](https://docs.cppinsights.io)\n[![patreon](https://img.shields.io/badge/patreon-support-orange.svg)](https://www.patreon.com/cppinsights)\n\n[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io#https://github.com/andreasfertig/cppinsights)\n\n## Contents\n\n- [What](#what)\n- [Why](#why)\n- [Building](#building)\n- [Usage](#usage)\n- [Get Involved](#get-involved)\n- [Support](#support)\n\n\n## What\n\n[C++ Insights](https://cppinsights.io) is a [Clang](https://clang.llvm.org)-based tool that does a source-to-source\ntransformation. The goal of C++ Insights is to make things visible that normally and intentionally happen behind the scenes.\nIt's about the magic the compiler does for us to make things work.\n\nTake this piece of code, for example:\n\n```.cpp\nclass Base {\n};\n\nclass Derived : public Base {\n};\n\nint main() {\n  Derived d;\n\n  Derived d2 = d;\n\n  d2 = d;\n\n  Base\u0026 b = d;\n}\n```\n\nNothing special, and of course, it compiles. This is the compiler's view on it:\n\n```.cpp\nclass Base\n{\n  public:\n  // inline constexpr Base() noexcept = default;\n  // inline constexpr Base(const Base \u0026) noexcept = default;\n  // inline constexpr Base \u0026 operator=(const Base \u0026) noexcept = default;\n};\n\n\n\nclass Derived : public Base\n{\n  public:\n  // inline constexpr Derived() noexcept = default;\n  // inline constexpr Derived(const Derived \u0026) noexcept = default;\n  // inline constexpr Derived \u0026 operator=(const Derived \u0026) noexcept = default;\n};\n\n\n\nint main()\n{\n  Derived d;\n  Derived d2 = Derived(d);\n  d2.operator=(d);\n  Base \u0026 b = static_cast\u003cBase\u0026\u003e(d);\n  return 0;\n}\n```\n\nYou can see all the compiler-provided special member functions and the upcast from `Derived` to `Base`.\n\n## Why\n\n[C++ Insights](https://cppinsights.io) is a [Clang](https://clang.llvm.org)-based tool that does a source-to-source transformation.\nThe 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\nfor us to make things work. Or looking through the classes of a compiler.\n\nIn 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,\nand structured bindings. I put it together in a talk. You can find the [slides](https://andreasfertig.com/talks/dl/afertig-ndcolo-2017-fast-and-small.pdf)\nand a [video](https://youtu.be/Bt7KzFxcbgc) online.\n\nHowever, 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\nof 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\ntools like Compiler Explorer. However, what we see is assembler. Neither the AST nor the Compiler Explorer output is in the language I write\ncode. 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\nnot quite satisfying for me.\n\nI 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\nfor structured bindings and lambdas. In the end, I did much more than initially planned. It shows where operators are\ninvoked and places in which the compiler does some casting. C++ Insights can deduce the type behind `auto` or `decltype`. The goal\nis to produce compilable code. However, this is not possible in all places.\n\nYou can see, for example, the transformation of a [lambda](https://cppinsights.io/s/e4e19791), [range-based for-loop](https://cppinsights.io/s/0cddd172), or [auto](https://cppinsights.io/s/6c61d601). Of course, you can transform any other C++ snippet.\n\nSee yourself. C++ Insights is available online: [cppinsights.io](https://cppinsights.io).\n\nStill, there is work to do.\n\nI 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.\nPlease remember that C++ Insights is based on Clang and its understanding of the AST.\n\n\nI did a couple of talks about C++ Insights since I released C++ Insights. For example, at C++ now. Here are the [slides](https://andreasfertig.com/talks/dl/afertig-2021-cppnow-cpp-insights.pdf) and the [video](https://youtu.be/p-8wndrTaTs).\n\n\n## Building\n\nC++ Insights can be built inside or outside the Clang source tree.\n\n### Building on Windows\n\nSee [Readme_Windows.md](Readme_Windows.md)\n\n### Building on Arch Linux\n\nTo build with `extra/clang` use the following extra flags: `-DINSIGHTS_USE_SYSTEM_INCLUDES=off -DCLANG_LINK_CLANG_DYLIB=on -DLLVM_LINK_LLVM_DYLIB=on`\n\nSee https://github.com/andreasfertig/cppinsights/issues/186 for an explanation of why `INSIGHTS_USE_SYSTEM_INCLUDES` needs to be turned off.\n\n`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\n\n\n### Building outside Clang\n\nYou need to have a Clang installation in the search path.\n\n```\ngit clone https://github.com/andreasfertig/cppinsights.git\nmkdir build \u0026\u0026 cd build\ncmake -G\"Ninja\" ../cppinsights\nninja\n```\nThe resulting binary (insights) can be found in the `build` folder.\n\n### Building inside Clang\n\nThe easiest way to build C++ Insights inside the Clang source tree is using the `LLVM_EXTERNAL_PROJECTS` option.\n\n```\ngit clone https://github.com/llvm/llvm-project.git\ngit clone https://github.com/andreasfertig/cppinsights.git\n\nmkdir build\ncd build\ncmake -G Ninja -D=CMAKE_BUILD_TYPE=Release -DLLVM_EXTERNAL_PROJECTS=cppinsights -DLLVM_EXTERNAL_CPPINSIGHTS_SOURCE_DIR=\u003cPATH/TO/cppinsights\u003e  [INSIGHTS CMAKE OPTIONS] ../llvm-project/llvm\n\nninja\n```\n\n\n\n### cmake options\n\nThere are a couple of options that can be enabled with [cmake](https://cmake.org):\n\n| Option              | Description                | Default |\n|---------------------|:---------------------------| --------|\n| INSIGHTS_STRIP      | Strip insight after build  | ON      |\n| INSIGHTS_STATIC     | Use static linking         | OFF     |\n| INSIGHTS_COVERAGE   | Enable code coverage       | OFF     |\n| INSIGHTS_USE_LIBCPP | Use libc++ for tests       | OFF     |\n| DEBUG               | Enable debug               | OFF     |\n\n### Building for ARM on macOS\n\nIt seems best to supply the architecture during configuration:\n\n```\ncmake -DCMAKE_OSX_ARCHITECTURES=arm64 ../cppinsights\n```\n\n\n### Use it with [Cevelop](https://www.cevelop.com)\n\n```\ngit clone https://github.com/andreasfertig/cppinsights.git\nmkdir build_eclipse\ncd build_eclipse\ncmake -G\"Eclipse CDT4 - Unix Makefiles\" ../cppinsights/\n```\n\nThen, in [Cevelop](https://www.cevelop.com) Import -\u003e General -\u003e Existing Project into Workspace. Select `build_eclipse`. Enjoy editing with\n[Cevelop](https://www.cevelop.com).\n\n## Usage\n\nUsing C++ Insights is fairly simple:\n\n```\ninsights \u003cYOUR_CPP_FILE\u003e -- -std=c++17\n```\n\nThings get complicated when it comes to the system-include paths. These paths are hard-coded in the binary, which seems\nto come from the compiler C++ Insights was built with. To help with that, check out [scripts/getinclude.py](scripts/getinclude.py). The script tries to\ncollect the system-include paths from the compiler. Without an option, `getinclude.py` uses `g++`. You can also pass another compiler\nas a first argument.\n\nHere is an example:\n\n```\n./scripts/getinclude.py\n-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\n```\n\nThe script can be used together with C++ Insights:\n\n```\ninsights \u003cYOUR_CPP_FILE\u003e -- -std=c++17 `./scripts/getinclude.py`\n```\n\n\n### Custom GCC installation\n\nIn 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:\n\n```\n./cppinsights Insights.cpp -- --gcc-toolchain=${GCC_11_2_0_INSTALL_PATH} -std=c++20\n```\n\nHere \"`${GCC_11_2_0_INSTALL_PATH}`\" is the installation directory of your customized-built GCC. The option for Clang is described [here](https://clang.llvm.org/docs/ClangCommandLineReference.html#cmdoption-clang-gcc-toolchain).\n\n\n### Ready to use Docker container\n\nThere is also another GitHub project that sets up a docker container with the latest C++ Insights version in it: [C++\nInsights - Docker](https://github.com/andreasfertig/cppinsights-docker)\n\n\n## Plugins / Extensions / Packages\n\n### C++ Insights @ Vim\n\nA plugin for Vim is available at\n[here](https://github.com/Freed-Wu/cppinsights.vim).\n\n### C++ Insights @ Neovim\n\nA plugin for Neovim is available at\n[here](https://github.com/Freed-Wu/cppinsights.nvim).\n\n### C++ Insights @ VSCode\n\nAn extension for Visual Studio Code is available at the VS Code marketplace: [C++\nInsights - VSCode Extension](https://marketplace.visualstudio.com/items?itemName=devtbi.vscode-cppinsights).\n\n\n### C++ Insights @ brew\n\nAt least for macOS, you can install C++ Insights via Homebrew thanks to [this formular](https://formulae.brew.sh/formula/cppinsights):\n\n```\nbrew install cppinsights\n```\n\n\n## Compatibility\n\nI aim for the repository to compile with the latest version of Clang and at least the one before. The website tries to\nstay close to the latest release of Clang. However, due to certain issues (building Clang for Windows), the website's\nversion is often delayed by a few months.\n\n\n## C++ Insights @ YouTube\n\nI created a [YouTube](https://youtube.com/@andreas_fertig) channel where I release a new video each month. In\nthese videos, I use C++ Insights to show and explain certain C++ constructs, and sometimes I explain C++ Insights as well.\n\n\n## ToDo's\n\nSee [TODO](TODO.md).\n\n\n## Get Involved\n+ Report bugs/issues by submitting a [GitHub issue](https://github.com/andreasfertig/cppinsights/issues).\n+ Submit contributions using [pull requests](https://github.com/andreasfertig/cppinsights/pulls). See [Contributing](CONTRIBUTING.md)\n\n## Support\n\nIf you like to support the project, consider [submitting](CONTRIBUTING.md) a patch. Another alternative is to become a [GitHub Sponsor](https://github.com/sponsors/andreasfertig) or a [Patreon](https://www.patreon.com/cppinsights) supporter.\n\n\n","funding_links":["https://github.com/sponsors/andreasfertig","https://patreon.com/cppinsights","https://www.patreon.com/cppinsights"],"categories":["HarmonyOS","C++","Development Environment","System","C/C++程序设计","pp-trace"],"sub_categories":["Windows Manager","Debugging and Tracing","资源传输下载","Other Clang-based tools"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandreasfertig%2Fcppinsights","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandreasfertig%2Fcppinsights","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandreasfertig%2Fcppinsights/lists"}