A tool for use with clang to analyze #includes in C and C++ source files
C++ Python C Other
Latest commit 6e28b99 Jun 30, 2017 @kimgr kimgr committed with kimgr Add .H as a known header extension
Both in IWYU and fix_includes.py.

Fix issue #452.
Permalink
Failed to load latest commit information.
docs Commit first canonical README Jul 9, 2017
more_tests Terminology: as-typed -> as-written Sep 4, 2016
tests Fix requiring allocator for getting container iterator with libc++. (#… Jul 3, 2017
.clang-format Unix line endings for .clang-format Mar 1, 2016
.gitignore Add .gitignore Jun 13, 2017
CMakeLists.txt Update to reflect changes in LLVM. Jun 9, 2017
CONTRIBUTING.md Copy InstructionsForDevelopers to CONTRIBUTING Jul 4, 2017
LICENSE.TXT Clean up third-party license listing Nov 11, 2015
README.md Commit first canonical README Jul 9, 2017
boost-all-private.imp Collect Boost and Qt mappings created by Scott Howard aka @maqifrnswa. Sep 10, 2015
boost-all.imp Collect Boost and Qt mappings created by Scott Howard aka @maqifrnswa. Sep 10, 2015
dist.sh Add shebang line and specify error handling options in dist.sh script. Oct 20, 2013
fix_includes.py Add .H as a known header extension Jul 15, 2017
fix_includes_test.py Add .H as a known header extension Jul 15, 2017
gcc.libc.imp Add more libc mapping(s). Feb 2, 2016
gcc.stl.headers.imp Fix issue #88: GCC header map lists some private headers as public Feb 18, 2013
gcc.symbols.imp Map FILE to <stdio.h> Jul 2, 2017
iwyu.cc Fix requiring allocator for getting container iterator with libc++. (#… Jul 3, 2017
iwyu.gcc.imp Specify public STL headers explicitly (issue #132). Sep 28, 2014
iwyu_ast_util.cc Pick up more sugar for function arguments Feb 21, 2017
iwyu_ast_util.h Add optional terse flag to PrintableDecl Feb 21, 2017
iwyu_cache.cc Handle precomputed template arguments in libc++ like in libstdc++ (is… Sep 7, 2014
iwyu_cache.h Fix Clang-tidy warnings Nov 16, 2016
iwyu_driver.cc Update to reflect changes in Clang Jan 6, 2017
iwyu_driver.h Make header guards consistent May 25, 2016
iwyu_getopt.cc Added getopt_long for Windows (resolves issue #52). Aug 11, 2012
iwyu_getopt.h Make header guards consistent May 25, 2016
iwyu_globals.cc Fix Clang-tidy warnings Nov 16, 2016
iwyu_globals.h Fix inconsistent parameter names Aug 15, 2016
iwyu_include_picker.cc Map FILE to <stdio.h> Jul 2, 2017
iwyu_include_picker.h Fix Clang-tidy warnings Nov 16, 2016
iwyu_lexer_utils.cc Allow IWYU pragma: keep on forward declarations as an escape hatch fo… Jun 21, 2017
iwyu_lexer_utils.h Allow IWYU pragma: keep on forward declarations as an escape hatch fo… Jun 21, 2017
iwyu_location_util.cc Fix Clang-tidy warnings Nov 16, 2016
iwyu_location_util.h Update to reflect changes in Clang. Oct 11, 2016
iwyu_output.cc Accept methods hiding using declarations May 8, 2017
iwyu_output.h Fix inconsistent parameter names Aug 15, 2016
iwyu_path_util.cc Add .H as a known header extension Jul 15, 2017
iwyu_path_util.h Use absolute paths to build include names Jun 8, 2016
iwyu_preprocessor.cc Allow IWYU pragma: keep on forward declarations as an escape hatch fo… Jun 21, 2017
iwyu_preprocessor.h Add pragma to set associated header Mar 10, 2017
iwyu_stl_util.h Fix #310: Replace Each with C++11 range for loops Jul 11, 2016
iwyu_string_util.h Fix some Clang-tidy warnings Jun 7, 2016
iwyu_test_util.py Clean up output from test runner Aug 15, 2016
iwyu_tool.py Add a new option for a more tool-friendly output. Nov 28, 2016
iwyu_verrs.cc Fixed file heading comments not matching the filename (issue #83). Pa… Nov 25, 2012
iwyu_verrs.h Handle internal headers guarded by macro and x-macros (fix issue #109). Aug 15, 2016
iwyu_version.h Bump versino to 0.8 on master Oct 29, 2016
libcxx.imp Add tweaks for declval, forward and nullptr_t Feb 28, 2017
port.h Explicitly use ASCII version of PathMatchSpec Jul 10, 2016
qt4.imp Collect Boost and Qt mappings created by Scott Howard aka @maqifrnswa. Sep 10, 2015
qt5_4.imp Mappings for qt5.4 Jan 2, 2016
run_iwyu_tests.py Add test coverage for simple function pointer expressions May 17, 2017
scrub-logs.py Let scrub-logs accept input from stdin May 6, 2017
stl.c.headers.imp Specify public STL headers explicitly (issue #132). Sep 28, 2014
third_party.imp Read private to public mappings from external file. Patch by Kim Gräs… Oct 14, 2012

README.md

Include What You Use

For more in-depth documentation, see http://github.com/include-what-you-use/include-what-you-use/tree/master/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 alpha quality software -- at best (as of February 2011). It was 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. For instance, we only run this on C++ code, not C or Objective C. Even for Google code, the tool still makes a lot of mistakes.

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 unittest case that verifies the fix)!

How to Build

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

We support two build configurations: out-of-tree and in-tree.

Building out-of-tree

In an out-of-tree configuration, we assume you already have compiled LLVM and Clang headers and libs somewhere on your filesystem, such as via the libclang-dev package.

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

  • Clone the IWYU Git repo:

    iwyu-trunk$ 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 3.2 installed, use the clang_3.2 branch. IWYU master tracks LLVM & Clang trunk:

    iwyu-trunk$ cd include-what-you-use
    iwyu-trunk/include-what-you-use$ git checkout clang_3.2
    iwyu-trunk/include-what-you-use$ cd ..
    
  • Create a build root and use CMake to generate a build system linked with LLVM/Clang prebuilts. Note that CMake settings need to match exactly, so you may need to add -DCMAKE_BUILD_TYPE=Release or more to the command-line below:

    # This example uses the Makefile generator, but anything should work.
    iwyu-trunk$ mkdir build && cd build
    iwyu-trunk/build$ cmake -G "Unix Makefiles" -DIWYU_LLVM_ROOT_PATH=/usr/lib/llvm-3.4 ../include-what-you-use
    
  • Once CMake has generated a build system, you can invoke it directly from build, e.g.

    iwyu-trunk/build$ make
    

This configuration is more useful if you want to get IWYU up and running quickly without building Clang and LLVM from scratch.

Building in-tree

You will need the Clang and LLVM trees on your system, such as by checking out their SVN trees (but don't configure or build before you've done the following.)

  • Clone the IWYU Git repo into the Clang source tree:

    llvm/tools/clang/tools$ git clone https://github.com/include-what-you-use/include-what-you-use.git
    
  • Edit tools/clang/tools/CMakeLists.txt and put in add_subdirectory(include-what-you-use)

  • Once this is done, IWYU is recognized and picked up by CMake workflow as described in the Clang Getting Started guide

This configuration is more useful if you're actively developing IWYU against Clang trunk. It's easier to set up correctly, but it requires that you build all of LLVM and Clang.

How to Install

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

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.

So for IWYU to function correctly, you need to copy in the Clang headers at a good location before running.

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

How to Run

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

Plugging into Make

The easiest way to run IWYU over your codebase is to run

  make -k CXX=/path/to/llvm/Debug+Asserts/bin/include-what-you-use

or

  make -k CXX=/path/to/llvm/Release/bin/include-what-you-use

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

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

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:

  mkdir build && cd build
  CC="clang" CXX="clang++" cmake -DCMAKE_CXX_INCLUDE_WHAT_YOU_USE="path/to/iwyu any iwyu args" ...

or, on Windows systems:

  mkdir build && cd build
  cmake -DCMAKE_CXX_COMPILER="%VCINSTALLDIR%/bin/cl.exe" -DCMAKE_CXX_INCLUDE_WHAT_YOU_USE="path/to/iwyu any iwyu args" -G Ninja ...

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

Note that with Microsoft's Visual C++ compiler, IWYU needs the --driver-mode=cl argument to understand the MSVC options from CMake.

Using with a compilation database

The iwyu_tool.py script predates 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:

  mkdir build && cd build
  CC="clang" CXX="clang++" cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON ...
  iwyu_tool.py -p .

or, on Windows systems:

  mkdir build && cd build
  cmake -DCMAKE_CXX_COMPILER="%VCINSTALLDIR%/bin/cl.exe" -DCMAKE_C_COMPILER="%VCINSTALLDIR%/VC/bin/cl.exe" -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -G Ninja ...
  python iwyu_tool.py -p .

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

See iwyu_tool.py --help for more options.

Applying fixes

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

  make -k CXX=/path/to/llvm/Debug+Asserts/bin/include-what-you-use 2> /tmp/iwyu.out
  python fix_includes.py < /tmp/iwyu.out

If 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:

  • -b: Put blank lines between system and Google includes
  • --nocomments: Don't add the 'why' comments next to includes

How to Correct IWYU Mistakes

  • 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.
  • 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.
  • If fix_includes.py has wrongly added or removed a forward-declare, just fix it up manually.
  • 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"'.

Current IWYU pragmas are described in IWYUPragmas.