| 1 | [[PageOutline]] |
| 2 | |
| 3 | = Building WebKit with Clang Address Sanitizer (ASan) = |
| 4 | |
| 5 | This page describes how to build WebKit with the clang Address Sanitizer (ASan) for various ports. |
| 6 | |
| 7 | == Building the Apple Mac OS X port with ASan == |
| 8 | |
| 9 | Building the Apple Mac OS X port with the clang Address Sanitizer currently requires a custom build of trunk clang, plus an Xcode toolchain derived from OSX10.9.xctoolchain. |
| 10 | |
| 11 | NOTE: These instructions are currently an '''untested''' work-in-progress, but we hope to automate it with tools soon. |
| 12 | |
| 13 | 1. Install Mac OS X 10.9.1 (Mavericks) on a Mac. Don't use 10.9 as it contains a bug that causes a crash on every HTTP redirect. |
| 14 | 2. Install Xcode developer tools, including the Mac OS X 10.9 SDK. These instructions assume the 10.9 SDK is located here: |
| 15 | {{{ |
| 16 | /Applications/Xcode.app/Contents/Developer/Toolchains/OSX10.9.xctoolchain/ |
| 17 | }}} |
| 18 | 3. Make a copy of the `OSX10.9.xctoolchain` and call it `ASAN.xctoolchain`: |
| 19 | {{{ |
| 20 | sudo ditto /Applications/Xcode.app/Contents/Developer/Toolchains/OSX10.9.xctoolchain /Applications/Xcode.app/Contents/Developer/Toolchains/ASAN.xctoolchain |
| 21 | }}} |
| 22 | 4. Edit `ASAN.xctoolchain/ToolchainInfo.plist` to change the `Identifier` string from `com.apple.dt.toolchain.OSX10_9` to `com.apple.dt.toolchain.ASAN`. |
| 23 | {{{ |
| 24 | sudo vi /Applications/Xcode.app/Contents/Developer/Toolchains/ASAN.xctoolchain/ToolchainInfo.plist |
| 25 | }}} |
| 26 | 5. Build trunk clang/llvm. The address sanitizer should be built by default for Mac OS X. See http://www.llvm.org/docs/ for details. Subversion revision r204316 of clang/llvm is known to build WebKit for Mac OS X. Newer versions may introduce new warnings or compiler bugs that must be fixed before proceeding. |
| 27 | 6. Ditto the clang/llvm build output into `/Applications/Xcode.app/Contents/Developer/Toolchains/ASAN.xctoolchain` to replace the version of clang/llvm in the original toolchain. |
| 28 | {{{ |
| 29 | TBD |
| 30 | }}} |
| 31 | 7. Fix the ID of `libclang_rt.asan_osx_dynamic.dylib` to its installation path using the `install_name_tool`: |
| 32 | {{{ |
| 33 | sudo xcrun install_name_tool -id /Applications/Xcode.app/Contents/Developer/Toolchains/ASAN.xctoolchain/usr/lib/clang/3.5.0/lib/darwin/libclang_rt.asan_osx_dynamic.dylib /Applications/Xcode.app/Contents/Developer/Toolchains/ASAN.xctoolchain/usr/lib/clang/3.5.0/lib/darwin/libclang_rt.asan_osx_dynamic.dylib |
| 34 | }}} |
| 35 | 8. Copy `libclang_rt.asan_osx_dynamic.dylib` into your `WebKitBuild/Release` directory: |
| 36 | {{{ |
| 37 | ditto /Applications/Xcode.app/Contents/Developer/Toolchains/ASAN.xctoolchain/usr/lib/clang/3.5.0/lib/darwin/libclang_rt.asan_osx_dynamic.dylib WebKitBuild/Release/ |
| 38 | }}} |
| 39 | 9. Build WebKit with additional xcodebuild arguments to load `asan.xcconfig`, find the ASan ignore list, and build with the new compiler: |
| 40 | {{{ |
| 41 | make release ARGS="-xcconfig $PWD/Tools/asan/asan.xcconfig ASAN_IGNORE=$PWD/Tools/asan/webkit-asan-ignore.txt TOOLCHAINS=com.apple.dt.toolchain.ASAN" |
| 42 | }}} |
| 43 | 10. When running apps that load WebKit built with ASan, the `ASAN_OPTIONS` environment variable needs to be set to make sure the app crashes when you hit an issue, and to prevent false-positives for some intrinsics Mac OS X (e.g., memcpy and memmove are the same function). For example, to launch Safari: |
| 44 | {{{ |
| 45 | ASAN_OPTIONS="replace_intrin=0:abort_on_error=1:handle_segv=0" ./Tools/Scripts/run-safari --release --no-saved-state |
| 46 | }}} |
| 47 | You should also be able to run DumpRenderTree and WebKitTestRunner in a similar fashion: |
| 48 | {{{ |
| 49 | ASAN_OPTIONS="replace_intrin=0:abort_on_error=1:handle_segv=0" ./Tools/Scripts/run-webkit-tests --release --no-build |
| 50 | }}} |