blob: 50f8b748472eca7931919cd253d5463561bf32d2 [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 }
Ted Kremenekce2e3322008-04-25 18:44:36 +00007 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 }
Ted Kremenekbd317162008-06-09 14:30:01 +000017 table { margin-left:20px; margin-top:20px; margin-bottom:20px }
Ted Kremenekce2e3322008-04-25 18:44:36 +000018 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>
23</head>
24<body>
25
26<h1>Information on using the Static Analyzer ("LLVM Checker")</h1>
27
Ted Kremenekbd317162008-06-09 14:30:01 +000028<p>This documents provides some notes on using the LLVM/clang static analyzer
29to find bugs in C and Objective-C programs. Please note that this tool is very
30earlier in development, and there are many planned enhancements to improve both
31the analysis precision of the tool and the number of bugs it will find.</p>
Ted Kremenekce2e3322008-04-25 18:44:36 +000032
33<p>This document is arranged into the following sections:</p>
34
35<ul>
Ted Kremenekbd317162008-06-09 14:30:01 +000036 <li><a href="#Contents">Obtaining the Analyzer</a></li>
Ted Kremenekce2e3322008-04-25 18:44:36 +000037 <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
Ted Kremenekbd317162008-06-09 14:30:01 +000043<h2 id="ReleaseContents">Obtaining the Analyzer</h2>
Ted Kremenekce2e3322008-04-25 18:44:36 +000044
Ted Kremenekbd317162008-06-09 14:30:01 +000045<p> Semi-regular builds of the analyzer on Mac OS X (10.5) are available <a
46href="http://keeda.stanford.edu/~kremenek/checker">here</a>. Packaged builds for
47other platforms may eventually be provided, but as the tool is in its early
48stages we are not actively promoting releases yet.</p>
49
50<p>Packaged builds consist of a few files from the Clang source tree, meaning
51that <b>anyone</b> who can build Clang can use the static analyzer. The packaged
52builds of the analyzer expand to the following files that are taken from the
53<tt>utils</tt> and <tt>Driver</tt> subdirectories in the Clang tree:</p>
Ted Kremenekce2e3322008-04-25 18:44:36 +000054
55<table>
56<thead><tr><td>File</td><td>Purpose</td></tr></thead>
57<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>
58<tr><td><tt>ccc-analyzer</tt></td><td>GCC interceptor (called by scan-build)</td></tr>
59<tr><td><tt>clang</tt></td><td>Static Analyzer (called by ccc-analyzer)</td><tr>
60<tr><td><tt>sorttable.js</tt></td><td>JavaScript used for displaying error reports</td></tr>
61</table>
62
Ted Kremenekbd317162008-06-09 14:30:01 +000063<p> Using the analyzer involves executing <tt>scan-build</tt> (see <a
64href="#BasicUsage">Basic Usage</a>). <tt>scan-build</tt> will first look for a
65<tt>clang</tt> executable in the same directory as <tt>scan-build</tt>, and then
66search your path. If one is using the analyzer directly from the Clang sources,
67it suffices to just directly execute <tt>scan-build</tt> in the <tt>utils</tt>
68directory. No other special installation is needed.</p>
69
Ted Kremenekce2e3322008-04-25 18:44:36 +000070<h2 id="BasicUsage">Basic Usage</h2>
71
72<p>The analyzer is executed from the command-line. To run the analyzer, you will
73use <tt>scan-build</tt> to analyze the source files compiled by <tt>gcc</tt>
74during a project build.</p>
75
76<p>For example, to analyze the files compiled under a build:</p>
77
78<pre>
79 $ <b>scan-build</b> make
80 $ <b>scan-build</b> xcodebuild
81</pre>
82
83<p> In the first case <tt>scan-build</tt> analyzes the code of a project built
84with <tt>make</tt>, andin the second case <tt>scan-build</tt> analyzes a project
85built using <tt>xcodebuild</tt>. In general, the format is: </p>
86
87<pre>
88 $ <b>scan-build</b> <i>[scan-build options]</i> <b>&lt;command&gt;</b> <i>[command options]</i>
89</pre>
90
91<p> Operationally, <tt>scan-build</tt> literally runs <command> with all of the
92subsequent options passed to it. For example</p>
93
94<pre>
95 $ scan-build make <b>-j4</b>
96</pre>
97
98<p>In this example, <tt>scan-build</tt> makes no effort to interpret the options
99after the build command (in this case, <tt>make</tt>); it just passes them
100through. In general, <tt>scan-build</tt> should support parallel builds, but
101<b>not distributed builds</b>. Similarly, you can use <tt>scan-build</tt> to
102analyze specific files:
103
104<pre>
105 $ scan-build gcc -c <b>t1.c t2.c</b>
106</pre>
107
108<p>
109This example causes the files <tt>t1.c</tt> and <tt>t2.c</tt> to be analyzed.
110</p>
111
112<h3>Other Options</h3>
113
114<p>
115As mentioned above, extra options can be passed to <tt>scan-build</tt>. These
116options prefix the build command. For example:</p>
117
118<pre>
119 $ scan-build <b>-k -V</b> make
120 $ scan-build <b>-k -V</b> xcodebuild
121</pre>
122
123<p>Here are a complete list of options:</p>
124
125<table>
126 <thead><tr><td>Option</td><td>Description</td></tr></thead>
127
128 <tr><td><b>-o</b></td><td>Target directory for HTML report files. Subdirectories will be
129 created as needed to represent separate "runs" of the analyzer. If this option
130is not specified, a directory is created in <tt>/tmp</tt> to store the
131reports.</td><tr>
132
133 <tr><td><b>-h</b><br><i><nobr>(or no arguments)</nobr></i></td><td>Display <tt>scan-build</tt> options.</td></tr>
134
135 <tr><td><b>-k</b><br><nobr><b>--keep-going</b></nobr></td><td>Add a "keep on going" option to the
136 specified build command. <p>This option currently supports <tt>make</tt> and
137 <tt>xcodebuild</tt>.</p> <p>This is a convenience option; one can specify this
138 behavior directly using build options.</p></td></tr>
139
140 <tr><td><b>-v<b></td><td>Verbose output from scan-build and the analyzer. <b>A second
141 "-v" increases verbosity</b>, and is useful for filing bug reports against the analyzer.</td></tr>
142
143 <tr><td><b>-V</b></td><td>View analysis results in a web browser when the build command completes.</td></tr>
144</table>
145
146<p>These options can also be viewed by running <tt>scan-build</tt> with no
147arguments:</p>
148
149<pre>
150 $ <b>scan-build</b>
151
152 USAGE: scan-build [options] &lt;build command&gt; [build options]
153
154 OPTIONS:
155
156 -o - Target directory for HTML report files. Subdirectories
157 will be created as needed to represent separate "runs" of
158 the analyzer. If this option is not specified, a directory
159 is created in /tmp to store the reports.
160 <b>...</b>
161</pre>
162
163<h2 id="Output">Output of the Analyzer</h2>
164
165<p>
166The output of the analyzer is a set of HTML files, each one which represents a
167separate bug report. A single <tt>index.html</tt> file is generated for
168surveying all of the bugs. You can then just open <tt>index.html</tt> in a web
169browser to view the bug reports.
170</p>
171
172<p>
173Where the HTML files are generated is specified with a <b>-o</b> option to
Ted Kremenek87e795e2008-04-25 20:31:58 +0000174<tt>scan-build</tt>. If <b>-o</b> isn't specified, a directory in <tt>/tmp</tt>
Ted Kremenekce2e3322008-04-25 18:44:36 +0000175is created to store the files (<tt>scan-build</tt> will print a message telling
176you where they are). If you want to view the reports immediately after the build
177completes, pass <b>-V</b> to <tt>scan-build</tt>.
178</p>
179
180
Ted Kremenek904f1002008-04-25 20:30:34 +0000181<h2 id="RecommendedUsageGuidelines">Recommended Usage Guidelines</h2>
Ted Kremenekce2e3322008-04-25 18:44:36 +0000182
183Here are a few recommendations with running the analyzer:
184
185<h3>Always Analyze a Project in its "Debug" Configuration</h3>
186
187Most projects can be built in a "debug" mode that enables assertions. Assertions
188are picked up by the static analyzer to prune infeasible paths, which in some
189cases can greatly reduce the number of false positives (bogus error reports)
190emitted by the tool.
191
192<h3>Pass -k to <tt>scan-build</tt></h3>
193
194<p>While <tt>ccc-analyzer</tt> invokes <tt>gcc</tt> to compile code, any
195problems in correctly forwarding arguments to <tt>gcc</tt> may result in a build
196failure. Passing <b>-k</b> to <tt>scan-build</tt> potentially allows you to
197analyze other code in a project for which this problem doesn't occur.</p>
198
199<p> Also, it is useful to analyze a project even if not all of the source files
200are compilable. This is great when using <tt>scan-build</tt> as part of your
201compile-debug cycle.</p>
202
203<h3>Use Verbose Output when Debugging <tt>scan-build</tt></h3>
204
205<tt>scan-build</tt> takes a <b>-v</b> option to emit verbose output about what
206it's doing; two <b>-v</b> options emit more information. Redirecting the output
207of <tt>scan-build</tt> to a text file (make sure to redirect standard error) is
208useful for filing bug reports against <tt>scan-build</tt> or the analyzer, as we
209can see the exact options (and files) passed to the analyzer. For more
210comprehendible logs, don't perform a parallel build.
211
212<h2 id="Debugging">Debugging the Analyzer</h2>
213
214This section provides information on debugging the analyzer, and troubleshooting
215it when you have problems analyzing a particular project.
216
217<h3>How it Works</h3>
218
219To analyze a project, <tt>scan-build</tt> simply sets the environment variable
220<tt>CC</tt> to the full path to <tt>ccc-analyzer</tt>. It also sets a few other
221environment variables to communicate to <tt>ccc-analyzer</tt> where to dump HTML
222report files.
223
224<p>Some Makefiles (or equivalent project files) hardcode the compiler; for such
225projects simply overriding <tt>CC</tt> won't cause <tt>ccc-analyzer</tt> to be
226called. This will cause the compiled code <b>to not be analyzed.</b></p> If you
227find that your code isn't being analyzed, check to see if <tt>CC</tt> is
228hardcoded. If this is the case, you can hardcode it instead to the <b>full
229path</b> to <tt>ccc-analyzer</tt>.</p>
230
231<p>When applicable, you can also run <tt>./configure</tt> for a project through
232<tt>scan-build</tt> so that configure sets up the location of <tt>CC</tt> based
233on the environment passed in from <tt>scan-build</tt>:
234
235<pre>
236 $ scan-build <b>./configure</b>
237</pre>
238
239<p><tt>scan-build</tt> has special knowledge about <tt>configure</tt>, so it in
240most cases will not actually analyze the configure tests run by
241<tt>configure</tt>.</p>
242
243<p>Under the hood, <tt>ccc-analyzer</tt> directly invokes <tt>gcc</tt> to
244compile the actual code in addition to running the analyzer (which occurs by it
245calling <tt>clang</tt>). <tt>ccc-analyzer</tt> tries to correctly forward all
246the arguments over to <tt>gcc</tt>, but this may not work perfectly (please
247report bugs of this kind).
248
249<h3>Filing Bugs</h3>
250
251We encourage users to file bug reports for any problems that they encounter.
252Apple-internal users should file bugs in Radar against the <b>llvm - clang</b>
253component. External-Apple users should file bugs in <a
254href="http://llvm.org/bugs/enter_bug.cgi?product=clang">LLVM's Bugzilla against
255clang</a>.