Include what you use

include-what-you-use

A tool for use with clang to analyze #includes in C and C++ source files

31 Mar 2022

iwyu 0.18 compatible with llvm+clang 14 is released. Major changes:

Note the breaking change for exit codes; IWYU now always returns zero by default. See the README for more information and manual overrides.

For the full list of closed issues see the iwyu 0.18 milestone.

Contributions in this release by Carlos Galvez and Kim Grasman. Sorry if we’ve missed anyone.

The source code can be downloaded from include-what-you-use-0.18.src.tar.gz. It is equivalent to the 0.18 tag and clang_14 branch.

05 Dec 2021

iwyu 0.17 compatible with llvm+clang 13 is released. Major changes:

For the full list of closed issues see the iwyu 0.17 milestone.

Contributions in this release by Alejandro Colomar, Bolshakov, David Fetter, Kim Grasman, Omar Sandoval, Salman Javed, Sven Panne. Sorry if we’ve missed anyone.

The source code can be downloaded from include-what-you-use-0.17.src.tar.gz. It is equivalent to the 0.17 tag and clang_13 branch.

26 May 2021

iwyu 0.16 compatible with llvm+clang 12 is released. Major changes:

For the full list of closed issues see the iwyu 0.16 milestone.

Contributions in this release by Alexey Storozhev, Florian Schmaus, Kim Grasman, Omer Anson, saki7. Sorry if we’ve missed anyone.

The source code can be downloaded from include-what-you-use-0.16.src.tar.gz. It is equivalent to the 0.16 tag and clang_12 branch.

21 November 2020

iwyu 0.15 compatible with llvm+clang 11 is released. Major changes:

For the full list of closed issues see the iwyu 0.15 milestone.

Contributions in this release by Andrea Bocci, David Callu, Emil Gedda, Florian Schmaus, John Bytheway, Kim Grasman, Liam Keegan, Omar Sandoval, pppyx, Romain Geissler, Seth R Johnson, Tim Gates. Sorry if we’ve missed anyone.

The source code can be downloaded from include-what-you-use-0.15.src.tar.gz. It is equivalent to the 0.15 tag and clang_11 branch.

17 May 2020

iwyu 0.14 compatible with llvm+clang 10 is released. Major changes:

For the full list of closed issues see the iwyu 0.14 milestone.

Contributions in this release by Aaron Puchert, Kim Grasman, Miklos Vajna, Nick Overdijk, Uladzislau Paulovich. Sorry if we’ve missed anyone.

The source code can be downloaded from include-what-you-use-0.14.src.tar.gz. It is equivalent to the 0.14 tag and clang_10 branch.

26 October 2019

iwyu 0.13 compatible with llvm+clang 9.0 is released. Major changes:

For the full list of closed issues see the iwyu 0.13 milestone.

Contributions in this release by Alexander Grund, i-ky, John Bytheway, Julien Cabieces, Kim Grasman, Levente GyЕ‘zЕ‘ LГ©nГЎrt, Miklos Vajna, Uladzislau Paulovich and Zachary Henkel. Sorry if we’ve missed anyone.

The source code can be downloaded from include-what-you-use-0.13.src.tar.gz. It is equivalent to the 0.13 tag and clang_9.0 branch. Note that there’s no clang_9.0 tag this time, to avoid tag/branch confusion.

15 April 2019

iwyu 0.12 compatible with llvm+clang 8.0 is released. Major changes:

Contributions in this release by Asier Lacasta, David Robillard, Ignat Loskutov, Jakub Wilk, John Bytheway, J.Ru, Kim Grasman, Martin Villagra, Miklos Vajna, tomKPZ, Tom Rix. Sorry if we’ve missed anyone.

The source code can be downloaded from include-what-you-use-0.12.src.tar.gz. It is equivalent to the clang_8.0 tag.

8 December 2018

iwyu 0.11 compatible with llvm+clang 7.0 is released. Major changes:

Contributions in this release by Asier Lacasta, Christian Venegas, Ignat Loskutov, J.Ru, Kim Grasman, Martin Villagra, Paul Seyfert, Phantal, Philip Pfaffe, Scott Ramsby, Tom Rix, Victor Poughon. Sorry if we’ve missed anyone.

The source code can be downloaded from include-what-you-use-0.11.src.tar.gz. It is equivalent to the clang_7.0 tag.

30 April 2018

iwyu 0.10 compatible with llvm+clang 6.0 is released. Major changes:

Contributions in this release by bungeman, Kim GrГ¤sman, Alex Kirchhoff, J. Ru, Orgad Shaneh, Christoph Weiss. Sorry if we’ve missed anyone.

The source code can be downloaded from include-what-you-use-0.10.src.tar.gz. It is equivalent to the clang_6.0 tag.

11 March 2018

iwyu 0.9 compatible with llvm+clang 5.0 is released. Major changes:

Contributions in this release by J. Ru, Kim GrГ¤sman, Kristoffer Henriksson, Paul Seyfert. Sorry if we’ve missed anyone.

NOTE: From now on we will not be able to produce binary releases. There are well-maintained packages for several platforms, and we rely on community contributions to increase availability here.

The source code can be downloaded from include-what-you-use-0.9.src.tar.gz. It is equivalent to the clang_5.0 tag.

3 August 2017

iwyu 0.8 compatible with llvm+clang 4.0.0 is released. Major changes:

Contributions in this release by Eugene Zelenko, ivankoster, Kim GrГ¤sman, Kristoffer Henriksson, mineo, nocnokneo, svenpanne, Volodymyr Sapsai, xuzhen1994. Sorry if we’ve missed anyone.

The source code can be downloaded from include-what-you-use-0.8.src.tar.gz. It is equivalent to clang_4.0 tag.

30 October 2016

iwyu 0.7 compatible with llvm+clang 3.9 is released. Major changes:

Thanks for all your contributions and help Bothari, Eugene Zelenko, Flamefire, Kim GrГ¤sman. Sorry if I’ve missed anyone.

The source code can be downloaded from include-what-you-use-0.7.src.tar.gz. It is equivalent to clang_3.9 tag.

15 May 2016

iwyu 0.6 compatible with llvm+clang 3.8 is released. In this version we

Thanks for all your contributions and help JVApen, Kim GrГ¤sman, Philip Pfaffe, pseyfert, realazthat, Sylvestre Ledru, ThosRTanner. Sorry if I’ve missed anyone.

The source code can be downloaded from include-what-you-use-0.6.src.tar.gz. It is equivalent to clang_3.8 tag.

17 December 2015

iwyu 0.5 compatible with llvm+clang 3.7 is released. In this version we

Thanks for all your contributions Scott Howard, bungeman, tpltnt, Chris Glover, Kim GrГ¤sman. And thank you for all you help JГ©rГ©mie Delaitre, Richard Thomson, dpunset, Earnestly, Dave Johansen, ThosRTanner. Sorry if I’ve missed anyone.

The source code can be downloaded from include-what-you-use-0.5.src.tar.gz. It is equivalent to clang_3.7 tag.

4 June 2015

iwyu 0.4 compatible with llvm+clang 3.6 is released. It contains the following changes:

This release received many contributions and I want to thank SmSpillaz, Paul Redmond, Chris Glover, Ryan Pavlik, showard314, Fabian Gruber, Kim GrГ¤sman for your help. And thanks to Dave Johansen, MMendez534, Sylvestre Ledru for packaging include-what-you-use. Sorry if I’ve missed anyone.

The source code can be downloaded from include-what-you-use-0.4.src.tar.gz. It is equivalent to clang_3.6 tag.

25 November 2014

iwyu 0.3 compatible with llvm+clang 3.5 is released. In this version we have

The source code can be downloaded from include-what-you-use-3.5.src.tar.gz. It is equivalent to clang_3.5 tag.

22 February 2014

iwyu version compatible with llvm+clang 3.4 is released. The source code can be downloaded from include-what-you-use-3.4.src.tar.gz. It is equivalent to clang_3.4 tag.

11 August 2013

We are moving downloads to Google Drive. iwyu version compatible with llvm+clang 3.3 can be found at include-what-you-use-3.3.tar.gz. It is equivalent to clang_3.3 tag.

6 December 2011

24 June 2011

It was just pointed out to me the tarball I built against llvm+clang 2.9 doesn’t actually compile with llvm+clang 2.9. I must have made a mistake packaging it. I’ve tried again; according to my tests, anyway, the new version works as it’s supposed to.

8 June 2011

I finally got around to releasing a tarball that builds against llvm+clang 2.9. See the ‘downloads’ section on the side pane. This is a rather old version of iwyu at this point, so you’ll do much better to download a current clang+llvm and the svn-root version of include-what-you-use, and build from that. See README.txt for more details.

13 April 2011

Work has been continuing at a furious pace on include-what-you-use. It’s definitely beta quality by now. 🙂 Well, early beta. I’ve not been making regular releases, but the SVN repository is being frequently updated, so don’t take the lack of news here to mean a lack of activity.

4 February 2011

I’m very pleased to announce the very-alpha, version 0.1 release of include-what-you-use. See the wiki links on the right for instructions on how to download, install, and run include-what-you-use.

I’m releasing the code as it is now under a «release early and often» approach. It’s still very early in iwyu, and the program will probably have mistakes on any non-trivial piece of code. Furthermore, it still has google-specific bits that may not make much sense in an opensource release. This will all get fixed over time. Feel free to dig in and suggest patches to help the fixing along!

If you want to follow the discussion on include-what-you-use, and/or keep up to date with changes, subscribe to the Google Group.

Include what you use

Copy raw contents

Why include-what-you-use is difficult

This section is informational, for folks who are wondering why include-what-you-use requires so much code and yet still has so many errors.

Include-what-you-use has the most problems with templates and macros. If your code doesn’t use either, IWYU will probably do great. And, you’re probably not actually programming in C++.

Use versus forward declare

Include-what-you-use has to be able to tell when a symbol is being used in a way that you can forward-declare it. Otherwise, if you wrote

To distinguish these, clang has to instantiate the vector and scoped_ptr template classes, including analyzing all member variables and the bodies of the constructor and destructor (and recursively for superclasses).

Handling template arguments

Even figuring out what types are ‘used’ with a template can be difficult. Consider the following two declarations:

These both have default template arguments, so are parsed like

So it’s tempting to just ignore default template arguments. But that’s not right either. What if hash is defined in some local myhash.h file (as hash often is)? Then we want to make sure IWYU says to #include «myhash.h» when you create the hash_set (otherwise the code won’t compile). That requires paying attention to the default template argument. Figuring out how to handle default template arguments can get very complex.

Even normal template arguments can be confusing. Consider this templated function:

Who is responsible for dependent template types?

Now suppose there’s a template function like this:

strcat is a normal function, and the author of MyFunc is responsible for its use. This is an easy case.

As you can imagine, distinguishing all these cases is extremely difficult. To get it exactly right would require re-implementing C++’s (byzantine) lookup rules, which we have not yet tackled.

Template template types

Let’s say you have a function

Worse, when the language auto-derives template types, it loses typedef information. Suppose you wrote this:

Includes with side effects

If IWYU just blindly replaces the #include with a forward declare such as namespace ns < class Foo; >, the code will break because of the lost using declaration. Include-what-you-use has to watch out for this case.

Another case is a header file like this:

Conditional #includes are a problem for IWYU when the condition is false:

If you’re running IWYU without that preprocessor definition set, it has no way of telling if verbose_logger.h is a necessary #include or not.

Placing new includes and forward-declares

Include what you use

Why include what you use?

Are there any concrete benefits to a strict include-what-you-use policy? We like to think so.

Here, the main benefit of include-what-you-use comes from the flip side: «don’t include what you don’t use.»

Again, the main advantage here is from «don’t include what you don’t use.»

This is most compelling for a very large codebase (such as Google’s). In a small codebase, it’s practical to just compile everything after a refactor like this, and clean up any errors you see. When your codebase contains hundreds of thousands of source files, identifying and cleaning up the errors can be a project in itself. In practice, people are likely to just leave the #include line in there, even though it’s unnecessary.

Here, it’s the actual ‘include what you use’ policy that saves the day. If everyone who uses vector is #including themselves, then you can remove without fear of breaking anything.

The ‘commented’ #include lines can also make it simpler to match function calls and classes to the files that define them, without depending on a particular IDE.

(The downside, of course, is the comments can get out of date as the code changes, so unless you run IWYU often, you still have to take the comments with a grain of salt. Nothing is free. 🙂 )

Again, this makes the most sense for large code-bases. Suppose your binaries are larger than you would expect, and upon closer examination use symbols that seem totally irrelevant. Where do they come from? Why are they there? With include-what-you-use, you can easily determine this by seeing who includes the files that define these symbols: those includers, and those alone, are responsible for the use.

Include-what-you-use tries very hard to figure out when a forward-declare can be used instead of an #include (IWYU would be about 90% less code if it didn’t bother with trying to forward-declare).

The reason for this is simple: if you can replace an #include by a forward-declare, you reduce the code size, speeding up compiles as described above. You also make it easier to break dependencies: not only do you not depend on that header file, you no longer depend on everything it brings in.

We still think IWYU’s normal policy is preferable for all the reasons above, but if your codebase has a no-forward-declare policy, so does IWYU.

Include What You Use

I’ve used the clang based include-what-you-use tool on a fairly large chunk of code — a couple of hundreds of files, containing dozens of includes each.

That was an interesting experiment.

Here are my takeaways on this powerful tool, what it can bring to your code, and a few things I wish I had known when I started using it.

include-what-you-…what?

The tool has two goals: make sure that each file:

The first goal correspond to the name of the tool, “include what you use”, and the second one could be called “use what you include”.

The benefits of having clean header inclusions

There are multiple benefits in having such clean header inclusions.

Design benefit

One of them is that it gives you better vision of dependencies between files. After executing the cleaning with the tool, nearly every remaining (or added) #include represents a dependency (I say nearly because some #include s don’t count as dependencies: for example a class implementation file that #include s its own header file).

Before cleaning the header inclusions, some #include s may not be necessary. They can be remains of old developments, whose code has be deleted or refactored away to other files modules. Indeed, when changing code, it’s easy to forget to update the #include s.

Those remaining useless #include s create a shallow dependency: a dependency of compilation, because the compiler (or rather, the preprocessor) executes the inclusion, but not a design dependency, because no code really depends on that inclusion.

On the other hand, there can be symbols that the code of a file uses and that are not in the #include s of that file. This happens if those symbol are defined in files that are indirectly included. In this case, the #include section doesn’t give the full picture of the dependencies of the file.

After the header cleanup, you can see the exact dependencies of a given file.

Seeing dependencies is valuable because it is a good start for refactoring: if you see a dependency that doesn’t make sense, then you can work towards removing it. This helps improve the design and architecture of the code, which makes it easier to understand.

Other benefits

Another interesting benefit in cleaning header inclusions is that it can reduce them, and therefore reduce compilation time. Indeed, if you change a header that is #include d by many files, re-building your project takes time as it involves to recompile a large amount of files.

Removing useless inclusions can therefore reduce compilation time, without changing the outcome of the compilation. The compiler just stops making unnecessary work.

Another benefit of cleaning up is that clean headers are self-inclusive. This means that if you were to compile them on their own, they would compile without errors, and in particular without missing files.

In fact, self-inclusive headers is more a necessity that a benefit. Without self-inclusive header, you can’t #include headers in any order, because they depend on the #include s of each other.

Without self-inclusive errors, you can get weird problems, such as changing a header and having compilation errors popping up in an unrelated file that you then need to fix because it wasn’t self-inclusive and relied on the header you’re changing.

The errors generated by the cleaning

Although a powerful tool, include-what-you-use isn’t a perfect one, as some files no longer compile after cleaning.

I haven’t see a recurring pattern but here are some of the errors I saw:

It may just be me incorrectly configuring the tool, or it may be bugs in the tool. It doesn’t matter that much, as those were very sparse errors in comparison with the volume of code that the tool treated correctly.

But what is useful to know is that sparse errors can generate a very, very large volume of error messages. Indeed, if those errors happen to be located in central header files, then the errors get generated in many compilation units.

As a result, the amount of errors messages can be daunting at first sight.

Treating errors

The best way I’ve found to treat those errors is to be very methodic.

First, group the errors by file. Maybe your IDE will do it for you, or if you get a raw output from your compiler you can put them into a Pivot Table in Excel in order to extract the file names and count duplicates.

Removing duplicate errors ensures that you won’t see the same error more than once. In my case, one single wrong include was responsible of more than half of the error messages! Fixing it took a few seconds, and it reduced the number of errors left to treat by two. This is energizing.

Taking care of the errors file by file also allows to accelerate the fixes, because you won’t have to jump from one file to another all the time.

All in all, it took me little time to go over the remaining changes to make after the tool ran, and all this experiment had a dramatic effect on the header inclusions of the files.

Make your code include what it uses

In conclusion, I recommend that you try include-what-you-use on your code, in order to clarify its dependencies, improve its compilation time and ensure that headers are self-inclusive.

When you do, please leave a comment here to let me know how that went, and if you have additional advice about how to use the tool efficiently.

And if you already tried it, please let us know about your experience now!

include-what-you-use/include-what-you-use

Use Git or checkout with SVN using the web URL.

Work fast with our official CLI. Learn more.

Launching GitHub Desktop

If nothing happens, download GitHub Desktop and try again.

Launching GitHub Desktop

If nothing happens, download GitHub Desktop and try again.

Launching Xcode

If nothing happens, download Xcode and try again.

Launching Visual Studio Code

Your codespace will open once ready.

There was a problem preparing your codespace, please try again.

Latest commit

Git stats

Files

Failed to load latest commit information.

README.md

Include What You Use

For more in-depth documentation, see docs.

Instructions for users

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.

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)!

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.

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

Packaging for other platforms will likely be subtly different.

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:

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 :

Create a build root and use CMake to generate a build system linked with LLVM/Clang prebuilts:

(substitute the llvm-6.0 or llvm-7 suffixes with the actual version compatible with your IWYU branch)

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:

How to build as part of LLVM

Instructions for building LLVM and Clang are available at https://clang.llvm.org/get_started.html.

To include IWYU in the LLVM build, use the LLVM_EXTERNAL_PROJECTS and LLVM_EXTERNAL_*_SOURCE_DIR CMake variables when configuring LLVM:

This builds all of LLVM, Clang and IWYU in a single tree.

If 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.)

Clang 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.

This weirdness is tracked in issue 100, hopefully we can make this more transparent over time.

The original design was built for Make, but a number of alternative run modes have come up over the years.

Running on single source file

The simplest way to use IWYU is to run it against a single source file:

Plugging into existing build system

Typically there is already a build system containing the relevant compiler flags for all source files. Replace your compiler with include-what-you-use to generate a large batch of IWYU advice. Depending on your build system/build tools, this can take many forms, but for a simple GNU Make system it might look like this:

Using with CMake

CMake has grown native support for IWYU as of version 3.3. See their documentation for CMake-side details.

The CMAKE_CXX_INCLUDE_WHAT_YOU_USE option enables a mode where CMake first compiles a source file, and then runs IWYU on it.

Use it like this:

or, on Windows systems:

The option appears to be separately supported for both C and C++, so use CMAKE_C_INCLUDE_WHAT_YOU_USE for C code.

Using with a compilation database

The iwyu_tool.py script pre-dates the native CMake support, and works off the compilation database format. For example, CMake generates such a database named compile_commands.json with the CMAKE_EXPORT_COMPILE_COMMANDS option enabled.

The script’s command-line syntax is designed to mimic Clang’s LibTooling, but they are otherwise unrelated. It can be used like this:

or, on Windows systems:

Unless a source filename is provided, all files in the project will be analyzed.

We 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):

How to correct IWYU mistakes

Current IWYU pragmas are described in IWYUPragmas.

About

A tool for use with clang to analyze #includes in C and C++ source files