README.md
1# Include What You Use #
2
3[](https://travis-ci.org/include-what-you-use/include-what-you-use)
4
5For more in-depth documentation, see [docs](docs).
6
7## Instructions for Users ##
8
9"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.
10
11This 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.
12
13### CAVEAT ###
14
15This is alpha quality software -- at best (as of July 2018). 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.
16
17While 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)!
18
19### How to Build ###
20
21Include-what-you-use makes heavy use of Clang internals, and will occasionally break when Clang is updated. Usually such discrepancies are detected by build bot and fixed promptly.
22
23**The IWYU master branch follows Clang trunk**.
24
25We 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. More details in the instructions below.
26
27We assume you already have compiled LLVM and Clang libraries on your system, either via packages for your platform or built from source. You can use this mapping table to combine Clang and IWYU versions correctly:
28
29| Clang | IWYU version | IWYU branch |
30|--------|--------------|----------------|
31| 3.6 | 0.4 | `clang_3.6` |
32| 3.7 | 0.5 | `clang_3.7` |
33| 3.8 | 0.6 | `clang_3.8` |
34| 3.9 | 0.7 | `clang_3.9` |
35| 4.0 | 0.8 | `clang_4.0-r2` |
36| 5.0 | 0.9 | `clang_5.0` |
37| 6 | 0.10 | `clang_6.0` |
38| 7 | 0.11 | `clang_7.0` |
39| 8 | 0.12 | `clang_8.0` |
40| 9 | 0.13 | `clang_9.0` |
41| 10 | 0.14 | `clang_10` |
42| ... | ... | ... |
43| trunk | master | `master` |
44
45> NOTE: If you use the Debian/Ubuntu packaging available from <https://apt.llvm.org>, you'll need the following packages installed:
46>
47> * `llvm-<version>-dev`
48> * `libclang-<version>-dev`
49> * `clang-<version>`
50>
51> Packaging for other platforms will likely be subtly different.
52
53To set up an environment for building:
54
55* Create a directory for IWYU development, e.g. `iwyu`
56
57* Clone the IWYU Git repo:
58
59 iwyu$ git clone https://github.com/include-what-you-use/include-what-you-use.git
60
61* 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 trunk:
62
63 iwyu$ cd include-what-you-use
64 iwyu/include-what-you-use$ git checkout clang_6.0
65
66* Create a build root and use CMake to generate a build system linked with LLVM/Clang prebuilts:
67
68 # This example uses the Makefile generator, but anything should work.
69 iwyu/include-what-you-use$ cd ..
70 iwyu$ mkdir build && cd build
71
72 # For IWYU 0.10/Clang 6 and earlier
73 iwyu/build$ cmake -G "Unix Makefiles" -DIWYU_LLVM_ROOT_PATH=/usr/lib/llvm-6.0 ../include-what-you-use
74
75 # For IWYU 0.11/Clang 7 and later
76 iwyu/build$ cmake -G "Unix Makefiles" -DCMAKE_PREFIX_PATH=/usr/lib/llvm-7 ../include-what-you-use
77
78 (substitute the `llvm-6.0` or `llvm-7` suffixes with the actual version compatible with your IWYU branch)
79
80 or, if you have a local LLVM and Clang build tree, you can specify that as `CMAKE_PREFIX_PATH` for IWYU 0.11 and later:
81
82 iwyu/build$ cmake -G "Unix Makefiles" -DCMAKE_PREFIX_PATH=/llvm-trunk/build ../include-what-you-use
83
84* Once CMake has generated a build system, you can invoke it directly from `build`, e.g.
85
86 iwyu/build$ make
87
88Instructions for building Clang are available at <https://clang.llvm.org/get_started.html>.
89
90### How to Install ###
91
92If you're building IWYU out-of-tree or installing pre-built binaries, you need to make sure it can find Clang built-in headers (`stdarg.h` and friends.)
93
94Clang's default policy is to look in `path/to/clang-executable/../lib/clang/<clang ver>/include`. So if Clang 3.5.0 is installed in `/usr/bin`, it will search for built-ins in `/usr/lib/clang/3.5.0/include`.
95
96Clang tools have the same policy by default, so in order for IWYU to analyze any non-trivial code, it needs to find Clang's built-ins in `path/to/iwyu/../lib/clang/3.5.0/include` where `3.5.0` is a stand-in for the version of Clang your IWYU was built against.
97
98Note that some distributions/packages may have different defaults, you can use `clang -print-resource-dir` to find the base path of the built-in headers on your system.
99
100So for IWYU to function correctly, you need to copy the Clang `include` directory to the expected location before running (similarly, use `include-what-you-use -print-resource-dir` to learn exactly where IWYU wants the headers).
101
102This weirdness is tracked in [issue 100](https://github.com/include-what-you-use/include-what-you-use/issues/100), hopefully we can make this more transparent over time.
103
104### How to Run ###
105
106The original design was built for Make, but a number of alternative run modes have come up over the years.
107
108#### Plugging into Make ####
109
110The easiest way to run IWYU over your codebase is to run
111
112 make -k CXX=/path/to/llvm/Debug+Asserts/bin/include-what-you-use
113
114or
115
116 make -k CXX=/path/to/llvm/Release/bin/include-what-you-use
117
118(include-what-you-use always exits with an error code, so the build system knows it didn't build a .o file. Hence the need for `-k`.)
119
120Include-what-you-use only analyzes .cc (or .cpp) files built by `make`, along with their corresponding .h files. If your project has a .h file with no corresponding .cc file, IWYU will ignore it unless you use the `--check_also` switch to add it for analysis together with a .cc file.
121
122#### Using with CMake ####
123
124CMake has grown native support for IWYU as of version 3.3. See [their documentation](https://cmake.org/cmake/help/latest/prop_tgt/LANG_INCLUDE_WHAT_YOU_USE.html) for CMake-side details.
125
126The `CMAKE_CXX_INCLUDE_WHAT_YOU_USE` option enables a mode where CMake first compiles a source file, and then runs IWYU on it.
127
128Use it like this:
129
130 mkdir build && cd build
131 CC="clang" CXX="clang++" cmake -DCMAKE_CXX_INCLUDE_WHAT_YOU_USE="path/to/iwyu;-Xiwyu;any;-Xiwyu;iwyu;-Xiwyu;args" ...
132
133or, on Windows systems:
134
135 mkdir build && cd build
136 cmake -DCMAKE_CXX_COMPILER="%VCINSTALLDIR%/bin/cl.exe" -DCMAKE_CXX_INCLUDE_WHAT_YOU_USE="path/to/iwyu;-Xiwyu;any;-Xiwyu;iwyu;-Xiwyu;args" -G Ninja ...
137
138The option appears to be separately supported for both C and C++, so use `CMAKE_C_INCLUDE_WHAT_YOU_USE` for C code.
139
140Note that with Microsoft's Visual C++ compiler, IWYU needs the `--driver-mode=cl` argument to understand the MSVC options from CMake.
141
142#### Using with a compilation database ####
143
144The `iwyu_tool.py` script predates the native CMake support, and works off the [compilation database format](https://clang.llvm.org/docs/JSONCompilationDatabase.html). For example, CMake generates such a database named `compile_commands.json` with the `CMAKE_EXPORT_COMPILE_COMMANDS` option enabled.
145
146The script's command-line syntax is designed to mimic Clang's LibTooling, but they are otherwise unrelated. It can be used like this:
147
148 mkdir build && cd build
149 CC="clang" CXX="clang++" cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON ...
150 iwyu_tool.py -p .
151
152or, on Windows systems:
153
154 mkdir build && cd build
155 cmake -DCMAKE_CXX_COMPILER="%VCINSTALLDIR%/bin/cl.exe" -DCMAKE_C_COMPILER="%VCINSTALLDIR%/VC/bin/cl.exe" -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -G Ninja ...
156 python iwyu_tool.py -p .
157
158Unless a source filename is provided, all files in the project will be analyzed.
159
160See `iwyu_tool.py --help` for more options.
161
162#### Applying fixes ####
163
164We also include a tool that automatically fixes up your source files based on the IWYU recommendations. This is also alpha-quality software! Here's how to use it (requires python):
165
166 make -k CXX=/path/to/llvm/Debug+Asserts/bin/include-what-you-use 2> /tmp/iwyu.out
167 python fix_includes.py < /tmp/iwyu.out
168
169If you don't like the way `fix_includes.py` munges your `#include` lines, you can control its behavior via flags. `fix_includes.py --help` will give a full list, but these are some common ones:
170
171* `-b`: Put blank lines between system and Google includes
172* `--nocomments`: Don't add the 'why' comments next to includes
173
174### How to Correct IWYU Mistakes ###
175
176* If `fix_includes.py` has removed an `#include` you actually need, add it back in with the comment '`// IWYU pragma: keep`' at the end of the `#include` line. Note that the comment is case-sensitive.
177* If `fix_includes.py` has added an `#include` you don't need, just take it out. We hope to come up with a more permanent way of fixing later.
178* If `fix_includes.py` has wrongly added or removed a forward-declare, just fix it up manually.
179* If `fix_includes.py` has suggested a private header file (such as `<bits/stl_vector.h>`) instead of the proper public header file (`<vector>`), you can fix this by inserting a specially crafted comment near top of the private file (assuming you can write to it): '`// IWYU pragma: private, include "the/public/file.h"`'.
180
181Current IWYU pragmas are described in [IWYUPragmas](docs/IWYUPragmas.md).
182
){kind=link}