Add clang-tidy documentation

docs/clang_tidy.md

+# Clang Tidy

[Devlin, 2016/07/11 23:38:28]

Not all markdown viewers are created equal - do you know if there's a way to
test this in a gitiles-like viewer?  Alternatively, we can commit it, view it
there for realz, and update as needed.

+
+[TOC]
+
+## Introduction
+
+[clang-tidy](http://clang.llvm.org/extra/clang-tidy/) is a clang-based C++
+“linter” tool. Its purpose is to provide an extensible framework for diagnosing
+and fixing typical programming errors, like style violations, interface misuse,
+or bugs that can be deduced via static analysis. **clang-tidy** is modular and
+provides a convenient interface for writing new checks.
+
+## Setting Up
+
+In addition to a full Chromium checkout, you need the clang-tidy binary. We
+recommend checking llvm's clang source and building the clang-tidy binary
+directly. Instructions for getting started with clang are available from
+[llvm](http://clang.llvm.org/get_started.html). You'll need to get llvm,
+clang, and the extra clang tools (you won't need Compiler-RT or libcxx).
+If you don't have it, you'll also need to install cmake as a part of this
+process.
+
+Instead of building with `"Unix Makefiles"`, generate build files for Ninja with
+```
+cmake -GNinja ../llvm
+```
+
+Then, instead of using `make`, use ninja to build the clang-tidy binary with
+```
+ninja clang-tidy
+```
+
+This binary will be at (build)/bin/clang-tidy.
+
+If you intend to use the `fix` feature of clang-tidy, you'll also need to build
+the `clang-apply-replacements` binary.
+```
+ninja clang-apply-replacements
+```
+
+## Running clang-tidy
+
+Running clang-tidy is (hopefully) simple.
+1.  Build chrome normally.\*
+```
+ninja -C out/release chrome
+```
+2.  Generate the compilation database
+```
+ninja -C out/release -t compdb objxx cxx > compile_commands.json
+```
+3.  Enter the build directory.
+```
+cd out/release
+```
+4.  Run clang-tidy.
+```
+<PATH_TO_LLVM_SRC>/tools/clang/tools/extra/clang-tidy/tools/run-clang-tidy.py \
+    -p ../.. \# Set the root project directory, where compile_commands.json is.
+    # Set the clang-tidy binary path, if it's not in your $PATH.
+    -clang-tidy-binary <PATH_TO_LLVM_BUILD>/bin/clang-tidy \
+    # Set the clang-apply-replacements binary path, if it's not in your $PATH
+    # and you are using the `fix` behavior of clang-tidy.
+    -clang-apply-replacements-binary \
+        <PATH_TO_LLVM_BUILD>/bin/clang-apply-replacements \
+    # The checks to employ in the build. Use `-*` to omit default checks.
+    -checks=<CHECKS> \
+    -header-filter=<FILTER> \# Optional, limit results to only certain files.
+    -fix \# Optional, used if you want to have clang-tidy auto-fix errors.
+    chrome/browser # The path to the files you want to check.
+```
+
+\*It's not clear which, if any, `gn` flags may cause issues for `clang-tidy`.
+I've had no problems building a component release build, both with and without
+goma. if you run into issues, let us know!
+
+## Troubleshooting
+
+If you see errors like
+```
+src/build/linux/debian_wheezy_amd64-sysroot/usr/include/wchar.h:40:11: error: 'stdarg.h' file not found [clang-diagnostic-error]
+```
+
+then you should also build the `clang-headers` target in your llvm checkout.
+(This should be fixed by http://reviews.llvm.org/D22046).
+
+## Questions
+
+Questions? Reach out to rdevlin.cronin@chromium.org or thakis@chromium.org.

[Devlin, 2016/07/11 23:38:28]

I'm volunteering you here. Let me know if you want out now. :)

+Discoveries? Update the doc!