[cfe-commits] r143554 - /cfe/trunk/www/analyzer/checker_dev_manual.html
Anna Zaks
ganna at apple.com
Wed Nov 2 10:49:21 PDT 2011
Author: zaks
Date: Wed Nov 2 12:49:20 2011
New Revision: 143554
URL: http://llvm.org/viewvc/llvm-project?rev=143554&view=rev
Log:
[analyzer] Start writing Checker Developer Manual.
So far added the skeleton + several more or less complete sections:
Getting Started
Idea for a Checker
AST Visitors
Useful Commands/Debugging Hints
Added:
cfe/trunk/www/analyzer/checker_dev_manual.html
Added: cfe/trunk/www/analyzer/checker_dev_manual.html
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/www/analyzer/checker_dev_manual.html?rev=143554&view=auto
==============================================================================
--- cfe/trunk/www/analyzer/checker_dev_manual.html (added)
+++ cfe/trunk/www/analyzer/checker_dev_manual.html Wed Nov 2 12:49:20 2011
@@ -0,0 +1,181 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+ <title>Checker Developer Manual</title>
+ <link type="text/css" rel="stylesheet" href="menu.css" />
+ <link type="text/css" rel="stylesheet" href="content.css" />
+ <script type="text/javascript" src="scripts/menu.js"></script>
+</head>
+<body>
+
+<div id="page">
+<!--#include virtual="menu.html.incl"-->
+
+<div id="content">
+
+<h1><font color=red>This Page Is Under Construction</font></h1>
+
+<h1>Checker Developer Manual</h1>
+
+<p>The static analyzer engine performs symbolic execution of the program and
+relies on a set of checkers to implement the logic for detecting and
+constructing bug reports. This page provides hints and guidelines for anyone
+who is interested in implementing their own checker. The static analyzer is a
+part of the Clang project, so consult <a href="http://clang.llvm.org/hacking.html">Hacking on Clang</a>
+and <a href="http://llvm.org/docs/ProgrammersManual.html">LLVM Programmer's Manual</a>
+for general developer guidelines and information. </p>
+
+ <ul>
+ <li><a href="#start">Getting Started</a></li>
+ <li><a href="#analyzer">Static Analyzer Overview</a></li>
+ <li><a href="#idea">Idea for a Checker</a></li>
+ <li><a href="#skeleton">Checker Skeleton</a></li>
+ <li><a href="#node">Exploded Node</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</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>
+ page.</li>
+
+ <li>The analyzer source code is located under the Clang source tree:
+ <br><tt>
+ $ <b>cd llvm/tools/clang</b>
+ </tt>
+ <br>See: <tt>include/clang/StaticAnalyzer</tt>, <tt>lib/StaticAnalyzer</tt>, <tt>test/Analysis</tt>.</li>
+
+ <li>The analyzer regression tests can be executed from the Clang's build directory:
+ <br><tt>
+ $ <b>cd ../../../; cd build/tools/clang; TESTDIRS=Analysis make test</b>
+ </tt></li>
+
+ <li>Analyze a file with the specified checker:
+ <br><tt>
+ $ <b>clang -cc1 -analyze -analyzer-checker=core.DivideZero test.c</b>
+ </tt></li>
+
+ <li>List the available checkers:
+ <br><tt>
+ $ <b>clang -cc1 -analyzer-checker-help</b>
+ </tt></li>
+
+ <li>See the analyzer help for different output formats, fine tuning, and debug options:
+ <br><tt>
+ $ <b>clang -cc1 -help | grep "analyzer"</b>
+ </tt></li>
+
+ </ul>
+
+<h2 id=analyzer>Static Analyzer Overview</h2>
+ ExplidedGraph, ExplodedNode (ProgramPoint, State)<br>
+ Engine-Checker Interaction<br>
+ Symbols<br>
+
+
+<h2 id=idea>Idea for a Checker</h2>
+ Here are several questions which you should consider when evaluating your checker idea:
+ <ul>
+ <li>Can the check be effectively implemented without path-sensitive analysis? See <a href="#ast">AST Visitors</a>.</li>
+
+ <li>How high the false positive rate is going to be? Looking at the occurrences
+ of the issue you want to write a checker for in the existing code bases might give you some
+ ideas. </li>
+
+ <li>How the current limitations of the analysis will effect the false alarm
+ rate? Currently, the analyzer only reasons about one procedure at a time (no
+ inter-procedural analysis). Also, it uses a simple range tracking based solver to model symbolic
+ execution.</li>
+
+ <li>Consult the <a href="http://llvm.org/bugs/buglist.cgi?query_format=advanced&bug_status=NEW&bug_status=REOPENED&version=trunk&component=Static%20Analyzer&product=clang">Bugzilla database</a>
+ to get some ideas for new checkers and consider starting with improving/fixing
+ bugs in the existing checkers.</li>
+ </ul>
+
+<h2 id=skeleton>Checker Skeleton</h2>
+ The source code for all the checkers goes into <tt>clang/lib/StaticAnalyzer/Checkers</tt>.<p>
+ There are two main decisions you need to make:
+ <ul>
+ <li> Which events the checker should be tracking.</li>
+ <li> What data you want to store as part of the checker-specific program state. Try to minimize the checker state as much as possible. </li>
+ </ul>
+ Describe the registration process.
+
+<h2 id=bugs>Bug Reports</h2>
+
+<h2 id=ast>AST Visitors</h2>
+ Some checks might not require path-sensitivity to be effective. Simple AST walk
+ might be sufficient. If that is the case, consider implementing a Clang compiler warning.
+ On the other hand, a check might not be acceptable as a compiler
+ warning; for example, because of a relatively high false positive rate. In this
+ 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>
+ </pre>
+
+<h2 id=commands>Useful Commands/Debugging Hints</h2>
+<ul>
+<li>
+While investigating a checker-related issue, instruct the analyzer to only execute a single checker:
+<br><tt>
+$ <b>clang -cc1 -analyze -analyzer-checker=osx.KeychainAPI test.c</b>
+</tt>
+</li>
+<li>
+To dump AST:
+<br><tt>
+$ <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>
+$ <b>clang -cc1 -analyze -analyzer-checker=debug.ViewCFG test.c</b>
+</tt>
+</li>
+<li>
+To see all available debug checkers:
+<br><tt>
+$ <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>
+(gdb) <b>p ViewGraph(0)</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>
+(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>
+(gdb) <b>p ENode->getCodeDecl().getBody()->dump(getContext().getSourceManager())</b>
+</tt>
+</li>
+</ul>
+
+</div>
+</div>
+</body>
+</html>
More information about the cfe-commits
mailing list