Introduction

WARNING: This is all very alpha. Proceed at your own risk. Also, these instructions are very out of date -- IWYU currently isn't generally usable, so we stopped looking at it for chromium.

See include what you use page for background about what it is and why it is important.

This page describes running IWYU for Chromium. It currently only covers Mac, but it would be nice to get Linux instructions here as well.

Mac

Setup

1. Checkout and build IWYU (This will also check out and build clang. See Clang page for details.)

$ cd /path/to/src/
$ tools/clang/scripts/update_iwyu.sh

2. Ensure "Continue building after errors" is enabled in the Xcode Preferences UI.

Chromium

1. Build Chromium. Be sure to substitute in the correct absolute path for /path/to/src/.

$ GYP_DEFINES='clang=1' gclient runhooks
$ cd chrome
$ xcodebuild -configuration Release -target chrome OBJROOT=/path/to/src/clang/obj DSTROOT=/path/to/src/clang SYMROOT=/path/to/src/clang CC=/path/to/src/third_party/llvm-build/Release+Asserts/bin/clang++

2. Run IWYU. Be sure to substitute in the correct absolute path for /path/to/src/.

$ xcodebuild -configuration Release -target chrome OBJROOT=/path/to/src/clang/obj DSTROOT=/path/to/src/clang SYMROOT=/path/to/src/clang CC=/path/to/src/third_party/llvm-build/Release+Asserts/bin/include-what-you-use

WebKit

1. Build TestShell. Be sure to substitute in the correct absolute path for /path/to/src/.

$ GYP_DEFINES='clang=1' gclient runhooks
$ cd webkit
$ xcodebuild -configuration Release -target test_shell OBJROOT=/path/to/src/clang/obj DSTROOT=/path/to/src/clang SYMROOT=/path/to/src/clang CC=/path/to/src/third_party/llvm-build/Release+Asserts/bin/clang++

2. Run IWYU. Be sure to substitute in the correct absolute path for /path/to/src/.

$ xcodebuild -configuration Release -target test_shell OBJROOT=/path/to/src/clang/obj DSTROOT=/path/to/src/clang SYMROOT=/path/to/src/clang CC=/work/chromium/src/third_party/llvm-build/Release+Asserts/bin/include-what-you-use

Bragging

You can run tools/include_tracer.py to get header file sizes before and after running iwyu. You can then include stats like "This reduces the size of foo.h from 2MB to 80kB" in your CL descriptions.

Known Issues

We are a long way off from being able to accept the results of IWYU for Chromium/WebKit. However, even in its current state it can be a useful tool for finding forward declaration opportunities and unused includes.

1. The biggest source of noise seems to be that it doesn't understand the include paths. For instance, it suggests replacing #include "Document.h" with #include "../../WebCore/dom/Document.h". The tool will become much more useful when that is fixed upstream. See issue 5