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