Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / clang / c12f7dc59d6c762e70bccd2a56c278df40a9d356 / . / www / StaticAnalysis.html
blob: eea51d5f7095a0f8fcec93f8dedd6ca0aff4e684 [file] [log] [blame]
Ted Kremenekce2e3322008-04-25 18:44:36 +0000[diff] [blame]1<html>
2<head>
Ted Kremenek12049292008-06-12 19:14:13 +0000[diff] [blame]3 <title>Information on using the Static Analyzer ("Clang Checker")</title>
Ted Kremenek20c5f142008-06-11 05:26:52 +0000[diff] [blame]4 <link type="text/css" rel="stylesheet" href="menu.css" />
5 <link type="text/css" rel="stylesheet" href="content.css" />
Ted Kremeneke0665ab2008-06-11 05:55:39 +0000[diff] [blame]6 <style>
Ted Kremenek482c6d42008-06-11 05:28:36 +0000[diff] [blame]7 thead {
8 background-color:#eee; color:#666666;
9 font-weight: bold; cursor: default;
10 text-align:center;
11 border-top: 2px solid #000000;
12 border-bottom: 2px solid #000000;
13 font-weight: bold; font-family: Verdana
14 }
15 table { border: 1px #000000 solid }
16 table { border-collapse: collapse; border-spacing: 0px }
17 table { margin-left:20px; margin-top:20px; margin-bottom:20px }
18 td { border-bottom: 1px #000000 dotted }
19 td { padding:5px; padding-left:8px; padding-right:8px }
20 td { text-align:left; font-size:9pt }
21 td.View { padding-left: 10px }
22 </style>
Ted Kremenekce2e3322008-04-25 18:44:36 +0000[diff] [blame]23</head>
24<body>
25
Ted Kremenek20c5f142008-06-11 05:26:52 +0000[diff] [blame]26<!--#include virtual="menu.html.incl"-->
27
28<div id="content">
29
Ted Kremenek43bfbaf2008-06-11 06:01:28 +0000[diff] [blame]30<h1>Information on using the Static Analyzer</h1>
Ted Kremenekce2e3322008-04-25 18:44:36 +0000[diff] [blame]31
Ted Kremenek12049292008-06-12 19:14:13 +0000[diff] [blame]32<p>This page provides some notes on using the LLVM/clang static analyzer to find
33bugs in C and Objective-C programs.</p>
Ted Kremenekbe6e5162008-06-11 05:25:12 +0000[diff] [blame]34
Ted Kremenekb8a522f2008-06-11 16:09:34 +0000[diff] [blame]35<p>Currently the analyzer is invoked as a command-line tool. It is intended to
Ted Kremenekbc757862008-06-12 18:39:02 +0000[diff] [blame]36run in tandem with a build of a project or code base. Analysis results are
Ted Kremenekb8a522f2008-06-11 16:09:34 +0000[diff] [blame]37deposited in a directory as HTML files, which can then viewed using a web
Ted Kremenekbc757862008-06-12 18:39:02 +0000[diff] [blame]38browser (open the generated <tt>index.html</tt> file to view a list of flagged
39errors).</p>
Ted Kremenekb8a522f2008-06-11 16:09:34 +0000[diff] [blame]40
Ted Kremenekbc757862008-06-12 18:39:02 +0000[diff] [blame]41<h3>Important Notes (Please Read)</h3>
42
43<p>Here are some important points we ask you to consider when using the static
44analyzer:</p>
45
46<ul>
47
48<li><b>This tool is <b>very early</b> in development.</b> There are many planned
49enhancements to improve both the precision and scope of its analysis algorithms
50as well as the kinds bugs it will find.</li>
51
52<li><b>False positives.</b> Static analysis reasons about the run-time behavior
53of a program without actually running the program. Static analysis is not
54perfect, and can falsely flag bugs in a program where the code behaves
55correctly. Because some code checks performed by the analyzer require more
56analysis than others, the frequency of false positives can vary widely between
57different checks. Our goal is to have the analyzer have a low false positive
58rate for most code on all checks, and we will reach this goal by gradually
59improving over time the analysis precision of the tool.</li>
60
61<li><b>Static analysis can be much slower than compilation.</b> The analyzer
62performs a variety of checks on code, each requiring different levels of
63analysis precision (more precision = more CPU time). While the analyzer is being
64designed to be as fast and light-weight as possible, please do not expect it to
65be as fast as compiling a program (even with optimizations enabled). Some of the
66algorithms needed to find bugs require in the worst case exponential time. The
67analyzer runs in a reasonable amount of time by both bounding the amount of
68checking work it will do as well as using clever algorithms to reduce the amount
69of work it must do to find bugs.</li>
70
71</ul>
Ted Kremenekb8a522f2008-06-11 16:09:34 +0000[diff] [blame]72
73<h3>Organization</h3>
74
75<p>This page is arranged into the following sections:</p>
Ted Kremenekce2e3322008-04-25 18:44:36 +0000[diff] [blame]76
77<ul>
Ted Kremenekbd317162008-06-09 14:30:01 +0000[diff] [blame]78 <li><a href="#Contents">Obtaining the Analyzer</a></li>
Ted Kremenekce2e3322008-04-25 18:44:36 +0000[diff] [blame]79 <li><a href="#BasicUsage">Basic Usage</a></li>
Ted Kremenek891a3532008-04-25 20:29:37 +0000[diff] [blame]80 <li><a href="#Output">Output of the Analyzer</a></li>
81 <li><a href="#RecommendedUsageGuidelines">Recommended Usage Guidelines</a></li>
Ted Kremenekbc757862008-06-12 18:39:02 +0000[diff] [blame]82 <li><a href="#Debugging">Debugging the Analyzer</a></li>
83 <li><a href="#filingbugs">Filing Bugs</a></li>
Ted Kremenekce2e3322008-04-25 18:44:36 +0000[diff] [blame]84</ul>
85
Ted Kremenekbd317162008-06-09 14:30:01 +0000[diff] [blame]86<h2 id="ReleaseContents">Obtaining the Analyzer</h2>
Ted Kremenekce2e3322008-04-25 18:44:36 +0000[diff] [blame]87
Ted Kremenekbe6e5162008-06-11 05:25:12 +0000[diff] [blame]88<p> Using the analyzer involves executing <tt>scan-build</tt> (see <a
89href="#BasicUsage">Basic Usage</a>). <tt>scan-build</tt> will first look for a
90<tt>clang</tt> executable in the same directory as <tt>scan-build</tt>, and then
91search your path.</p>
92
93<p>If one is using the analyzer directly from the Clang sources, it suffices to
94just directly execute <tt>scan-build</tt> in the <tt>utils</tt> directory. No
95other special installation is needed.</p>
96
Ted Kremenekd53ab9f2008-06-11 16:16:41 +0000[diff] [blame]97<h3>Packaged Builds (Mac OS X)</h3>
Ted Kremenekbe6e5162008-06-11 05:25:12 +0000[diff] [blame]98
Ted Kremenekbc757862008-06-12 18:39:02 +0000[diff] [blame]99<p>Semi-regular pre-built binaries of the analyzer are available on Mac OS X
100(10.5).</p>
Ted Kremenekd53ab9f2008-06-11 16:16:41 +0000[diff] [blame]101
102<p>The latest build is: <b><a
Ted Kremenek75a25202008-06-16 21:46:12 +0000[diff] [blame]103href="http://keeda.stanford.edu/~kremenek/checker/checker-37.tar.gz">checker-37.tar.gz</a></b> (built June 16, 2008)</p>
104
105<p><b>Note: This fixes a serious bug in checker-36 where the analyzer would
106never be run, thus finding no bugs.</b></p>
Ted Kremenekd53ab9f2008-06-11 16:16:41 +0000[diff] [blame]107
Ted Kremenekbc757862008-06-12 18:39:02 +0000[diff] [blame]108Packaged builds for other platforms may eventually be provided, but as the tool
109is in its early stages we are not actively promoting releases yet. If you wish
110to help contribute regular builds of the analyzer on other platforms, please
111email the <a href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev">Clang
112Developers' mailing list</a>.</p>
Ted Kremenekbd317162008-06-09 14:30:01 +0000[diff] [blame]113
Ted Kremenekbe6e5162008-06-11 05:25:12 +0000[diff] [blame]114<p>Packaged builds of the analyzer expand to the following files:</p>
Ted Kremenekce2e3322008-04-25 18:44:36 +0000[diff] [blame]115
Ted Kremenekbe6e5162008-06-11 05:25:12 +0000[diff] [blame]116<table id="package">
Ted Kremenekce2e3322008-04-25 18:44:36 +0000[diff] [blame]117<thead><tr><td>File</td><td>Purpose</td></tr></thead>
118<tr><td><tt><b>scan-build</b></tt></td><td>Script for running the analyzer over a project build. <b>This is the only file you care about.</b></td></tr>
119<tr><td><tt>ccc-analyzer</tt></td><td>GCC interceptor (called by scan-build)</td></tr>
120<tr><td><tt>clang</tt></td><td>Static Analyzer (called by ccc-analyzer)</td><tr>
121<tr><td><tt>sorttable.js</tt></td><td>JavaScript used for displaying error reports</td></tr>
122</table>
123
Ted Kremenekbe6e5162008-06-11 05:25:12 +0000[diff] [blame]124<h3>Other Platforms (Building the Analyzer from Source)</h3>
125
126<p>Packaged builds simply consist of a few files from the Clang source tree,
127meaning that <b>anyone</b> who can build Clang can use the static analyzer.
128Please see the <a href="get_started.html">Getting Started</a> page for more
129details on downloading and compiling Clang.</p>
130
131<p>All files used by the analyzer (and included in packaged builds; <a
132href="#package">see above</a>) other than a compiled <tt>clang</tt> executable
133are found in the <tt>utils</tt> subdirectory in the Clang tree.</p>
Ted Kremenekbd317162008-06-09 14:30:01 +0000[diff] [blame]134
Ted Kremenekce2e3322008-04-25 18:44:36 +0000[diff] [blame]135<h2 id="BasicUsage">Basic Usage</h2>
136
137<p>The analyzer is executed from the command-line. To run the analyzer, you will
138use <tt>scan-build</tt> to analyze the source files compiled by <tt>gcc</tt>
139during a project build.</p>
140
141<p>For example, to analyze the files compiled under a build:</p>
142
143<pre>
144 $ <b>scan-build</b> make
145 $ <b>scan-build</b> xcodebuild
146</pre>
147
148<p> In the first case <tt>scan-build</tt> analyzes the code of a project built
149with <tt>make</tt>, andin the second case <tt>scan-build</tt> analyzes a project
150built using <tt>xcodebuild</tt>. In general, the format is: </p>
151
152<pre>
153 $ <b>scan-build</b> <i>[scan-build options]</i> <b>&lt;command&gt;</b> <i>[command options]</i>
154</pre>
155
156<p> Operationally, <tt>scan-build</tt> literally runs <command> with all of the
157subsequent options passed to it. For example</p>
158
159<pre>
160 $ scan-build make <b>-j4</b>
161</pre>
162
163<p>In this example, <tt>scan-build</tt> makes no effort to interpret the options
164after the build command (in this case, <tt>make</tt>); it just passes them
165through. In general, <tt>scan-build</tt> should support parallel builds, but
166<b>not distributed builds</b>. Similarly, you can use <tt>scan-build</tt> to
167analyze specific files:
168
169<pre>
170 $ scan-build gcc -c <b>t1.c t2.c</b>
171</pre>
172
173<p>
174This example causes the files <tt>t1.c</tt> and <tt>t2.c</tt> to be analyzed.
175</p>
176
177<h3>Other Options</h3>
178
179<p>
180As mentioned above, extra options can be passed to <tt>scan-build</tt>. These
181options prefix the build command. For example:</p>
182
183<pre>
184 $ scan-build <b>-k -V</b> make
185 $ scan-build <b>-k -V</b> xcodebuild
186</pre>
187
188<p>Here are a complete list of options:</p>
189
190<table>
191 <thead><tr><td>Option</td><td>Description</td></tr></thead>
192
Ted Kremenekbe6e5162008-06-11 05:25:12 +0000[diff] [blame]193 <tr><td><b>-a</b></td>
194 <td>The analysis to run. The default analysis is <i>checker-cfref</i>. Valid options are: <i>checker-cfref</i>, <i>fsyntax-only</i>.
195 These translate into options passed down to the <tt>clang</tt> executable, and currently this option is mainly used for debugging.</td></tr>
196
Ted Kremenekce2e3322008-04-25 18:44:36 +0000[diff] [blame]197 <tr><td><b>-o</b></td><td>Target directory for HTML report files. Subdirectories will be
198 created as needed to represent separate "runs" of the analyzer. If this option
199is not specified, a directory is created in <tt>/tmp</tt> to store the
200reports.</td><tr>
201
202 <tr><td><b>-h</b><br><i><nobr>(or no arguments)</nobr></i></td><td>Display <tt>scan-build</tt> options.</td></tr>
203
204 <tr><td><b>-k</b><br><nobr><b>--keep-going</b></nobr></td><td>Add a "keep on going" option to the
205 specified build command. <p>This option currently supports <tt>make</tt> and
206 <tt>xcodebuild</tt>.</p> <p>This is a convenience option; one can specify this
207 behavior directly using build options.</p></td></tr>
208
Ted Kremenekbe6e5162008-06-11 05:25:12 +0000[diff] [blame]209 <tr><td><b>-v<b></td><td>Verbose output from scan-build and the analyzer. <b>A second and third
Ted Kremenekce2e3322008-04-25 18:44:36 +0000[diff] [blame]210 "-v" increases verbosity</b>, and is useful for filing bug reports against the analyzer.</td></tr>
211
212 <tr><td><b>-V</b></td><td>View analysis results in a web browser when the build command completes.</td></tr>
213</table>
214
215<p>These options can also be viewed by running <tt>scan-build</tt> with no
216arguments:</p>
217
218<pre>
219 $ <b>scan-build</b>
220
221 USAGE: scan-build [options] &lt;build command&gt; [build options]
222
223 OPTIONS:
224
Ted Kremenekbe6e5162008-06-11 05:25:12 +0000[diff] [blame]225 -a - The analysis to run. The default is 'checker-cfref'.
226 Valid options are: 'checker-cfref', 'fsyntax-only'
227
Ted Kremenekce2e3322008-04-25 18:44:36 +0000[diff] [blame]228 -o - Target directory for HTML report files. Subdirectories
229 will be created as needed to represent separate "runs" of
230 the analyzer. If this option is not specified, a directory
231 is created in /tmp to store the reports.
232 <b>...</b>
233</pre>
234
235<h2 id="Output">Output of the Analyzer</h2>
236
237<p>
238The output of the analyzer is a set of HTML files, each one which represents a
239separate bug report. A single <tt>index.html</tt> file is generated for
240surveying all of the bugs. You can then just open <tt>index.html</tt> in a web
241browser to view the bug reports.
242</p>
243
244<p>
245Where the HTML files are generated is specified with a <b>-o</b> option to
Ted Kremenek87e795e2008-04-25 20:31:58 +0000[diff] [blame]246<tt>scan-build</tt>. If <b>-o</b> isn't specified, a directory in <tt>/tmp</tt>
Ted Kremenekce2e3322008-04-25 18:44:36 +0000[diff] [blame]247is created to store the files (<tt>scan-build</tt> will print a message telling
248you where they are). If you want to view the reports immediately after the build
249completes, pass <b>-V</b> to <tt>scan-build</tt>.
250</p>
251
252
Ted Kremenek904f1002008-04-25 20:30:34 +0000[diff] [blame]253<h2 id="RecommendedUsageGuidelines">Recommended Usage Guidelines</h2>
Ted Kremenekce2e3322008-04-25 18:44:36 +0000[diff] [blame]254
255Here are a few recommendations with running the analyzer:
256
257<h3>Always Analyze a Project in its "Debug" Configuration</h3>
258
Ted Kremenekbc757862008-06-12 18:39:02 +0000[diff] [blame]259<p>Most projects can be built in a "debug" mode that enables assertions.
260Assertions are picked up by the static analyzer to prune infeasible paths, which
261in some cases can greatly reduce the number of false positives (bogus error
262reports) emitted by the tool.</p>
Ted Kremenekce2e3322008-04-25 18:44:36 +0000[diff] [blame]263
264<h3>Pass -k to <tt>scan-build</tt></h3>
265
266<p>While <tt>ccc-analyzer</tt> invokes <tt>gcc</tt> to compile code, any
267problems in correctly forwarding arguments to <tt>gcc</tt> may result in a build
268failure. Passing <b>-k</b> to <tt>scan-build</tt> potentially allows you to
269analyze other code in a project for which this problem doesn't occur.</p>
270
271<p> Also, it is useful to analyze a project even if not all of the source files
272are compilable. This is great when using <tt>scan-build</tt> as part of your
273compile-debug cycle.</p>
274
275<h3>Use Verbose Output when Debugging <tt>scan-build</tt></h3>
276
Ted Kremenekbc757862008-06-12 18:39:02 +0000[diff] [blame]277<p><tt>scan-build</tt> takes a <b>-v</b> option to emit verbose output about
278what it's doing; two <b>-v</b> options emit more information. Redirecting the
279output of <tt>scan-build</tt> to a text file (make sure to redirect standard
280error) is useful for filing bug reports against <tt>scan-build</tt> or the
281analyzer, as we can see the exact options (and files) passed to the analyzer.
282For more comprehendible logs, don't perform a parallel build.</p>
Ted Kremenekce2e3322008-04-25 18:44:36 +0000[diff] [blame]283
284<h2 id="Debugging">Debugging the Analyzer</h2>
285
Ted Kremenekbc757862008-06-12 18:39:02 +0000[diff] [blame]286<p>This section provides information on debugging the analyzer, and troubleshooting
287it when you have problems analyzing a particular project.</p>
Ted Kremenekce2e3322008-04-25 18:44:36 +0000[diff] [blame]288
289<h3>How it Works</h3>
290
Ted Kremenekbc757862008-06-12 18:39:02 +0000[diff] [blame]291<p>To analyze a project, <tt>scan-build</tt> simply sets the environment variable
Ted Kremenekce2e3322008-04-25 18:44:36 +0000[diff] [blame]292<tt>CC</tt> to the full path to <tt>ccc-analyzer</tt>. It also sets a few other
293environment variables to communicate to <tt>ccc-analyzer</tt> where to dump HTML
Ted Kremenekbc757862008-06-12 18:39:02 +0000[diff] [blame]294report files.</p>
Ted Kremenekce2e3322008-04-25 18:44:36 +0000[diff] [blame]295
296<p>Some Makefiles (or equivalent project files) hardcode the compiler; for such
297projects simply overriding <tt>CC</tt> won't cause <tt>ccc-analyzer</tt> to be
298called. This will cause the compiled code <b>to not be analyzed.</b></p> If you
299find that your code isn't being analyzed, check to see if <tt>CC</tt> is
300hardcoded. If this is the case, you can hardcode it instead to the <b>full
301path</b> to <tt>ccc-analyzer</tt>.</p>
302
303<p>When applicable, you can also run <tt>./configure</tt> for a project through
304<tt>scan-build</tt> so that configure sets up the location of <tt>CC</tt> based
305on the environment passed in from <tt>scan-build</tt>:
306
307<pre>
308 $ scan-build <b>./configure</b>
309</pre>
310
311<p><tt>scan-build</tt> has special knowledge about <tt>configure</tt>, so it in
312most cases will not actually analyze the configure tests run by
313<tt>configure</tt>.</p>
314
315<p>Under the hood, <tt>ccc-analyzer</tt> directly invokes <tt>gcc</tt> to
316compile the actual code in addition to running the analyzer (which occurs by it
317calling <tt>clang</tt>). <tt>ccc-analyzer</tt> tries to correctly forward all
318the arguments over to <tt>gcc</tt>, but this may not work perfectly (please
319report bugs of this kind).
320
Ted Kremenekbc757862008-06-12 18:39:02 +0000[diff] [blame]321<h2 id="filingbugs">Filing Bugs</h2>
Ted Kremenekce2e3322008-04-25 18:44:36 +0000[diff] [blame]322
Ted Kremenekbc757862008-06-12 18:39:02 +0000[diff] [blame]323<p>We encourage users to file bug reports for any problems that they
324encounter.</p>
Ted Kremenekbe6e5162008-06-11 05:25:12 +0000[diff] [blame]325
Ted Kremenekbc757862008-06-12 18:39:02 +0000[diff] [blame]326<h3>Outside Apple</h3>
Ted Kremenekbe6e5162008-06-11 05:25:12 +0000[diff] [blame]327
Ted Kremenekbc757862008-06-12 18:39:02 +0000[diff] [blame]328<p>Please <a href="http://llvm.org/bugs/enter_bug.cgi?product=clang">file
329bugs</a> (against Clang) in LLVM's Bugzilla database.</p>
330
331<h3>Apple-internal Users</h3>
332
333<p>Please file bugs in Radar against the <b>llvm - clang</b> component.</p>
334
Ted Kremenekbe6e5162008-06-11 05:25:12 +0000[diff] [blame]335
Ted Kremenek20c5f142008-06-11 05:26:52 +0000[diff] [blame]336</div>
Ted Kremenekbe6e5162008-06-11 05:25:12 +0000[diff] [blame]337</body>
338</html>