Include What You Use

For more in-depth documentation, see docs.

Instructions for users

"Include what you use" means this: for every symbol (type, function, variable, or macro) that you use in foo.cc (or foo.cpp), either foo.cc or foo.h should include a .h file that exports the declaration of that symbol. (Similarly, for foo_test.cc, either foo_test.cc or foo.h should do the including.) Obviously symbols defined in foo.cc itself are excluded from this requirement.

This puts us in a state where every file includes the headers it needs to declare the symbols that it uses. When every file includes what it uses, then it is possible to edit any file and remove unused headers, without fear of accidentally breaking the upwards dependencies of that file. It also becomes easy to automatically track and update dependencies in the source code.

CAVEAT

This is experimental software, as of June 2024. It was originally written to work specifically in the Google source tree, and may make assumptions, or have gaps, that are immediately and embarrassingly evident in other types of code.

While we work to get IWYU quality up, we will be stinting new features, and will prioritize reported bugs along with the many existing, known bugs. The best chance of getting a problem fixed is to submit a patch that fixes it (along with a test case that verifies the fix)!

Clang compatibility

Include-what-you-use makes heavy use of Clang internals, and will occasionally break when Clang is updated. We build IWYU regularly against Clang mainline to detect and fix such compatibility breaks as soon as possible.

NOTE: the IWYU master branch follows Clang main branch.

We also have convenience tags and branches for released versions of Clang (called clang_<version>, e.g. clang_5.0). To build against a Clang release, check out the corresponding branch in IWYU before configuring the build. You can use this mapping table to combine Clang and IWYU versions correctly:

Clang	IWYU version	IWYU branch
3.6	0.4	clang_3.6
3.7	0.5	clang_3.7
3.8	0.6	clang_3.8
3.9	0.7	clang_3.9
4.0	0.8	clang_4.0-r2
5.0	0.9	clang_5.0
6	0.10	clang_6.0
7	0.11	clang_7.0
8	0.12	clang_8.0
9	0.13	clang_9.0
10	0.14	clang_10
11	0.15	clang_11
12	0.16	clang_12
13	0.17	clang_13
14	0.18	clang_14
15	0.19	clang_15
16	0.20	clang_16
17	0.21	clang_17
18	0.22	clang_18
19	0.23	clang_19
20	0.24	clang_20
21	0.25	clang_21
22	0.26	clang_22
23	0.27	clang_23
...	...	...
main		master

NOTE: If you use the Debian/Ubuntu packaging available from https://apt.llvm.org, you'll need the following packages installed:

• llvm-<version>-dev
• libmlir-<version>-dev
• libclang-<version>-dev
• clang-<version>

Packaging for other platforms will likely be subtly different.

How to download

IWYU is released in source form, both as GitHub releases and to https://include-what-you-use.org.

Releases are signed; you can find the public PGP key used to sign at https://include-what-you-use.org/downloads/[email protected].

To verify a release archive after download:

• Download and dearmor the public key:

  $ curl https://include-what-you-use.org/downloads/[email protected] |
      gpg -o iwyu.pub --dearmor -
  

• Assuming a downloaded 0.24 source archive and associated signature, verify the archive using the dearmored key:

  $ ls -1 0.24.tar.gz*
  0.24.tar.gz
  0.24.tar.gz.asc
  
  $ gpg --no-default-keyring --keyring ./iwyu.pub --verify 0.24.tar.gz.asc 0.24.tar.gz
  gpg: Signature made Sat 05 Apr 2025 12:06:53 PM CEST
  gpg:                using EDDSA key ...
  gpg: Good signature from "Kim Gräsman <[email protected]>" [ultimate]
  

Each release will also have a tag named as the version number without decoration, so for example the 0.24 release will be tagged 0.24. Cloning the Git repo and checking out a tag X should give the same snapshot as downloading the source archive X.tar.gz or X.zip (or include-what-you-use-X.src.tar.gz from include-what-you-use.org).

How to build standalone

This build mode assumes you already have compiled LLVM and Clang libraries on your system, either via packages for your platform or built from source. To set up an environment for building IWYU:

• Create a directory for IWYU development, e.g. iwyu

• Clone the IWYU Git repo:

  iwyu$ git clone https://github.com/include-what-you-use/include-what-you-use.git
  

• Presumably, you'll be building IWYU with a released version of LLVM and Clang, so check out the corresponding branch. For example, if you have Clang 6.0 installed, use the clang_6.0 branch. IWYU master tracks LLVM & Clang main:

  iwyu$ cd include-what-you-use
  iwyu/include-what-you-use$ git checkout clang_6.0
  

This is the beginning of the README. Read the rest at the original. Read the full README ↗