Add clang-tidy documentation

docs/clang_tidy.md

Index: docs/clang_tidy.md
diff --git a/docs/clang_tidy.md b/docs/clang_tidy.md
new file mode 100644
index 0000000000000000000000000000000000000000..979ce502d237e6d82688624f2be0ad015a46ed4a
--- /dev/null
+++ b/docs/clang_tidy.md
@@ -0,0 +1,97 @@
+# Clang Tidy
+
+[TOC]
+
+## Danger, Will Robinson!
+
+Support for `clang-tidy` in Chromium is very experimental, and is somewhat
+painful to use. We are exploring making it easier and integrating with existing
+tools, but aren't there yet. If you don't want to wait and enjoy tinkering,
+forge ahead. Otherwise, feel free to turn back now.
+
+## 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.

[Nico, 2016/07/12 18:44:09]

i'd omit the last sentence

[Devlin, 2016/07/12 19:05:02]

Done.

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

[Nico, 2016/07/12 18:44:09]

upper-case R, then it works with gyp too

[Devlin, 2016/07/12 19:05:02]

It was my subtle hint to get people off gyp ;)  But fair enough.  Done.

+```
+2.  Generate the compilation database
+```
+ninja -C out/release -t compdb objxx cxx > compile_commands.json

[Nico, 2016/07/12 18:44:09]

ditto. (also, isn't it "objcxx" for mm files? not sure)

[Devlin, 2016/07/12 19:05:02]

Done, and yes!  Typo.  Thanks for catching it.

+```
+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.

[Nico, 2016/07/12 18:44:09]

hm, do inline comments work with continuations? is this copy-pastable-?

[Devlin, 2016/07/12 19:05:02]

Nope, but I figured it was the easiest way of documenting what each part did.

I've added a second "copy-paste friendly" version below it.  (If you'd prefer,
we could also have the command and then describe everything below, but I
slightly prefer the inline approach.)

+    -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).

[Nico, 2016/07/12 18:44:09]

"(This is fixed in llvm r274751, so if your llvm checkout is up-to-date this
shouldn't be needed.)" instead

Maybe just remove this section altogether though.

[Devlin, 2016/07/12 19:05:02]

Updated the phrasing.  I'd like to keep it in for helping anyone who has a
slightly outdated checkout.  We can remove it in awhile when it's more likely
everyone will have it.

+
+## Questions
+
+Questions? Reach out to rdevlin.cronin@chromium.org or thakis@chromium.org.
+Discoveries? Update the doc!