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