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