diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 32 |
1 files changed, 21 insertions, 11 deletions
@@ -40,6 +40,8 @@ We assume you already have compiled LLVM and Clang libraries on your system, eit | 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` | | ... | ... | ... | | main | | `master` | @@ -106,19 +108,23 @@ This weirdness is tracked in [issue 100](https://github.com/include-what-you-use The original design was built for Make, but a number of alternative run modes have come up over the years. -#### Plugging into Make #### +#### Running on single source file #### -The easiest way to run IWYU over your codebase is to run +The simplest way to use IWYU is to run it against a single source file: - make -k CXX=/path/to/llvm/Debug+Asserts/bin/include-what-you-use + include-what-you-use $CXXFLAGS myfile.cc -or +where `$CXXFLAGS` are the flags you would normally pass to the compiler. - make -k CXX=/path/to/llvm/Release/bin/include-what-you-use +#### Plugging into existing build system #### -(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`.) +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: -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. + make -k CXX=include-what-you-use CXXFLAGS="-Xiwyu --error_always" + +(The additional `-Xiwyu --error_always` switch makes `include-what-you-use` always exit with an error code, so the build system knows it didn't build a .o file. Hence the need for `-k`.) + +In this mode `include-what-you-use` only analyzes the .cc (or .cpp) files known to your build system, 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. It is possible to run IWYU against individual header files, provided the compiler flags are carefully constructed to match all includers. #### Using with CMake #### @@ -129,12 +135,16 @@ The `CMAKE_CXX_INCLUDE_WHAT_YOU_USE` option enables a mode where CMake first com Use it like this: mkdir build && cd build - CC="clang" CXX="clang++" cmake -DCMAKE_CXX_INCLUDE_WHAT_YOU_USE="path/to/iwyu;-Xiwyu;any;-Xiwyu;iwyu;-Xiwyu;args" ... + CC="clang" CXX="clang++" cmake -DCMAKE_CXX_INCLUDE_WHAT_YOU_USE=include-what-you-use ... 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;-Xiwyu;any;-Xiwyu;iwyu;-Xiwyu;args" -G Ninja ... + cmake -DCMAKE_CXX_COMPILER="%VCINSTALLDIR%/bin/cl.exe" -DCMAKE_CXX_INCLUDE_WHAT_YOU_USE=include-what-you-use -G Ninja ... + +These examples assume that `include-what-you-use` is in the `PATH`. If it isn't, consider changing the value to an absolute path. Arguments to IWYU can be added using CMake's semicolon-separated list syntax, e.g.: + + ... cmake -DCMAKE_CXX_INCLUDE_WHAT_YOU_USE="include-what-you-use;-w;-Xiwyu;--verbose=7" ... The option appears to be separately supported for both C and C++, so use `CMAKE_C_INCLUDE_WHAT_YOU_USE` for C code. @@ -142,7 +152,7 @@ Note that with Microsoft's Visual C++ compiler, IWYU needs the `--driver-mode=cl #### Using with a compilation database #### -The `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. +The `iwyu_tool.py` script pre-dates 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. The script's command-line syntax is designed to mimic Clang's LibTooling, but they are otherwise unrelated. It can be used like this: @@ -164,7 +174,7 @@ See `iwyu_tool.py --help` for more options. 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 + make -k CXX=include-what-you-use CXXFLAGS="-Xiwyu --error_always" 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: |