{"id":13418001,"url":"https://github.com/include-what-you-use/include-what-you-use","last_synced_at":"2025-05-14T10:10:33.148Z","repository":{"id":37771233,"uuid":"37440338","full_name":"include-what-you-use/include-what-you-use","owner":"include-what-you-use","description":"A tool for use with clang to analyze #includes in C and C++ source files","archived":false,"fork":false,"pushed_at":"2024-10-05T13:24:53.000Z","size":4406,"stargazers_count":4102,"open_issues_count":257,"forks_count":388,"subscribers_count":70,"default_branch":"master","last_synced_at":"2024-10-29T15:06:59.930Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://include-what-you-use.org","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/include-what-you-use.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.TXT","code_of_conduct":null,"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}},"created_at":"2015-06-15T03:00:29.000Z","updated_at":"2024-10-27T11:25:03.000Z","dependencies_parsed_at":"2023-02-17T02:45:55.056Z","dependency_job_id":"37757369-45c7-4e80-871a-23f8faad22cd","html_url":"https://github.com/include-what-you-use/include-what-you-use","commit_stats":{"total_commits":1299,"total_committers":75,"mean_commits":17.32,"dds":0.6520400307929176,"last_synced_commit":"14e9b208914a84fcdf49bf9f5d08897a4b3dc4b8"},"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/include-what-you-use%2Finclude-what-you-use","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/include-what-you-use%2Finclude-what-you-use/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/include-what-you-use%2Finclude-what-you-use/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/include-what-you-use%2Finclude-what-you-use/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/include-what-you-use","download_url":"https://codeload.github.com/include-what-you-use/include-what-you-use/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247953072,"owners_count":21023949,"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":[],"created_at":"2024-07-30T22:00:56.923Z","updated_at":"2025-04-09T01:14:30.955Z","avatar_url":"https://github.com/include-what-you-use.png","language":"C++","funding_links":[],"categories":["TODO scan for Android support in followings","Static Code Analysis","HarmonyOS","C++","Tools","工具","Tools ##"],"sub_categories":["Windows Manager","YAML","Vim ###"],"readme":"# Include What You Use #\n\n[![IWYU CI](https://github.com/include-what-you-use/include-what-you-use/actions/workflows/ci.yml/badge.svg)](https://github.com/include-what-you-use/include-what-you-use/actions/workflows/ci.yml)\n\nFor more in-depth documentation, see [docs](docs).\n\n\n## Instructions for users ##\n\n\"Include what you use\" means this: for every symbol (type, function, variable,\nor macro) that you use in `foo.cc` (or `foo.cpp`), either `foo.cc` or `foo.h`\nshould include a .h file that exports the declaration of that\nsymbol. (Similarly, for `foo_test.cc`, either `foo_test.cc` or `foo.h` should do\nthe including.)  Obviously symbols defined in `foo.cc` itself are excluded from\nthis requirement.\n\nThis puts us in a state where every file includes the headers it needs to\ndeclare the symbols that it uses.  When every file includes what it uses, then\nit is possible to edit any file and remove unused headers, without fear of\naccidentally breaking the upwards dependencies of that file.  It also becomes\neasy to automatically track and update dependencies in the source code.\n\n\n### CAVEAT ###\n\nThis is experimental software, as of June 2024.  It was originally written to\nwork specifically in the Google source tree, and may make assumptions, or have\ngaps, that are immediately and embarrassingly evident in other types of code.\n\nWhile we work to get IWYU quality up, we will be stinting new features, and will\nprioritize reported bugs along with the many existing, known bugs.  The best\nchance of getting a problem fixed is to submit a patch that fixes it (along with\na test case that verifies the fix)!\n\n\n### Clang compatibility ###\n\nInclude-what-you-use makes heavy use of Clang internals, and will occasionally\nbreak when Clang is updated. We build IWYU regularly against Clang mainline to\ndetect and fix such compatibility breaks as soon as possible.\n\nNOTE: the IWYU master branch follows Clang main branch.\n\nWe also have convenience tags and branches for released versions of Clang\n(called `clang_\u003cversion\u003e`, e.g. `clang_5.0`). To build against a Clang release,\ncheck out the corresponding branch in IWYU before configuring the build. You can\nuse this mapping table to combine Clang and IWYU versions correctly:\n\n| Clang | IWYU version | IWYU branch    |\n|-------|--------------|----------------|\n| 3.6   | 0.4          | `clang_3.6`    |\n| 3.7   | 0.5          | `clang_3.7`    |\n| 3.8   | 0.6          | `clang_3.8`    |\n| 3.9   | 0.7          | `clang_3.9`    |\n| 4.0   | 0.8          | `clang_4.0-r2` |\n| 5.0   | 0.9          | `clang_5.0`    |\n| 6     | 0.10         | `clang_6.0`    |\n| 7     | 0.11         | `clang_7.0`    |\n| 8     | 0.12         | `clang_8.0`    |\n| 9     | 0.13         | `clang_9.0`    |\n| 10    | 0.14         | `clang_10`     |\n| 11    | 0.15         | `clang_11`     |\n| 12    | 0.16         | `clang_12`     |\n| 13    | 0.17         | `clang_13`     |\n| 14    | 0.18         | `clang_14`     |\n| 15    | 0.19         | `clang_15`     |\n| 16    | 0.20         | `clang_16`     |\n| 17    | 0.21         | `clang_17`     |\n| 18    | 0.22         | `clang_18`     |\n| 19    | 0.23         | `clang_19`     |\n| 20    | 0.24         | `clang_20`     |\n| ...   | ...          | ...            |\n| main  |              | `master`       |\n\n\u003e NOTE: If you use the Debian/Ubuntu packaging available from\n\u003e \u003chttps://apt.llvm.org\u003e, you'll need the following packages installed:\n\u003e\n\u003e * `llvm-\u003cversion\u003e-dev`\n\u003e * `libclang-\u003cversion\u003e-dev`\n\u003e * `clang-\u003cversion\u003e`\n\u003e\n\u003e Packaging for other platforms will likely be subtly different.\n\n\n### How to build standalone ###\n\nThis build mode assumes you already have compiled LLVM and Clang libraries on\nyour system, either via packages for your platform or built from source. To set\nup an environment for building IWYU:\n\n* Create a directory for IWYU development, e.g. `iwyu`\n\n* Clone the IWYU Git repo:\n  ```\n  iwyu$ git clone https://github.com/include-what-you-use/include-what-you-use.git\n  ```\n* Presumably, you'll be building IWYU with a released version of LLVM and Clang,\n  so check out the corresponding branch. For example, if you have Clang 6.0\n  installed, use the `clang_6.0` branch. IWYU `master` tracks LLVM \u0026 Clang\n  `main`:\n  ```\n  iwyu$ cd include-what-you-use\n  iwyu/include-what-you-use$ git checkout clang_6.0\n  ```\n\n* Create a build root and use CMake to generate a build system linked with\n  LLVM/Clang prebuilts:\n  ```\n  # This example uses the Makefile generator, but anything should work.\n  iwyu/include-what-you-use$ cd ..\n  iwyu$ mkdir build \u0026\u0026 cd build\n\n  # For IWYU 0.10/Clang 6 and earlier\n  iwyu/build$ cmake -G \"Unix Makefiles\" -DIWYU_LLVM_ROOT_PATH=/usr/lib/llvm-6.0 ../include-what-you-use\n\n  # For IWYU 0.11/Clang 7 and later\n  iwyu/build$ cmake -G \"Unix Makefiles\" -DCMAKE_PREFIX_PATH=/usr/lib/llvm-7 ../include-what-you-use\n  ```\n  (substitute the `llvm-6.0` or `llvm-7` suffixes with the actual version\n  compatible with your IWYU branch)\n\n  or, if you have a local LLVM and Clang build tree, you can specify that as\n  `CMAKE_PREFIX_PATH` for IWYU 0.11 and later:\n  ```\n  iwyu/build$ cmake -G \"Unix Makefiles\" -DCMAKE_PREFIX_PATH=~/llvm-project/build ../include-what-you-use\n  ```\n\n* Once CMake has generated a build system, you can invoke it directly from\n  `build`, e.g.\n  ```\n  iwyu/build$ make\n  ```\n\n### How to build as part of LLVM ###\n\nInstructions for building LLVM and Clang are available at\n\u003chttps://clang.llvm.org/get_started.html\u003e.\n\nTo include IWYU in the LLVM build, use the `LLVM_EXTERNAL_PROJECTS` and\n`LLVM_EXTERNAL_*_SOURCE_DIR` CMake variables when configuring LLVM:\n```\nllvm-project/build$ cmake -G \"Unix Makefiles\" -DLLVM_ENABLE_PROJECTS=clang \\\n    -DLLVM_EXTERNAL_PROJECTS=iwyu -DLLVM_EXTERNAL_IWYU_SOURCE_DIR=/path/to/iwyu\\\n    /path/to/llvm-project/llvm\nllvm-project/build$ make\n```\nThis builds all of LLVM, Clang and IWYU in a single tree.\n\n\n### How to install ###\n\nTo install and use a pre-built IWYU, besides any dynamic library dependencies,\nyou need to make sure it can find the Clang built-in headers (`stdarg.h` and\nfriends).\n\nThis is a surprisingly complex problem, so it helps to first understand how\nClang locates the built-in headers.\n\nThe built-in headers live in what Clang calls the _resource directory_, which\ncontains various runtime resources for the compiler. The resource dir is\nconfigurable at Clang build time, using the `CLANG_RESOURCE_DIR` CMake\nvariable. `CLANG_RESOURCE_DIR` is always a relative path, so the effective\nabsolute path can be computed at runtime relative to the `clang` executable.\n\nThe Clang build sets up a resource dir in the build tree and copies the relevant\nresources there (the built-in headers among them), so it's possible to run\n`clang` directly from the build tree. Furthermore, the Clang install target will\ncopy the resource dir to the install tree.\n\nThe Clang `Driver` library is responsible for computing the effective path at\nruntime. It will look up the current executable path (typically `clang`), strip\noff the filename and append `CLANG_RESOURCE_DIR` to form the resource dir\npath. You can use `clang -print-resource-dir` to print the effective resource\ndir for a particular Clang tree.\n\nPhew! What does this mean for IWYU?\n\nIWYU links to the Clang `Driver` library, and so would nominally get the exact\nsame policy by default: `CLANG_RESOURCE_DIR` relative to the\n`include-what-you-use` executable. This means the IWYU build would have to\ncreate the resource dir in its build tree, and also make sure it's available in\nthe install tree, using a custom install target. But `CLANG_RESOURCE_DIR` is not\nexported from the Clang CMake system, so it's not possible to know at build-time\nwhere the resources need to be.\n\nSince Clang has all the knowledge about which resources need to go into the\nresource dir, and also decides under the covers where it has to be, it's\ndifficult for IWYU to make any principled decisions. We side-step this conflict\nby exposing our own set of CMake variables for the resource dir:\n\n* `IWYU_RESOURCE_DIR`: same semantics as Clang's `CLANG_RESOURCE_DIR`\n* `IWYU_RESOURCE_RELATIVE_TO`: which executable to serve as the anchor path for\n  the resource directory (`clang` or `iwyu`)\n\nFirst, `IWYU_RESOURCE_DIR` exists to supplement `CLANG_RESOURCE_DIR`. Packagers\nfor a platform where Clang has a custom `CLANG_RESOURCE_DIR` can repeat the same\ncustomization for IWYU. By default it will use the same default pattern as\nClang, i.e. `../lib/clang/\u003cclang-version\u003e`.\n\nSecond, we can use `IWYU_RESOURCE_RELATIVE_TO` to decide which executable path\nto use as the anchor for the relative `IWYU_RESOURCE_DIR`.\n\nIf it is `clang`, we resolve the path to the `clang` executable _at configure-\ntime_, and bake that absolute path into `include-what-you-use`.\n\nIf it is `iwyu`, the `include-what-you-use` executable resolves its own path _at\nruntime_.\n\nThat means packagers can easily build:\n\n* an `include-what-you-use` that has a package dependency on Clang, and relies\n  entirely on its resource dir (`-DIWYU_RESOURCE_RELATIVE_TO=clang`)\n* an `include-what-you-use` that has a package dependency on a Clang with a\n  custom resource dir (`-DIWYU_RESOURCE_RELATIVE_TO=clang\n  -DIWYU_RESOURCE_DIR=../what/clang/said`)\n* an `include-what-you-use` that can be installed separate from Clang in its own\n  prefix (`-DIWYU_RESOURCE_RELATIVE_TO=iwyu -DCMAKE_INSTALL_PREFIX=/usr/local`),\n  assuming a custom install step to also copy the built-in headers to the\n  default `IWYU_RESOURCE_DIR` in the same prefix.\n* an `include-what-you-use` that can be installed separate from Clang in an\n  arbitrary prefix with a custom resource dir (`-DIWYU_RESOURCE_RELATIVE_TO=iwyu\n  -DIWYU_RESOURCE_DIR=../share/include-what-you-use`), assuming a custom install\n  step to also copy the built-in headers to the custom `IWYU_RESOURCE_DIR`.\n\nIWYU uses `IWYU_RESOURCE_RELATIVE_TO=clang` by default, because that produces a\nrunnable `include-what-you-use` in the build tree, which depends directly on the\nClang package it was configured for with `-DCMAKE_PREFIX_PATH`. It's also\nsuitable for packaging, in the sense that the IWYU package can be made to depend\non the Clang package, and will then automatically use the Clang resource dir on\nthe target system.\n\n`IWYU_RESOURCE_RELATIVE_TO=iwyu` is more suitable to build a fully independent\nIWYU package, but also requires some custom logic outside the IWYU build to\npackage and install relevant parts of the resource dir from Clang in a suitable\nlocation.\n\nUse `include-what-you-use -print-resource-dir` to learn exactly where IWYU\nexpects the resource dir to be installed.\n\n\n### How to run ###\n\nThe original design was built for Make, but a number of alternative run modes\nhave come up over the years.\n\n\n#### Running on single source file ####\n\nThe simplest way to use IWYU is to run it against a single source file:\n```\ninclude-what-you-use $CXXFLAGS myfile.cc\n```\nwhere `$CXXFLAGS` are the flags you would normally pass to the compiler.\n\n\n#### Plugging into existing build system ####\n\nTypically there is already a build system containing the relevant compiler flags\nfor all source files. Replace your compiler with `include-what-you-use` to\ngenerate a large batch of IWYU advice. Depending on your build system/build\ntools, this can take many forms, but for a simple GNU Make system it might look\nlike this:\n```\nmake -k CXX=include-what-you-use CXXFLAGS=\"-Xiwyu --error_always\"\n```\n(The additional `-Xiwyu --error_always` switch makes `include-what-you-use`\nalways exit with an error code, so the build system knows it didn't build a .o\nfile.  Hence the need for `-k`.)\n\nIn this mode `include-what-you-use` only analyzes the .cc (or .cpp) files known\nto your build system, along with their corresponding .h files.  If your project\nhas a .h file with no corresponding .cc file, IWYU will ignore it unless you use\nthe `--check_also` switch to add it for analysis together with a .cc file. It is\npossible to run IWYU against individual header files, provided the compiler\nflags are carefully constructed to match all includers.\n\n\n#### Using with CMake ####\n\nCMake has grown native support for IWYU as of version 3.3. See [their\ndocumentation](https://cmake.org/cmake/help/latest/prop_tgt/LANG_INCLUDE_WHAT_YOU_USE.html)\nfor CMake-side details.\n\nThe `CMAKE_CXX_INCLUDE_WHAT_YOU_USE` option enables a mode where CMake first\ncompiles a source file, and then runs IWYU on it.\n\nUse it like this:\n```\nmkdir build \u0026\u0026 cd build\nCC=\"clang\" CXX=\"clang++\" cmake -DCMAKE_CXX_INCLUDE_WHAT_YOU_USE=include-what-you-use ...\n```\n\nor, on Windows systems:\n```\nmkdir build \u0026\u0026 cd build\ncmake -DCMAKE_CXX_COMPILER=\"%VCINSTALLDIR%/bin/cl.exe\" -DCMAKE_CXX_INCLUDE_WHAT_YOU_USE=include-what-you-use -G Ninja ...\n```\n\nThese examples assume that `include-what-you-use` is in the `PATH`. If it isn't,\nconsider changing the value to an absolute path. Arguments to IWYU can be added\nusing CMake's semicolon-separated list syntax, e.g.:\n```\n... cmake -DCMAKE_CXX_INCLUDE_WHAT_YOU_USE=\"include-what-you-use;-w;-Xiwyu;--verbose=7\" ...\n```\n\nThe option appears to be separately supported for both C and C++, so use\n`CMAKE_C_INCLUDE_WHAT_YOU_USE` for C code.\n\nNote that with Microsoft's Visual C++ compiler, IWYU needs the\n`--driver-mode=cl` argument to understand the MSVC options from CMake.\n\n\n#### Using with a compilation database ####\n\nThe `iwyu_tool.py` script pre-dates the native CMake support, and works off the\n[compilation database\nformat](https://clang.llvm.org/docs/JSONCompilationDatabase.html). For example,\nCMake generates such a database named `compile_commands.json` with the\n`CMAKE_EXPORT_COMPILE_COMMANDS` option enabled.\n\nThe script's command-line syntax is designed to mimic Clang's LibTooling, but\nthey are otherwise unrelated. It can be used like this:\n```\nmkdir build \u0026\u0026 cd build\nCC=\"clang\" CXX=\"clang++\" cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON ...\niwyu_tool.py -p .\n```\n\nor, on Windows systems:\n```\nmkdir build \u0026\u0026 cd build\ncmake -DCMAKE_CXX_COMPILER=\"%VCINSTALLDIR%/bin/cl.exe\" -DCMAKE_C_COMPILER=\"%VCINSTALLDIR%/VC/bin/cl.exe\" -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -G Ninja ...\npython3 iwyu_tool.py -p .\n```\n\nUnless a source filename is provided, all files in the project will be analyzed.\n\nSee `iwyu_tool.py --help` for more options.\n\n\n#### Applying fixes ####\n\nWe also include a tool that automatically fixes up your source files based on\nthe IWYU recommendations.  This is also alpha-quality software!  Here's how to\nuse it (requires python3):\n```\nmake -k CXX=include-what-you-use CXXFLAGS=\"-Xiwyu --error_always\" 2\u003e /tmp/iwyu.out\npython3 fix_includes.py \u003c /tmp/iwyu.out\n```\n\nIf you don't like the way `fix_includes.py` munges your `#include` lines, you\ncan control its behavior via flags. `fix_includes.py --help` will give a full\nlist, but these are some common ones:\n\n* `-b`: Put blank lines between system and Google includes\n* `--nocomments`: Don't add the 'why' comments next to includes\n\n\n### How to correct IWYU mistakes ###\n\n* If `fix_includes.py` has removed an `#include` you actually need, add it back\n  in with the comment '`// IWYU pragma: keep`' at the end of the `#include`\n  line.  Note that the comment is case-sensitive.\n* If `fix_includes.py` has added an `#include` you don't need, just take it out.\n  We hope to come up with a more permanent way of fixing later.\n* If `fix_includes.py` has wrongly added or removed a forward-declare, just fix\n  it up manually.\n* If `fix_includes.py` has suggested a private header file (such as\n  `\u003cbits/stl_vector.h\u003e`) instead of the proper public header file (`\u003cvector\u003e`),\n  you can fix this by inserting a specially crafted comment near top of the\n  private file (assuming you can write to it): '`// IWYU pragma: private,\n  include \"the/public/file.h\"`'.\n\nCurrent IWYU pragmas are described in [IWYUPragmas](docs/IWYUPragmas.md).\n\n\n## More questions? ##\n\nSee our [FAQ](./docs/IWYUFAQ.md) for longer-form Q\u0026A.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finclude-what-you-use%2Finclude-what-you-use","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finclude-what-you-use%2Finclude-what-you-use","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finclude-what-you-use%2Finclude-what-you-use/lists"}