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

(On Diff #65762)

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

645 ↗

(On Diff #65762)

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

cfe/trunk/www/analyzer/checker_dev_manual.html

<ul>
       </ul></li>
       <li><a href="#idea">Idea for a Checker</a></li>
       <li><a href="#registration">Checker Registration</a></li>
       <li><a href="#events_callbacks">Events, Callbacks, and Checker Class Structure</a></li>
       <li><a href="#extendingstates">Custom Program States</a></li>
       <li><a href="#bugs">Bug Reports</a></li>
       <li><a href="#ast">AST Visitors</a></li>
       <li><a href="#testing">Testing</a></li>
-      <li><a href="#commands">Useful Commands/Debugging Hints</a></li>
+      <li><a href="#commands">Useful Commands/Debugging Hints</a>
+      <ul>
+        <li><a href="#attaching">Attaching the Debugger</a></li>
+        <li><a href="#narrowing">Narrowing Down the Problem</a></li>
+        <li><a href="#visualizing">Visualizing the Analysis</a></li>
+        <li><a href="#debugprints">Debug Prints and Tricks</a></li>
+      </ul></li>
       <li><a href="#additioninformation">Additional Sources of Information</a></li>
       <li><a href="#links">Useful Links</a></li>
     </ul>
 
 <h2 id=start>Getting Started</h2>
   <ul>
     <li>To check out the source code and build the project, follow steps 1-4 of 
     the <a href="http://clang.llvm.org/get_started.html">Clang Getting Started</a> 
<h2 id=analyzer>Static Analyzer Overview</h2>
   <ul>
     <li><tt>Environment</tt> - a mapping from source code expressions to symbolic 
     values
     <li><tt>Store</tt> - a mapping from memory locations to symbolic values
     <li><tt>GenericDataMap</tt> - constraints on symbolic values
   </ul>
   
   <h3 id=interaction>Interaction with Checkers</h3>
+
+  <p>
   Checkers are not merely passive receivers of the analyzer core changes - they 
   actively participate in the <tt>ProgramState</tt> construction through the
   <tt>GenericDataMap</tt> which can be used to store the checker-defined part 
   of the state. Each time the analyzer engine explores a new statement, it 
   notifies each checker registered to listen for that statement, giving it an 
   opportunity to either report a bug or modify the state. (As a rule of thumb, 
   the checker itself should be stateless.) The checkers are called one after another 
   in the predefined order; thus, calling all the checkers adds a chain to the 
-  <tt>ExplodedGraph</tt>. 
+  <tt>ExplodedGraph</tt>.
+  </p>
   
   <h3 id=values>Representing Values</h3>
+
+  <p>
   During symbolic execution, <a href="http://clang.llvm.org/doxygen/classclang_1_1ento_1_1SVal.html">SVal</a> 
   objects are used to represent the semantic evaluation of expressions. 
   They can represent things like concrete 
   integers, symbolic values, or memory locations (which are memory regions). 
   They are a discriminated union of "values", symbolic and otherwise. 
   If a value isn't symbolic, usually that means there is no symbolic 
   information to track. For example, if the value was an integer, such as 
   <tt>42</tt>, it would be a <a href="http://clang.llvm.org/doxygen/classclang_1_1ento_1_1nonloc_1_1ConcreteInt.html">ConcreteInt</a>, 
   and the checker doesn't usually need to track any state with the concrete 
   number. In some cases, <tt>SVal</tt> is not a symbol, but it really should be 
   a symbolic value. This happens when the analyzer cannot reason about something 
   (yet). An example is floating point numbers. In such cases, the 
   <tt>SVal</tt> will evaluate to <a href="http://clang.llvm.org/doxygen/classclang_1_1ento_1_1UnknownVal.html">UnknownVal</a>.
   This represents a case that is outside the realm of the analyzer's reasoning 
   capabilities. <tt>SVals</tt> are value objects and their values can be viewed 
   using the <tt>.dump()</tt> method. Often they wrap persistent objects such as 
-  symbols or regions. 
+  symbols or regions.
+  </p>
+
   <p>
   <a href="http://clang.llvm.org/doxygen/classclang_1_1ento_1_1SymExpr.html">SymExpr</a> (symbol) 
   is meant to represent abstract, but named, symbolic value. Symbols represent 
   an actual (immutable) value. We might not know what its specific value is, but 
   we can associate constraints with that value as we analyze a path. For 
   example, we might record that the value of a symbol is greater than 
   <tt>0</tt>, etc.
-  <p>
+  </p>
 
   <p>
   <a href="http://clang.llvm.org/doxygen/classclang_1_1ento_1_1MemRegion.html">MemRegion</a> is similar to a symbol.  
   It is used to provide a lexicon of how to describe abstract memory. Regions can 
   layer on top of other regions, providing a layered approach to representing memory. 
   For example, a struct object on the stack might be represented by a <tt>VarRegion</tt>, 
   but a <tt>FieldRegion</tt> which is a subregion of the <tt>VarRegion</tt> could 
   be used to represent the memory associated with a specific field of that object.
   So how do we represent symbolic memory regions? That's what 
   <a href="http://clang.llvm.org/doxygen/classclang_1_1ento_1_1SymbolicRegion.html">SymbolicRegion</a> 
   is for. It is a <tt>MemRegion</tt> that has an associated symbol. Since the 
   symbol is unique and has a unique name; that symbol names the region.
+  </p>
   
-  <P>
+  <p>
   Let's see how the analyzer processes the expressions in the following example:
+  </p>
+
   <p>
   <pre class="code_example">
   int foo(int x) {
      int y = x * 2;
      int z = x;
      ...
   }
   </pre>
+  </p>
+
   <p>
 Let's look at how <tt>x*2</tt> gets evaluated. When <tt>x</tt> is evaluated, 
 we first construct an <tt>SVal</tt> that represents the lvalue of <tt>x</tt>, in 
 this case it is an <tt>SVal</tt> that references the <tt>MemRegion</tt> for <tt>x</tt>. 
 Afterwards, when we do the lvalue-to-rvalue conversion, we get a new <tt>SVal</tt>, 
 which references the value <b>currently bound</b> to <tt>x</tt>. That value is 
 symbolic; it's whatever <tt>x</tt> was bound to at the start of the function. 
 Let's call that symbol <tt>$0</tt>. Similarly, we evaluate the expression for <tt>2</tt>, 
 and get an <tt>SVal</tt> that references the concrete number <tt>2</tt>. When 
 we evaluate <tt>x*2</tt>, we take the two <tt>SVals</tt> of the subexpressions, 
 and create a new <tt>SVal</tt> that represents their multiplication (which in 
 this case is a new symbolic expression, which we might call <tt>$1</tt>). When we 
 evaluate the assignment to <tt>y</tt>, we again compute its lvalue (a <tt>MemRegion</tt>), 
 and then bind the <tt>SVal</tt> for the RHS (which references the symbolic value <tt>$1</tt>) 
 to the <tt>MemRegion</tt> in the symbolic store.
 <br>
 The second line is similar. When we evaluate <tt>x</tt> again, we do the same 
 dance, and create an <tt>SVal</tt> that references the symbol <tt>$0</tt>. Note, two <tt>SVals</tt> 
 might reference the same underlying values.
+  </p>
 
 <p>
 To summarize, MemRegions are unique names for blocks of memory. Symbols are 
 unique names for abstract symbolic values. Some MemRegions represents abstract 
 symbolic chunks of memory, and thus are also based on symbols. SVals are just 
 references to values, and can reference either MemRegions, Symbols, or concrete 
 values (e.g., the number 1).
+</p>
 
   <!-- 
   TODO: Add a picture.
   <br>
   Symbols<br>
   FunctionalObjects are used throughout.  
   -->
 
<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 id=attaching>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, 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 id=narrowing>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>
+
+<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.
+
+<h3 id=visualizing>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 id=debugprints>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>
 
 <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