docs/include_what_you_use.md

   1 # Introduction
   2
   3 **WARNING:** This is all very alpha. Proceed at your own risk. The Mac instructions 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 something like `CXX=include-what-you-use GYP_DEFINES="clang=1" gclient runhooks; ninja -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-what-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 > commands.txt
  21 ```
  22   * Run the IWYU commands. We do this in parallel for speed. Merge the output and 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 [Clang 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 `/path/to/src/`.
  45 ```
  46 $ GYP_DEFINES='clang=1' gclient runhooks
  47 $ cd chrome
  48 $ 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++
  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/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
  53 ```
  54
  55 ## WebKit
  56
  57   1. Build TestShell. Be sure to substitute in the correct absolute path for `/path/to/src/`.
  58 ```
  59 $ GYP_DEFINES='clang=1' gclient runhooks
  60 $ cd webkit
  61 $ 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++
  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/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
  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 from 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 forward 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/Forward.h, wtf/Threading.h
  78   * "using" declarations (most of WTF) makes IWYU not suggest forward declarations
  79   * Functions defined inline in a different location to the declaration are dropped, e.g. Document::renderView in RenderView.h and Node::renderStyle in NodeRenderStyle.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 implemented in e.g. chromium/FooChromium.cpp
  82   * g++/clang/iwyu seems fine with using forward declarations for PassRefPtr types in some circumstances, which MSVC doesn't.