blob: 7ff4020d27c6680720226491239ee761cbc99749 [file] [log] [blame]
Ted Kremenekce2e3322008-04-25 18:44:36 +00001<html>
2<head>
3 <title>Information on using the Static Analyzer ("LLVM Checker")</title>
4 <style type="text/css">
5 body { color:#000000; background-color:#ffffff }
6 body { font-family: Helvetica, sans-serif; font-size:9pt }
7 h1 { font-size:12pt }
8 thead {
9 background-color:#eee; color:#666666;
10 font-weight: bold; cursor: default;
11 text-align:center;
12 border-top: 2px solid #000000;
13 border-bottom: 2px solid #000000;
14 font-weight: bold; font-family: Verdana
15 }
16 table { border: 1px #000000 solid }
17 table { border-collapse: collapse; border-spacing: 0px }
18 table { margin-left:20px; margin-top:20px; margin-bottom:20px; width:80%;}
19 td { border-bottom: 1px #000000 dotted }
20 td { padding:5px; padding-left:8px; padding-right:8px }
21 td { text-align:left; font-size:9pt }
22 td.View { padding-left: 10px }
23 </style>
24</head>
25<body>
26
27<h1>Information on using the Static Analyzer ("LLVM Checker")</h1>
28
29<p>
30This documents provides some notes on using the LLVM/clang static analyzer to
31find bugs in C and Objective-C programs.
32
33<p>This document is arranged into the following sections:</p>
34
35<ul>
36 <li><a href="#Contents">Downloadable Package Contents</a></li>
37 <li><a href="#BasicUsage">Basic Usage</a></li>
Ted Kremenek891a3532008-04-25 20:29:37 +000038 <li><a href="#Output">Output of the Analyzer</a></li>
39 <li><a href="#RecommendedUsageGuidelines">Recommended Usage Guidelines</a></li>
40 <li><a href="#Debugging">Debugging the Analyzer</a>
Ted Kremenekce2e3322008-04-25 18:44:36 +000041</ul>
42
43<h2 id="ReleaseContents">Package Contents</h2>
44
45<p>The static analyzer is released as a single tarball:
46<tt>checker-XXX.tar.gz</tt>, where <b>XXX</b> is the release tag. The tarball
47expands to the following files:</p>
48
49<table>
50<thead><tr><td>File</td><td>Purpose</td></tr></thead>
51<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>
52<tr><td><tt>ccc-analyzer</tt></td><td>GCC interceptor (called by scan-build)</td></tr>
53<tr><td><tt>clang</tt></td><td>Static Analyzer (called by ccc-analyzer)</td><tr>
54<tr><td><tt>sorttable.js</tt></td><td>JavaScript used for displaying error reports</td></tr>
55</table>
56
57<h2 id="BasicUsage">Basic Usage</h2>
58
59<p>The analyzer is executed from the command-line. To run the analyzer, you will
60use <tt>scan-build</tt> to analyze the source files compiled by <tt>gcc</tt>
61during a project build.</p>
62
63<p>For example, to analyze the files compiled under a build:</p>
64
65<pre>
66 $ <b>scan-build</b> make
67 $ <b>scan-build</b> xcodebuild
68</pre>
69
70<p> In the first case <tt>scan-build</tt> analyzes the code of a project built
71with <tt>make</tt>, andin the second case <tt>scan-build</tt> analyzes a project
72built using <tt>xcodebuild</tt>. In general, the format is: </p>
73
74<pre>
75 $ <b>scan-build</b> <i>[scan-build options]</i> <b>&lt;command&gt;</b> <i>[command options]</i>
76</pre>
77
78<p> Operationally, <tt>scan-build</tt> literally runs <command> with all of the
79subsequent options passed to it. For example</p>
80
81<pre>
82 $ scan-build make <b>-j4</b>
83</pre>
84
85<p>In this example, <tt>scan-build</tt> makes no effort to interpret the options
86after the build command (in this case, <tt>make</tt>); it just passes them
87through. In general, <tt>scan-build</tt> should support parallel builds, but
88<b>not distributed builds</b>. Similarly, you can use <tt>scan-build</tt> to
89analyze specific files:
90
91<pre>
92 $ scan-build gcc -c <b>t1.c t2.c</b>
93</pre>
94
95<p>
96This example causes the files <tt>t1.c</tt> and <tt>t2.c</tt> to be analyzed.
97</p>
98
99<h3>Other Options</h3>
100
101<p>
102As mentioned above, extra options can be passed to <tt>scan-build</tt>. These
103options prefix the build command. For example:</p>
104
105<pre>
106 $ scan-build <b>-k -V</b> make
107 $ scan-build <b>-k -V</b> xcodebuild
108</pre>
109
110<p>Here are a complete list of options:</p>
111
112<table>
113 <thead><tr><td>Option</td><td>Description</td></tr></thead>
114
115 <tr><td><b>-o</b></td><td>Target directory for HTML report files. Subdirectories will be
116 created as needed to represent separate "runs" of the analyzer. If this option
117is not specified, a directory is created in <tt>/tmp</tt> to store the
118reports.</td><tr>
119
120 <tr><td><b>-h</b><br><i><nobr>(or no arguments)</nobr></i></td><td>Display <tt>scan-build</tt> options.</td></tr>
121
122 <tr><td><b>-k</b><br><nobr><b>--keep-going</b></nobr></td><td>Add a "keep on going" option to the
123 specified build command. <p>This option currently supports <tt>make</tt> and
124 <tt>xcodebuild</tt>.</p> <p>This is a convenience option; one can specify this
125 behavior directly using build options.</p></td></tr>
126
127 <tr><td><b>-v<b></td><td>Verbose output from scan-build and the analyzer. <b>A second
128 "-v" increases verbosity</b>, and is useful for filing bug reports against the analyzer.</td></tr>
129
130 <tr><td><b>-V</b></td><td>View analysis results in a web browser when the build command completes.</td></tr>
131</table>
132
133<p>These options can also be viewed by running <tt>scan-build</tt> with no
134arguments:</p>
135
136<pre>
137 $ <b>scan-build</b>
138
139 USAGE: scan-build [options] &lt;build command&gt; [build options]
140
141 OPTIONS:
142
143 -o - Target directory for HTML report files. Subdirectories
144 will be created as needed to represent separate "runs" of
145 the analyzer. If this option is not specified, a directory
146 is created in /tmp to store the reports.
147 <b>...</b>
148</pre>
149
150<h2 id="Output">Output of the Analyzer</h2>
151
152<p>
153The output of the analyzer is a set of HTML files, each one which represents a
154separate bug report. A single <tt>index.html</tt> file is generated for
155surveying all of the bugs. You can then just open <tt>index.html</tt> in a web
156browser to view the bug reports.
157</p>
158
159<p>
160Where the HTML files are generated is specified with a <b>-o</b> option to
161<ttscan-build</tt>. If <b>-o</b> isn't specified, a directory in <tt>/tmp</tt>
162is created to store the files (<tt>scan-build</tt> will print a message telling
163you where they are). If you want to view the reports immediately after the build
164completes, pass <b>-V</b> to <tt>scan-build</tt>.
165</p>
166
167
Ted Kremenek904f1002008-04-25 20:30:34 +0000168<h2 id="RecommendedUsageGuidelines">Recommended Usage Guidelines</h2>
Ted Kremenekce2e3322008-04-25 18:44:36 +0000169
170Here are a few recommendations with running the analyzer:
171
172<h3>Always Analyze a Project in its "Debug" Configuration</h3>
173
174Most projects can be built in a "debug" mode that enables assertions. Assertions
175are picked up by the static analyzer to prune infeasible paths, which in some
176cases can greatly reduce the number of false positives (bogus error reports)
177emitted by the tool.
178
179<h3>Pass -k to <tt>scan-build</tt></h3>
180
181<p>While <tt>ccc-analyzer</tt> invokes <tt>gcc</tt> to compile code, any
182problems in correctly forwarding arguments to <tt>gcc</tt> may result in a build
183failure. Passing <b>-k</b> to <tt>scan-build</tt> potentially allows you to
184analyze other code in a project for which this problem doesn't occur.</p>
185
186<p> Also, it is useful to analyze a project even if not all of the source files
187are compilable. This is great when using <tt>scan-build</tt> as part of your
188compile-debug cycle.</p>
189
190<h3>Use Verbose Output when Debugging <tt>scan-build</tt></h3>
191
192<tt>scan-build</tt> takes a <b>-v</b> option to emit verbose output about what
193it's doing; two <b>-v</b> options emit more information. Redirecting the output
194of <tt>scan-build</tt> to a text file (make sure to redirect standard error) is
195useful for filing bug reports against <tt>scan-build</tt> or the analyzer, as we
196can see the exact options (and files) passed to the analyzer. For more
197comprehendible logs, don't perform a parallel build.
198
199<h2 id="Debugging">Debugging the Analyzer</h2>
200
201This section provides information on debugging the analyzer, and troubleshooting
202it when you have problems analyzing a particular project.
203
204<h3>How it Works</h3>
205
206To analyze a project, <tt>scan-build</tt> simply sets the environment variable
207<tt>CC</tt> to the full path to <tt>ccc-analyzer</tt>. It also sets a few other
208environment variables to communicate to <tt>ccc-analyzer</tt> where to dump HTML
209report files.
210
211<p>Some Makefiles (or equivalent project files) hardcode the compiler; for such
212projects simply overriding <tt>CC</tt> won't cause <tt>ccc-analyzer</tt> to be
213called. This will cause the compiled code <b>to not be analyzed.</b></p> If you
214find that your code isn't being analyzed, check to see if <tt>CC</tt> is
215hardcoded. If this is the case, you can hardcode it instead to the <b>full
216path</b> to <tt>ccc-analyzer</tt>.</p>
217
218<p>When applicable, you can also run <tt>./configure</tt> for a project through
219<tt>scan-build</tt> so that configure sets up the location of <tt>CC</tt> based
220on the environment passed in from <tt>scan-build</tt>:
221
222<pre>
223 $ scan-build <b>./configure</b>
224</pre>
225
226<p><tt>scan-build</tt> has special knowledge about <tt>configure</tt>, so it in
227most cases will not actually analyze the configure tests run by
228<tt>configure</tt>.</p>
229
230<p>Under the hood, <tt>ccc-analyzer</tt> directly invokes <tt>gcc</tt> to
231compile the actual code in addition to running the analyzer (which occurs by it
232calling <tt>clang</tt>). <tt>ccc-analyzer</tt> tries to correctly forward all
233the arguments over to <tt>gcc</tt>, but this may not work perfectly (please
234report bugs of this kind).
235
236<h3>Filing Bugs</h3>
237
238We encourage users to file bug reports for any problems that they encounter.
239Apple-internal users should file bugs in Radar against the <b>llvm - clang</b>
240component. External-Apple users should file bugs in <a
241href="http://llvm.org/bugs/enter_bug.cgi?product=clang">LLVM's Bugzilla against
242clang</a>.