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