Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / clang / 01e56aecb77a96dcd93fa0e901b919f2e441981d / . / www / analyzer / scan-build.html
blob: 1db15fec99eb3958d10932cc8179884ac5e214a9 [file] [log] [blame]
Ted Kremenek591b9072009-06-08 21:21:24 +0000[diff] [blame]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd">
3<html>
4<head>
Ted Kremenek831a46a2010-02-19 05:36:44 +0000[diff] [blame]5 <title>scan-build: running the analyzer from the command line</title>
Ted Kremenek591b9072009-06-08 21:21:24 +0000[diff] [blame]6 <link type="text/css" rel="stylesheet" href="content.css" />
Ted Kremenekfe775382010-02-09 23:09:48 +0000[diff] [blame]7 <link type="text/css" rel="stylesheet" href="menu.css" />
Ted Kremenek0f399962010-02-19 08:14:02 +0000[diff] [blame]8 <script type="text/javascript" src="scripts/menu.js"></script>
9 <script type="text/javascript" src="scripts/dbtree.js"></script>
Ted Kremenek591b9072009-06-08 21:21:24 +0000[diff] [blame]10</head>
11<body>
12
Ted Kremenek8bebc6e2010-02-09 23:05:59 +0000[diff] [blame]13<div id="page">
Ted Kremenek591b9072009-06-08 21:21:24 +0000[diff] [blame]14<!--#include virtual="menu.html.incl"-->
Ted Kremenek591b9072009-06-08 21:21:24 +0000[diff] [blame]15<div id="content">
16
Ted Kremenek831a46a2010-02-19 05:36:44 +0000[diff] [blame]17<h1>scan-build: running the analyzer from the command line</h1>
Ted Kremenek591b9072009-06-08 21:21:24 +0000[diff] [blame]18
Ted Kremenek831a46a2010-02-19 05:36:44 +0000[diff] [blame]19<table style="margin-top:0px" width="100%" border="0" cellpadding="0px" cellspacing="0">
20<tr><td>
Ted Kremenek591b9072009-06-08 21:21:24 +0000[diff] [blame]21
Ted Kremenek831a46a2010-02-19 05:36:44 +0000[diff] [blame]22<h3>What is it?</h3>
23<p><b>scan-build</b> is a command line utility that enables a user to run the
24static analyzer over their codebase as part of performing a regular build (from
25the command line).</p>
26
27<h3>How does it work?</h3>
28<p>During a project build, as source files are compiled they are also analyzed
29in tandem by the static analyzer.</p>
30
31<p>Upon completion of the build, results are then presented to the user within a
32web browser.</p>
33
34<h3>Will it work with any build system?</h3>
35<p><b>scan-build</b> has little or no knowledge about how you build your code.
36It works by overriding the <tt>CC</tt> and <tt>CXX</tt> environment variables to
37(hopefully) change your build to use a &quot;fake&quot; compiler instead of the
38one that would normally build your project. By default, this fake compiler
39executes <tt>gcc</tt> to compile your code (assuming that <tt>gcc</tt> is your
40compiler) and then executes the static analyzer to analyze your code.</p>
41
42<p>This &quot;poor man's interposition&quot; works amazingly well in many cases
43and falls down in others. Please consult the information on this page on making
44the best use of <b>scan-build</b>, which includes getting it to work when the
45aforementioned hack fails to work.</p>
46
47</td>
48<td style="padding-left:10px">
49<center>
50 <img src="images/scan_build_cmd.png" width="450px" border=0><br>
51 <a href="images/analyzer_html.png"><img src="images/analyzer_html.png" width="450px" border=0></a>
52<br><b>Viewing static analyzer results in a web browser</b></center>
53</td></tr></table>
54
55<h2>Contents</h2>
Ted Kremenek591b9072009-06-08 21:21:24 +0000[diff] [blame]56
Ted Kremenek0f399962010-02-19 08:14:02 +0000[diff] [blame]57<ul id="collapsetree" class="dbtree onclick multiple">
58<li><a href="#scanbuild">Getting Started</a>
Ted Kremenek591b9072009-06-08 21:21:24 +0000[diff] [blame]59 <ul>
60 <li><a href="#scanbuild_basicusage">Basic Usage</a></li>
61 <li><a href="#scanbuild_otheroptions">Other Options</a></li>
62 <li><a href="#scanbuild_output">Output of scan-build</a></li>
63 </ul>
Ted Kremenek0f399962010-02-19 08:14:02 +0000[diff] [blame]64</li>
65<li><a href="#recommendedguidelines">Recommended Usage Guidelines</a>
Ted Kremenek591b9072009-06-08 21:21:24 +0000[diff] [blame]66 <ul>
67 <li><a href="#recommended_debug">Always Analyze a Project in its &quot;Debug&quot; Configuration</a></li>
68 <li><a href="#recommended_verbose">Use Verbose Output when Debugging scan-build</a></li>
69 <li><a href="#recommended_autoconf">Run './configure' through scan-build</a></li>
70 </ul>
Ted Kremenek0f399962010-02-19 08:14:02 +0000[diff] [blame]71</li>
72<li><a href="#iphone">Analyzing iPhone Projects</a></li>
Ted Kremenek591b9072009-06-08 21:21:24 +0000[diff] [blame]73</ul>
74
Ted Kremenek831a46a2010-02-19 05:36:44 +0000[diff] [blame]75<h2 id="scanbuild">Getting Started</h2>
Ted Kremenek591b9072009-06-08 21:21:24 +0000[diff] [blame]76
77<p>The <tt>scan-build</tt> command can be used to analyze an entire project by
78essentially interposing on a project's build process. This means that to run the
79analyzer using <tt>scan-build</tt>, you will use <tt>scan-build</tt> to analyze
80the source files compiled by <tt>gcc</tt> during a project build. This means
81that any files that are not compiled will also not be analyzed.</p>
82
83<h3 id="scanbuild_basicusage">Basic Usage</h3>
84
85<p>Basic usage of <tt>scan-build</tt> is designed to be simple: just place the
86word &quot;scan-build&quot; in front of your build command:</p>
87
88<pre class="code_example">
89$ <span class="code_highlight">scan-build</span> make
90$ <span class="code_highlight">scan-build</span> xcodebuild
91</pre>
92
93<p>In the first case <tt>scan-build</tt> analyzes the code of a project built
94with <tt>make</tt> and in the second case <tt>scan-build</tt> analyzes a project
95built using <tt>xcodebuild</tt>.<p>
96
97<p>Here is the general format for invoking <tt>scan-build</tt>:</p>
98
99<pre class="code_example">
100$ <span class="code_highlight">scan-build</span> <i>[scan-build options]</i> <span class="code_highlight">&lt;command&gt;</span> <i>[command options]</i>
101</pre>
102
Duncan Sands763f7d62010-01-20 12:40:56 +0000[diff] [blame]103<p>Operationally, <tt>scan-build</tt> literally runs &lt;command&gt; with all of the
Ted Kremenek591b9072009-06-08 21:21:24 +0000[diff] [blame]104subsequent options passed to it. For example, one can pass <nobr><tt>-j4</tt></nobr> to
105<tt>make</tt> get a parallel build over 4 cores:</p>
106
107<pre class="code_example">
108$ scan-build make <span class="code_highlight">-j4</span>
109</pre>
110
111<p>In almost all cases, <tt>scan-build</tt> makes no effort to interpret the
112options after the build command; it simply passes them through. In general,
113<tt>scan-build</tt> should support parallel builds, but <b>not distributed
114builds</b>.</p>
115
116<p>It is also possible to use <tt>scan-build</tt> to analyze specific
117files:</p>
118
119<pre class="code_example">
120 $ scan-build gcc -c <span class="code_highlight">t1.c t2.c</span>
121</pre>
122
123<p>This example causes the files <tt>t1.c</tt> and <tt>t2.c</tt> to be analyzed.
124</p>
125
126<h3 id="scanbuild_otheroptions">Other Options</h3>
127
128<p>As mentioned above, extra options can be passed to <tt>scan-build</tt>. These
129options prefix the build command. For example:</p>
130
131<pre class="code_example">
132 $ scan-build <span class="code_highlight">-k -V</span> make
133 $ scan-build <span class="code_highlight">-k -V</span> xcodebuild
134</pre>
135
136<p>Here is a subset of useful options:</p>
137
Ted Kremenekc49d5d52010-02-09 23:32:46 +0000[diff] [blame]138<table class="options">
Ted Kremenek591b9072009-06-08 21:21:24 +0000[diff] [blame]139<thead><tr><td>Option</td><td>Description</td></tr></thead>
140
141<tr><td><b>-o</b></td><td>Target directory for HTML report files. Subdirectories
142will be created as needed to represent separate "runs" of the analyzer. If this
143option is not specified, a directory is created in <tt>/tmp</tt> to store the
144reports.</td><tr>
145
146<tr><td><b>-h</b><br><i><nobr>(or no arguments)</nobr></i></td><td>Display all
147<tt>scan-build</tt> options.</td></tr>
148
149<tr><td><b>-k</b><br><nobr><b>--keep-going</b></nobr></td><td>Add a "keep on
150going" option to the specified build command. <p>This option currently supports
151<tt>make</tt> and <tt>xcodebuild</tt>.</p> <p>This is a convenience option; one
152can specify this behavior directly using build options.</p></td></tr>
153
154<tr><td><b>-v<b></td><td>Verbose output from scan-build and the analyzer. <b>A
155second and third "-v" increases verbosity</b>, and is useful for filing bug
156reports against the analyzer.</td></tr>
157
158<tr><td><b>-V</b></td><td>View analysis results in a web browser when the build
159command completes.</td></tr> </table>
160
161<p>A complete list of options can be obtained by running <tt>scan-build</tt>
162with no arguments.</p>
163
164<h3 id="scanbuild_output">Output of scan-build</h3>
165
166<p>
167The output of scan-build is a set of HTML files, each one which represents a
168separate bug report. A single <tt>index.html</tt> file is generated for
169surveying all of the bugs. You can then just open <tt>index.html</tt> in a web
170browser to view the bug reports.
171</p>
172
173<p>
174Where the HTML files are generated is specified with a <b>-o</b> option to
175<tt>scan-build</tt>. If <b>-o</b> isn't specified, a directory in <tt>/tmp</tt>
176is created to store the files (<tt>scan-build</tt> will print a message telling
177you where they are). If you want to view the reports immediately after the build
178completes, pass <b>-V</b> to <tt>scan-build</tt>.
179</p>
180
181
182<h2 id="recommendedguidelines">Recommended Usage Guidelines</h2>
183
184<p>This section describes a few recommendations with running the analyzer.</p>
185
Ted Kremenek831a46a2010-02-19 05:36:44 +0000[diff] [blame]186<h3 id="recommended_debug">ALWAYS analyze a project in its &quot;debug&quot; configuration</h3>
Ted Kremenek591b9072009-06-08 21:21:24 +0000[diff] [blame]187
188<p>Most projects can be built in a &quot;debug&quot; mode that enables assertions.
189Assertions are picked up by the static analyzer to prune infeasible paths, which
190in some cases can greatly reduce the number of false positives (bogus error
191reports) emitted by the tool.</p>
192
Ted Kremenek831a46a2010-02-19 05:36:44 +0000[diff] [blame]193<h3 id="recommend_verbose">Use verbose output when debugging scan-build</h3>
Ted Kremenek591b9072009-06-08 21:21:24 +0000[diff] [blame]194
195<p><tt>scan-build</tt> takes a <b>-v</b> option to emit verbose output about
196what it's doing; two <b>-v</b> options emit more information. Redirecting the
197output of <tt>scan-build</tt> to a text file (make sure to redirect standard
198error) is useful for filing bug reports against <tt>scan-build</tt> or the
199analyzer, as we can see the exact options (and files) passed to the analyzer.
200For more comprehensible logs, don't perform a parallel build.</p>
201
202<h3 id="recommended_autoconf">Run './configure' through scan-build</h3>
203
204<p>If an analyzed project uses an autoconf generated <tt>configure</tt> script,
205you will probably need to run <tt>configure</tt> script through
206<tt>scan-build</tt> in order to analyze the project.</p>
207
208<p><b>Example</b></p>
209
210<pre class="code_example">
211$ scan-build ./configure
212$ scan-build make
213</pre>
214
215<p>The reason <tt>configure</tt> also needs to be run through
216<tt>scan-build</tt> is because <tt>scan-build</tt> scans your source files by
217<i>interposing</i> on the compiler. This interposition is currently done by
218<tt>scan-build</tt> temporarily setting the environment variable <tt>CC</tt> to
219<tt>ccc-analyzer</tt>. The program <tt>ccc-analyzer</tt> acts like a fake
220compiler, forwarding its command line arguments over to <tt>gcc</tt> to perform
221regular compilation and <tt>clang</tt> to perform static analysis.</p>
222
223<p>Running <tt>configure</tt> typically generates makefiles that have hardwired
224paths to the compiler, and by running <tt>configure</tt> through
225<tt>scan-build</tt> that path is set to <tt>ccc-analyzer</tt>.</p.>
226
227<!--
228<h2 id="Debugging">Debugging the Analyzer</h2>
229
230<p>This section provides information on debugging the analyzer, and troubleshooting
231it when you have problems analyzing a particular project.</p>
232
233<h3>How it Works</h3>
234
235<p>To analyze a project, <tt>scan-build</tt> simply sets the environment variable
236<tt>CC</tt> to the full path to <tt>ccc-analyzer</tt>. It also sets a few other
237environment variables to communicate to <tt>ccc-analyzer</tt> where to dump HTML
238report files.</p>
239
240<p>Some Makefiles (or equivalent project files) hardcode the compiler; for such
241projects simply overriding <tt>CC</tt> won't cause <tt>ccc-analyzer</tt> to be
242called. This will cause the compiled code <b>to not be analyzed.</b></p> If you
243find that your code isn't being analyzed, check to see if <tt>CC</tt> is
244hardcoded. If this is the case, you can hardcode it instead to the <b>full
245path</b> to <tt>ccc-analyzer</tt>.</p>
246
247<p>When applicable, you can also run <tt>./configure</tt> for a project through
248<tt>scan-build</tt> so that configure sets up the location of <tt>CC</tt> based
249on the environment passed in from <tt>scan-build</tt>:
250
251<pre>
252 $ scan-build <b>./configure</b>
253</pre>
254
255<p><tt>scan-build</tt> has special knowledge about <tt>configure</tt>, so it in
256most cases will not actually analyze the configure tests run by
257<tt>configure</tt>.</p>
258
259<p>Under the hood, <tt>ccc-analyzer</tt> directly invokes <tt>gcc</tt> to
260compile the actual code in addition to running the analyzer (which occurs by it
261calling <tt>clang</tt>). <tt>ccc-analyzer</tt> tries to correctly forward all
262the arguments over to <tt>gcc</tt>, but this may not work perfectly (please
263report bugs of this kind).
264 -->
265
Ted Kremenek0f399962010-02-19 08:14:02 +0000[diff] [blame]266<h2 id="iphone">Analyzing iPhone Projects</h2>
267
268<p>Conceptually Xcode projects for iPhone applications are nearly the same as
269their cousins for desktop applications. <b>scan-build</b> can analyze these
270projects as well, but users often encounter problems with just building their
271iPhone projects from the command line because there are a few extra preparative
272steps they need to take (e.g., setup code signing).</p>
273
274<h3>Recommendation: use &quot;Build and Analyze&quot;</h3>
275
276<p>The absolute easiest way to analyze iPhone projects is to use the <a
277href="http://developer.apple.com/mac/library/featuredarticles/StaticAnalysis/index.html"><i>Build
278and Analyze</i> feature in Xcode 3.2</a> (which is based on the Clang Static
279Analyzer). There a user can analyze their project with the click of a button
280without most of the setup described later.</p>
281
Ted Kremenek7d539a42010-02-19 08:19:14 +0000[diff] [blame]282<p><a href="/xcode.html">Instructions are available</a> on this
Ted Kremenek0f399962010-02-19 08:14:02 +0000[diff] [blame]283website on how to use open source builds of the analyzer as a replacement for
284the one bundled with Xcode.</p>
285
286<h3>Using scan-build directly</h3>
287
288<p>If you wish to use <b>scan-build</b> with your iPhone project, keep the
289following things in mind:</p>
290
291<ul>
292 <li>Analyze your project in the <tt>Debug</tt> configuration, either by setting
293this as your configuration with Xcode or by passing <tt>-configuration
294Debug</tt> to <tt>xcodebuild</tt>.</li>
295 <li>Analyze your project using the <tt>Simulator</tt> as your base SDK. It is
296possible to analyze your code when targetting the device, but this is much
297easier to do when using Xcode's <i>Build and Analyze</i> feature.</li>
298 <li>Check that your code signing SDK is set to the simulator SDK as well, and make sure this option is set to <tt>Don't Code Sign</tt>.</li>
299</ul>
300
301<p>Note that you can most of this without actually modifying your project. For
302example, if your application targets iPhoneOS 2.2, you could run
303<b>scan-build</b> in the following manner from the command line:</p>
304
305<pre class="code_example">
306$ scan-build xcodebuild -configuration Debug -sdk iphonesimulator2.2
307</pre>
308
309Alternatively, if your application targets iPhoneOS 3.0:
310
311<pre class="code_example">
312$ scan-build xcodebuild -configuration Debug -sdk iphonesimulator3.0
313</pre>
314
315<h3>Gotcha: using the right compiler</h3>
316
317<p>Recall that <b>scan-build</b> analyzes your project by using <tt>gcc</tt> to
318compile the project and <tt>clang</tt> to analyze your project. When analyzing
319iPhone projects, <b>scan-build</b> may pick the wrong compiler than the one
320Xcode would use to build your project. This is because multiple versions of
321<tt>gcc</tt> may be installed on your system, especially if you are developing
322for the iPhone.</p>
323
324<p>Where this particularly might be a problem is if you are using Mac OS 10.5
325(Leopard) to develop for iPhone OS 3.0. The default desktop compiler on Leopard
326is gcc-4.0, while the compiler for iPhone OS 3.0 is gcc-4.2. When compiling your
327application to run on the simulator, it is important that <b>scan-build</b>
328finds the correct version of <tt>gcc</tt>. Otherwise, you may see strange build
329errors that only happen when you run <tt>scan-build</tt>.
330
331<p><b>scan-build</b> provides the <tt>--use-cc</tt> and <tt>--use-c++</tt>
332options to hardwire which compiler scan-build should use for building your code.
333Note that although you are chiefly interested in analyzing your project, keep in
334mind that running the analyzer is intimately tied to the build, and not being
335able to compile your code means it won't get fully analyzed (if at all).</p>
336
337<p>If you aren't certain which compiler Xcode uses to build your project, try
338just running <tt>xcodebuild</tt> (without <b>scan-build</b>). You should see the
339full path to the compiler that Xcode is using, and use that as an argument to
340<tt>--use-cc</tt>.</p>
341
Ted Kremenek591b9072009-06-08 21:21:24 +0000[diff] [blame]342</div>
Ted Kremenek8bebc6e2010-02-09 23:05:59 +0000[diff] [blame]343</div>
Ted Kremenek591b9072009-06-08 21:21:24 +0000[diff] [blame]344</body>
345</html>
346