| OLD | NEW | 
 | (Empty) | 
|   1 # Introduction |  | 
|   2  |  | 
|   3 **WARNING:** This is all very alpha. Proceed at your own risk. The Mac instructi
    ons are very out of date -- IWYU currently isn't generally usable, so we stopped
     looking at it for chromium. |  | 
|   4  |  | 
|   5 See [include what you use page](http://code.google.com/p/include-what-you-use/) 
    for background about what it is and why it is important. |  | 
|   6  |  | 
|   7 This page describes running IWYU for Chromium. |  | 
|   8  |  | 
|   9 # Linux/Blink |  | 
|  10  |  | 
|  11 ## Running IWYU |  | 
|  12  |  | 
|  13 These instructions have a slightly awkward workflow. Ideally we should use somet
    hing like `CXX=include-what-you-use GYP_DEFINES="clang=1" gclient runhooks; ninj
    a -C out/Debug webkit -k 10000` if someone can get it working. |  | 
|  14  |  | 
|  15   * Install include-what-you-use (see [here](https://code.google.com/p/include-w
    hat-you-use/wiki/InstructionsForUsers)). Make sure to use --enable-optimized=YES
     when building otherwise IWYU will be very slow. |  | 
|  16   * Get the compilation commands from ninja (using g++), and derive include-what
    -you-use invocations from it |  | 
|  17 ``` |  | 
|  18 $ cd /path/to/chromium/src |  | 
|  19 $ ninja -C out/Debug content_shell -v > ninjalog.txt |  | 
|  20 $ sed '/obj\/third_party\/WebKit\/Source/!d; s/^\[[0-9\/]*\] //; /^g++/!d; s/^g+
    +/include-what-you-use -Wno-c++11-extensions/; s/-fno-ident//' ninjalog.txt > co
    mmands.txt |  | 
|  21 ``` |  | 
|  22   * Run the IWYU commands. We do this in parallel for speed. Merge the output an
    d remove any complaints that the compiler has. |  | 
|  23 ``` |  | 
|  24 $ cd out/Debug |  | 
|  25 $ for i in {1..32}; do (sed -ne "$i~32p" ../../commands.txt | xargs -n 1 -L 1 -d
     '\n' bash -c > iwyu_$i.txt 2>&1) & done |  | 
|  26 $ cat iwyu_{1..32}.txt | sed '/In file included from/d;/\(note\|warning\|error\)
    :/{:a;N;/should add/!b a;s/.*\n//}' > iwyu.txt |  | 
|  27 $ rm iwyu_{1..32}.txt |  | 
|  28 ``` |  | 
|  29   * The output in iwyu.txt has all the suggested changes |  | 
|  30  |  | 
|  31 # Mac |  | 
|  32  |  | 
|  33 ## Setup |  | 
|  34  |  | 
|  35   1. Checkout and build IWYU (This will also check out and build clang. See [Cla
    ng page](http://code.google.com/p/chromium/wiki/Clang) for details.) |  | 
|  36 ``` |  | 
|  37 $ cd /path/to/src/ |  | 
|  38 $ tools/clang/scripts/update_iwyu.sh |  | 
|  39 ``` |  | 
|  40   1. Ensure "Continue building after errors" is enabled in the Xcode Preferences
     UI. |  | 
|  41  |  | 
|  42 ## Chromium |  | 
|  43  |  | 
|  44   1. Build Chromium. Be sure to substitute in the correct absolute path for `/pa
    th/to/src/`. |  | 
|  45 ``` |  | 
|  46 $ GYP_DEFINES='clang=1' gclient runhooks |  | 
|  47 $ cd chrome |  | 
|  48 $ xcodebuild -configuration Release -target chrome OBJROOT=/path/to/src/clang/ob
    j DSTROOT=/path/to/src/clang SYMROOT=/path/to/src/clang CC=/path/to/src/third_pa
    rty/llvm-build/Release+Asserts/bin/clang++ |  | 
|  49 ``` |  | 
|  50   1. Run IWYU. Be sure to substitute in the correct absolute path for `/path/to/
    src/`. |  | 
|  51 ``` |  | 
|  52 $ xcodebuild -configuration Release -target chrome OBJROOT=/path/to/src/clang/ob
    j DSTROOT=/path/to/src/clang SYMROOT=/path/to/src/clang CC=/path/to/src/third_pa
    rty/llvm-build/Release+Asserts/bin/include-what-you-use |  | 
|  53 ``` |  | 
|  54  |  | 
|  55 ## WebKit |  | 
|  56  |  | 
|  57   1. Build TestShell. Be sure to substitute in the correct absolute path for `/p
    ath/to/src/`. |  | 
|  58 ``` |  | 
|  59 $ GYP_DEFINES='clang=1' gclient runhooks |  | 
|  60 $ cd webkit |  | 
|  61 $ xcodebuild -configuration Release -target test_shell OBJROOT=/path/to/src/clan
    g/obj DSTROOT=/path/to/src/clang SYMROOT=/path/to/src/clang CC=/path/to/src/thir
    d_party/llvm-build/Release+Asserts/bin/clang++ |  | 
|  62 ``` |  | 
|  63   1. Run IWYU. Be sure to substitute in the correct absolute path for `/path/to/
    src/`. |  | 
|  64 ``` |  | 
|  65 $ xcodebuild -configuration Release -target test_shell OBJROOT=/path/to/src/clan
    g/obj DSTROOT=/path/to/src/clang SYMROOT=/path/to/src/clang CC=/work/chromium/sr
    c/third_party/llvm-build/Release+Asserts/bin/include-what-you-use |  | 
|  66 ``` |  | 
|  67  |  | 
|  68 # Bragging |  | 
|  69  |  | 
|  70 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 fr
    om 2MB to 80kB" in your CL descriptions. |  | 
|  71  |  | 
|  72 # Known Issues |  | 
|  73  |  | 
|  74 We are a long way off from being able to accept the results of IWYU for Chromium
    /Blink. However, even in its current state it can be a useful tool for finding f
    orward declaration opportunities and unused includes. |  | 
|  75  |  | 
|  76 Using IWYU with Blink has several issues: |  | 
|  77   * Lack of understanding on Blink style, e.g. config.h, wtf/MathExtras.h, wtf/F
    orward.h, wtf/Threading.h |  | 
|  78   * "using" declarations (most of WTF) makes IWYU not suggest forward declaratio
    ns |  | 
|  79   * Functions defined inline in a different location to the declaration are drop
    ped, e.g. Document::renderView in RenderView.h and Node::renderStyle in NodeRend
    erStyle.h |  | 
|  80   * typedefs can cause unwanted dependencies, e.g. typedef int ExceptionCode in 
    Document.h |  | 
|  81   * .cpp files don't always correspond directly to .h files, e.g. Foo.h can be i
    mplemented in e.g. chromium/FooChromium.cpp |  | 
|  82   * g++/clang/iwyu seems fine with using forward declarations for PassRefPtr typ
    es in some circumstances, which MSVC doesn't. |  | 
| OLD | NEW |