[analyzer] Fixes to the checker developer manual.

[NoQ]

Summary

1. Fix the explanation of how to run tests after migration from autotools to cmake.

2. Expand the "debugging" section with more interesting stuff, as accidentally discussed in D22622 and D22856.

Any other things to fix there?

Also, does anybody think it's a good idea to mention my unofficial guide (https://github.com/haoNoQ/clang-analyzer-guide/releases) in the "additional sources" section?

[zaks.anna]

A couple of nits. Otherwise, LGTM. Thanks!

www/analyzer/checker_dev_manual.html

534

I suggest to just tell about -### and drop the explanation about attaching to the child process. Sounds good?

645

I'd move this up after the description of "-analyze-function=foo".

www/analyzer/checker_dev_manual.html

<h2 id=ast>AST Visitors</h2>
   situation, AST callbacks <tt><b>checkASTDecl</b></tt> and 
   <tt><b>checkASTCodeBody</b></tt> are your best friends. 
 
 <h2 id=testing>Testing</h2>
   Every patch should be well tested with Clang regression tests. The checker tests 
   live in <tt>clang/test/Analysis</tt> folder. To run all of the analyzer tests, 
   execute the following from the <tt>clang</tt> build directory:
     <pre class="code">
-    $ <b>TESTDIRS=Analysis make test</b>
+    $ <b>bin/llvm-lit -sv ../llvm/tools/clang/test/Analysis</b>
     </pre>
 
 <h2 id=commands>Useful Commands/Debugging Hints</h2>
-<ul>
-<li>
-While investigating a checker-related issue, instruct the analyzer to only 
+
+<h3>Attaching the debugger</h3>
+
+<p>When your command contains the <tt><b>-cc1</b></tt> flag, you can attach the
+debugger to it directly:</p>
+
+<pre class="code">
+    $ <b>gdb --args clang -cc1 -analyze -analyzer-checker=core test.c</b>
+    $ <b>lldb -- clang -cc1 -analyze -analyzer-checker=core test.c</b>
+</pre>
+
+<p>
+Otherwise, if your command line contains <tt><b>--analyze</b></tt>,
+the actual clang instance would be run in a separate process. In
+order to debug it, you'd have to either instruct your debugger to attach
+itself to the child process (for example, in <tt><b>gcc</b></tt> you can
+<tt><b>set follow-fork-mode=child</b></tt>), or use the <tt><b>-###</b></tt>
+flag for obtaining the command line of the child process:
+</p>
+
+<pre class="code">
+    $ <b>clang --analyze test.c -\#\#\#</b>
+</pre>
+
+<p>
+Below we describe a few useful command line arguments, all of which assume that
+you are running <tt><b>clang -cc1</b></tt>.
+</p>
+
+<h3>Narrowing down the problem</h3>
+
+<p>While investigating a checker-related issue, instruct the analyzer to only
 execute a single checker:
-<br><tt>
+</p>
+<pre class="code">
     $ <b>clang -cc1 -analyze -analyzer-checker=osx.KeychainAPI test.c</b>
-</tt>
-</li>
-<li>
-To dump AST:
-<br><tt>
+</pre>
+
+<p>If you are experiencing a crash, to see which function is failing while
+processing a large file use the  <tt><b>-analyzer-display-progress</b></tt>
+option.</p>
+
+<p>You can analyze a particular function within the file, which is often useful
+because the problem is always in a certain function:</p>
+<pre class="code">
+    $ <b>clang -cc1 -analyze -analyzer-checker=core test.c -analyzer-display-progress</b>
+    ANALYZE (Syntax): test.c foo
+    ANALYZE (Syntax): test.c bar
+    ANALYZE (Path,  Inline_Regular): test.c bar
+    ANALYZE (Path,  Inline_Regular): test.c foo
+    $ <b>clang -cc1 -analyze -analyzer-checker=core test.c -analyzer-display-progress -analyze-function=foo</b>
+    ANALYZE (Syntax): test.c foo
+    ANALYZE (Path,  Inline_Regular): test.c foo
+</pre>
+
+<h3>Visualizing the analysis</h3>
+
+<p>To dump the AST, which often helps understanding how the program should
+behave:</p>
+<pre class="code">
     $ <b>clang -cc1 -ast-dump test.c</b>
-</tt>
-</li>
-<li>
-To view/dump CFG use <tt>debug.ViewCFG</tt> or <tt>debug.DumpCFG</tt> checkers:
-<br><tt>
+</pre>
+
+<p>To view/dump CFG use <tt>debug.ViewCFG</tt> or <tt>debug.DumpCFG</tt>
+checkers:</p>
+<pre class="code">
     $ <b>clang -cc1 -analyze -analyzer-checker=debug.ViewCFG test.c</b>
-</tt> 
-</li>
-<li>
-To see all available debug checkers:
-<br><tt>
+</pre>
+
+<p><tt>ExplodedGraph</tt> (the state graph explored by the analyzer) can be
+visualized with another debug checker:</p>
+<pre class="code">
+    $ <b>clang -cc1 -analyze -analyzer-checker=debug.ViewExplodedGraph test.c</b>
+</pre>
+<p>Or, equivalently, with <tt><b>-analyzer-viz-egraph-graphviz</b></tt>
+option, which does the same thing - dumps the exploded graph in graphviz
+<tt><b>.dot</b></tt> format.</p>
+
+<p>You can convert <tt><b>.dot</b></tt> files into other formats - in
+particular, converting to <tt><b>.svg</b></tt> and viewing in your web
+browser might be more comfortable than using a <tt><b>.dot</b></tt> viewer:</p>
+<pre class="code">
+    $ <b>dot -Tsvg ExprEngine-501e2e.dot -o ExprEngine-501e2e.svg</b>
+</pre>
+
+<p>The <tt><b>-trim-egraph</b></tt> option removes all paths except those
+leading to bug reports from the exploded graph dump. This is useful
+because exploded graphs are often huge and hard to navigate.</p>
+
+<p>Viewing <tt>ExplodedGraph</tt> is your most powerful tool for understanding
+the analyzer's false positives, because it gives comprehensive information
+on every decision made by the analyzer across all analysis paths.</p>
+
+<p>There are more debug checkers available. To see all available debug checkers:
+</p>
+<pre class="code">
     $ <b>clang -cc1 -analyzer-checker-help | grep "debug"</b>
-</tt>
-</li>
-<li>
-To see which function is failing while processing a large file use 
-<tt>-analyzer-display-progress</tt> option.
-</li>
-<li>
-While debugging execute <tt>clang -cc1 -analyze -analyzer-checker=core</tt> 
-instead of <tt>clang --analyze</tt>, as the later would call the compiler 
-in a separate process.
-</li>
-<li>
-To view <tt>ExplodedGraph</tt> (the state graph explored by the analyzer) while 
-debugging, goto a frame that has <tt>clang::ento::ExprEngine</tt> object and 
-execute:
-<br><tt> 
+</pre>
+
+<h3>Debug prints and tricks</h3>
+
+<p>To view "half-baked" <tt>ExplodedGraph</tt> while debugging, jump to a frame
+that has <tt>clang::ento::ExprEngine</tt> object and execute:</p>
+<pre class="code">
     (gdb) <b>p ViewGraph(0)</b>
-</tt>
-</li>
-<li>
-To see the <tt>ProgramState</tt> while debugging use the following command. 
-<br><tt>
+</pre>
+
+<p>To see the <tt>ProgramState</tt> while debugging use the following command.
+<pre class="code">
     (gdb) <b>p State->dump()</b>
-</tt> 
-</li>
-<li>
-To see <tt>clang::Expr</tt> while debugging use the following command. If you 
-pass in a SourceManager object, it will also dump the corresponding line in the 
-source code.
-<br><tt>
+</pre>
+
+<p>To see <tt>clang::Expr</tt> while debugging use the following command. If you
+pass in a <tt>SourceManager</tt> object, it will also dump the corresponding line in the
+source code.</p>
+<pre class="code">
     (gdb) <b>p E->dump()</b>
-</tt> 
-</li>
-<li>
-To dump AST of a method that the current <tt>ExplodedNode</tt> belongs to:
-<br><tt>
+</pre>
+
+<p>To dump AST of a method that the current <tt>ExplodedNode</tt> belongs
+to:</p>
+<pre class="code">
     (gdb) <b>p C.getPredecessor()->getCodeDecl().getBody()->dump()</b>
-(gdb) <b>p C.getPredecessor()->getCodeDecl().getBody()->dump(getContext().getSourceManager())</b>
-</tt>
-</li>
-</ul>
+</pre>
+
+<h3>More verbose path diagnostics</h3>
+
+<p>The bug reporter mechanism removes path diagnostics inside intermediate
+function calls that have returned by the time the bug was found and contain
+no interesting pieces. Usually it is up to the checkers to produce more
+interesting pieces by adding custom <tt>BugReporterVisitor</tt> objects.
+However, you can disable path pruning while debugging with the
+<tt><b>-analyzer-config prune-paths=false</b></tt> option.
 
 <h2 id=additioninformation>Additional Sources of Information</h2>
 
 Here are some additional resources that are useful when working on the Clang
 Static Analyzer:
 
 <ul>
 <li> <a href="http://clang.llvm.org/doxygen">Clang doxygen</a>. Contains