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