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