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