Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / clang / d67fc49da93be0e3c1620b70746cc1bfae9878b0 / . / www / analyzer / checker_dev_manual.html
blob: b31b11b477fce0b60a2f30b1bdf560cc390b8417 [file] [log] [blame]
Anna Zaksd67fc492011-11-02 17:49:20 +0000[diff] [blame^]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd">
3<html>
4<head>
5 <title>Checker Developer Manual</title>
6 <link type="text/css" rel="stylesheet" href="menu.css" />
7 <link type="text/css" rel="stylesheet" href="content.css" />
8 <script type="text/javascript" src="scripts/menu.js"></script>
9</head>
10<body>
11
12<div id="page">
13<!--#include virtual="menu.html.incl"-->
14
15<div id="content">
16
17<h1><font color=red>This Page Is Under Construction</font></h1>
18
19<h1>Checker Developer Manual</h1>
20
21<p>The static analyzer engine performs symbolic execution of the program and
22relies on a set of checkers to implement the logic for detecting and
23constructing bug reports. This page provides hints and guidelines for anyone
24who is interested in implementing their own checker. The static analyzer is a
25part of the Clang project, so consult <a href="http://clang.llvm.org/hacking.html">Hacking on Clang</a>
26and <a href="http://llvm.org/docs/ProgrammersManual.html">LLVM Programmer's Manual</a>
27for general developer guidelines and information. </p>
28
29 <ul>
30 <li><a href="#start">Getting Started</a></li>
31 <li><a href="#analyzer">Static Analyzer Overview</a></li>
32 <li><a href="#idea">Idea for a Checker</a></li>
33 <li><a href="#skeleton">Checker Skeleton</a></li>
34 <li><a href="#node">Exploded Node</a></li>
35 <li><a href="#bugs">Bug Reports</a></li>
36 <li><a href="#ast">AST Visitors</a></li>
37 <li><a href="#testing">Testing</a></li>
38 <li><a href="#commands">Useful Commands</a></li>
39 </ul>
40
41<h2 id=start>Getting Started</h2>
42 <ul>
43 <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>
44 page.</li>
45
46 <li>The analyzer source code is located under the Clang source tree:
47 <br><tt>
48 $ <b>cd llvm/tools/clang</b>
49 </tt>
50 <br>See: <tt>include/clang/StaticAnalyzer</tt>, <tt>lib/StaticAnalyzer</tt>, <tt>test/Analysis</tt>.</li>
51
52 <li>The analyzer regression tests can be executed from the Clang's build directory:
53 <br><tt>
54 $ <b>cd ../../../; cd build/tools/clang; TESTDIRS=Analysis make test</b>
55 </tt></li>
56
57 <li>Analyze a file with the specified checker:
58 <br><tt>
59 $ <b>clang -cc1 -analyze -analyzer-checker=core.DivideZero test.c</b>
60 </tt></li>
61
62 <li>List the available checkers:
63 <br><tt>
64 $ <b>clang -cc1 -analyzer-checker-help</b>
65 </tt></li>
66
67 <li>See the analyzer help for different output formats, fine tuning, and debug options:
68 <br><tt>
69 $ <b>clang -cc1 -help | grep "analyzer"</b>
70 </tt></li>
71
72 </ul>
73
74<h2 id=analyzer>Static Analyzer Overview</h2>
75 ExplidedGraph, ExplodedNode (ProgramPoint, State)<br>
76 Engine-Checker Interaction<br>
77 Symbols<br>
78
79
80<h2 id=idea>Idea for a Checker</h2>
81 Here are several questions which you should consider when evaluating your checker idea:
82 <ul>
83 <li>Can the check be effectively implemented without path-sensitive analysis? See <a href="#ast">AST Visitors</a>.</li>
84
85 <li>How high the false positive rate is going to be? Looking at the occurrences
86 of the issue you want to write a checker for in the existing code bases might give you some
87 ideas. </li>
88
89 <li>How the current limitations of the analysis will effect the false alarm
90 rate? Currently, the analyzer only reasons about one procedure at a time (no
91 inter-procedural analysis). Also, it uses a simple range tracking based solver to model symbolic
92 execution.</li>
93
94 <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>
95 to get some ideas for new checkers and consider starting with improving/fixing
96 bugs in the existing checkers.</li>
97 </ul>
98
99<h2 id=skeleton>Checker Skeleton</h2>
100 The source code for all the checkers goes into <tt>clang/lib/StaticAnalyzer/Checkers</tt>.<p>
101 There are two main decisions you need to make:
102 <ul>
103 <li> Which events the checker should be tracking.</li>
104 <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>
105 </ul>
106 Describe the registration process.
107
108<h2 id=bugs>Bug Reports</h2>
109
110<h2 id=ast>AST Visitors</h2>
111 Some checks might not require path-sensitivity to be effective. Simple AST walk
112 might be sufficient. If that is the case, consider implementing a Clang compiler warning.
113 On the other hand, a check might not be acceptable as a compiler
114 warning; for example, because of a relatively high false positive rate. In this
115 situation, AST callbacks <tt><b>checkASTDecl</b></tt> and
116 <tt><b>checkASTCodeBody</b></tt> are your best friends.
117
118<h2 id=testing>Testing</h2>
119 Every patch should be well tested with Clang regression tests. The checker tests
120 live in <tt>clang/test/Analysis</tt> folder. To run all of the analyzer tests,
121 execute the following from the <tt>clang</tt> build directory:
122 <pre class="code">
123 $ <b>TESTDIRS=Analysis make test</b>
124 </pre>
125
126<h2 id=commands>Useful Commands/Debugging Hints</h2>
127<ul>
128<li>
129While investigating a checker-related issue, instruct the analyzer to only execute a single checker:
130<br><tt>
131$ <b>clang -cc1 -analyze -analyzer-checker=osx.KeychainAPI test.c</b>
132</tt>
133</li>
134<li>
135To dump AST:
136<br><tt>
137$ <b>clang -cc1 -ast-dump test.c</b>
138</tt>
139</li>
140<li>
141To view/dump CFG use <tt>debug.ViewCFG</tt> or <tt>debug.DumpCFG</tt> checkers:
142<br><tt>
143$ <b>clang -cc1 -analyze -analyzer-checker=debug.ViewCFG test.c</b>
144</tt>
145</li>
146<li>
147To see all available debug checkers:
148<br><tt>
149$ <b>clang -cc1 -analyzer-checker-help | grep "debug"</b>
150</tt>
151</li>
152<li>
153To see which function is failing while processing a large file use <tt>-analyzer-display-progress</tt> option.
154</li>
155<li>
156While 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.
157</li>
158<li>
159To 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:
160<br><tt>
161(gdb) <b>p ViewGraph(0)</b>
162</tt>
163</li>
164<li>
165To 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.
166<br><tt>
167(gdb) <b>p E->dump()</b>
168</tt>
169</li>
170<li>
171To dump AST of a method that the current <tt>ExplodedNode</tt> belongs to:
172<br><tt>
173(gdb) <b>p ENode->getCodeDecl().getBody()->dump(getContext().getSourceManager())</b>
174</tt>
175</li>
176</ul>
177
178</div>
179</div>
180</body>
181</html>