Gitiles
Code Review Sign In
gerrit-public.fairphone.software / fp2-dev / platform / external / clang / c415901e14b7dde67ad0530f290ce4baee476d0c / . / www / analyzer / scan-build.html
blob: d89ed9ebe2dad703d4ab746240037f27c4694156 [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>
5 <title>Running the Analyzer</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 #cccccc;
14 border-bottom: 2px solid #cccccc;
15 font-weight: bold; font-family: Verdana
16 }
17 table { border: 1px #cccccc solid }
18 table { border-collapse: collapse; border-spacing: 0px }
19 table { margin-left:0px; margin-top:20px; margin-bottom:20px }
20 td { border-bottom: 1px #cccccc 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>Running the Analyzer</h1>
33
34<p>While the static analyzer engine can be used as a library, many users will
Ted Kremenekc4159012009-06-24 19:12:07 +0000[diff] [blame^]35likely use the command-line interface to the analyzer to analyze projects. This
36page documents <tt>scan-build<tt/>, a program that users can use from the
37command line to analyze all the source files used to build a project.</p>
Ted Kremenek591b9072009-06-08 21:21:24 +0000[diff] [blame]38
39<h3>Contents</h3>
40
41<ul>
42<li><a href="#scanbuild">scan-build</a></li>
43 <ul>
44 <li><a href="#scanbuild_basicusage">Basic Usage</a></li>
45 <li><a href="#scanbuild_otheroptions">Other Options</a></li>
46 <li><a href="#scanbuild_output">Output of scan-build</a></li>
47 </ul>
48<li><a href="#recommendedguidelines">Recommended Usage Guidelines</a></li>
49 <ul>
50 <li><a href="#recommended_debug">Always Analyze a Project in its &quot;Debug&quot; Configuration</a></li>
51 <li><a href="#recommended_verbose">Use Verbose Output when Debugging scan-build</a></li>
52 <li><a href="#recommended_autoconf">Run './configure' through scan-build</a></li>
53 </ul>
54</ul>
55
56<h2 id="scanbuild">scan-build</h2>
57
58<p>The <tt>scan-build</tt> command can be used to analyze an entire project by
59essentially interposing on a project's build process. This means that to run the
60analyzer using <tt>scan-build</tt>, you will use <tt>scan-build</tt> to analyze
61the source files compiled by <tt>gcc</tt> during a project build. This means
62that any files that are not compiled will also not be analyzed.</p>
63
64<h3 id="scanbuild_basicusage">Basic Usage</h3>
65
66<p>Basic usage of <tt>scan-build</tt> is designed to be simple: just place the
67word &quot;scan-build&quot; in front of your build command:</p>
68
69<pre class="code_example">
70$ <span class="code_highlight">scan-build</span> make
71$ <span class="code_highlight">scan-build</span> xcodebuild
72</pre>
73
74<p>In the first case <tt>scan-build</tt> analyzes the code of a project built
75with <tt>make</tt> and in the second case <tt>scan-build</tt> analyzes a project
76built using <tt>xcodebuild</tt>.<p>
77
78<p>Here is the general format for invoking <tt>scan-build</tt>:</p>
79
80<pre class="code_example">
81$ <span class="code_highlight">scan-build</span> <i>[scan-build options]</i> <span class="code_highlight">&lt;command&gt;</span> <i>[command options]</i>
82</pre>
83
84<p>Operationally, <tt>scan-build</tt> literally runs <command> with all of the
85subsequent options passed to it. For example, one can pass <nobr><tt>-j4</tt></nobr> to
86<tt>make</tt> get a parallel build over 4 cores:</p>
87
88<pre class="code_example">
89$ scan-build make <span class="code_highlight">-j4</span>
90</pre>
91
92<p>In almost all cases, <tt>scan-build</tt> makes no effort to interpret the
93options after the build command; it simply passes them through. In general,
94<tt>scan-build</tt> should support parallel builds, but <b>not distributed
95builds</b>.</p>
96
97<p>It is also possible to use <tt>scan-build</tt> to analyze specific
98files:</p>
99
100<pre class="code_example">
101 $ scan-build gcc -c <span class="code_highlight">t1.c t2.c</span>
102</pre>
103
104<p>This example causes the files <tt>t1.c</tt> and <tt>t2.c</tt> to be analyzed.
105</p>
106
107<h3 id="scanbuild_otheroptions">Other Options</h3>
108
109<p>As mentioned above, extra options can be passed to <tt>scan-build</tt>. These
110options prefix the build command. For example:</p>
111
112<pre class="code_example">
113 $ scan-build <span class="code_highlight">-k -V</span> make
114 $ scan-build <span class="code_highlight">-k -V</span> xcodebuild
115</pre>
116
117<p>Here is a subset of useful options:</p>
118
119<table>
120<thead><tr><td>Option</td><td>Description</td></tr></thead>
121
122<tr><td><b>-o</b></td><td>Target directory for HTML report files. Subdirectories
123will be created as needed to represent separate "runs" of the analyzer. If this
124option is not specified, a directory is created in <tt>/tmp</tt> to store the
125reports.</td><tr>
126
127<tr><td><b>-h</b><br><i><nobr>(or no arguments)</nobr></i></td><td>Display all
128<tt>scan-build</tt> options.</td></tr>
129
130<tr><td><b>-k</b><br><nobr><b>--keep-going</b></nobr></td><td>Add a "keep on
131going" option to the specified build command. <p>This option currently supports
132<tt>make</tt> and <tt>xcodebuild</tt>.</p> <p>This is a convenience option; one
133can specify this behavior directly using build options.</p></td></tr>
134
135<tr><td><b>-v<b></td><td>Verbose output from scan-build and the analyzer. <b>A
136second and third "-v" increases verbosity</b>, and is useful for filing bug
137reports against the analyzer.</td></tr>
138
139<tr><td><b>-V</b></td><td>View analysis results in a web browser when the build
140command completes.</td></tr> </table>
141
142<p>A complete list of options can be obtained by running <tt>scan-build</tt>
143with no arguments.</p>
144
145<h3 id="scanbuild_output">Output of scan-build</h3>
146
147<p>
148The output of scan-build is a set of HTML files, each one which represents a
149separate bug report. A single <tt>index.html</tt> file is generated for
150surveying all of the bugs. You can then just open <tt>index.html</tt> in a web
151browser to view the bug reports.
152</p>
153
154<p>
155Where the HTML files are generated is specified with a <b>-o</b> option to
156<tt>scan-build</tt>. If <b>-o</b> isn't specified, a directory in <tt>/tmp</tt>
157is created to store the files (<tt>scan-build</tt> will print a message telling
158you where they are). If you want to view the reports immediately after the build
159completes, pass <b>-V</b> to <tt>scan-build</tt>.
160</p>
161
162
163<h2 id="recommendedguidelines">Recommended Usage Guidelines</h2>
164
165<p>This section describes a few recommendations with running the analyzer.</p>
166
167<h3 id="recommended_debug">Always Analyze a Project in its &quot;Debug&quot; Configuration</h3>
168
169<p>Most projects can be built in a &quot;debug&quot; mode that enables assertions.
170Assertions are picked up by the static analyzer to prune infeasible paths, which
171in some cases can greatly reduce the number of false positives (bogus error
172reports) emitted by the tool.</p>
173
174<h3 id="recommend_verbose">Use Verbose Output when Debugging scan-build</h3>
175
176<p><tt>scan-build</tt> takes a <b>-v</b> option to emit verbose output about
177what it's doing; two <b>-v</b> options emit more information. Redirecting the
178output of <tt>scan-build</tt> to a text file (make sure to redirect standard
179error) is useful for filing bug reports against <tt>scan-build</tt> or the
180analyzer, as we can see the exact options (and files) passed to the analyzer.
181For more comprehensible logs, don't perform a parallel build.</p>
182
183<h3 id="recommended_autoconf">Run './configure' through scan-build</h3>
184
185<p>If an analyzed project uses an autoconf generated <tt>configure</tt> script,
186you will probably need to run <tt>configure</tt> script through
187<tt>scan-build</tt> in order to analyze the project.</p>
188
189<p><b>Example</b></p>
190
191<pre class="code_example">
192$ scan-build ./configure
193$ scan-build make
194</pre>
195
196<p>The reason <tt>configure</tt> also needs to be run through
197<tt>scan-build</tt> is because <tt>scan-build</tt> scans your source files by
198<i>interposing</i> on the compiler. This interposition is currently done by
199<tt>scan-build</tt> temporarily setting the environment variable <tt>CC</tt> to
200<tt>ccc-analyzer</tt>. The program <tt>ccc-analyzer</tt> acts like a fake
201compiler, forwarding its command line arguments over to <tt>gcc</tt> to perform
202regular compilation and <tt>clang</tt> to perform static analysis.</p>
203
204<p>Running <tt>configure</tt> typically generates makefiles that have hardwired
205paths to the compiler, and by running <tt>configure</tt> through
206<tt>scan-build</tt> that path is set to <tt>ccc-analyzer</tt>.</p.>
207
208<!--
209<h2 id="Debugging">Debugging the Analyzer</h2>
210
211<p>This section provides information on debugging the analyzer, and troubleshooting
212it when you have problems analyzing a particular project.</p>
213
214<h3>How it Works</h3>
215
216<p>To analyze a project, <tt>scan-build</tt> simply sets the environment variable
217<tt>CC</tt> to the full path to <tt>ccc-analyzer</tt>. It also sets a few other
218environment variables to communicate to <tt>ccc-analyzer</tt> where to dump HTML
219report files.</p>
220
221<p>Some Makefiles (or equivalent project files) hardcode the compiler; for such
222projects simply overriding <tt>CC</tt> won't cause <tt>ccc-analyzer</tt> to be
223called. This will cause the compiled code <b>to not be analyzed.</b></p> If you
224find that your code isn't being analyzed, check to see if <tt>CC</tt> is
225hardcoded. If this is the case, you can hardcode it instead to the <b>full
226path</b> to <tt>ccc-analyzer</tt>.</p>
227
228<p>When applicable, you can also run <tt>./configure</tt> for a project through
229<tt>scan-build</tt> so that configure sets up the location of <tt>CC</tt> based
230on the environment passed in from <tt>scan-build</tt>:
231
232<pre>
233 $ scan-build <b>./configure</b>
234</pre>
235
236<p><tt>scan-build</tt> has special knowledge about <tt>configure</tt>, so it in
237most cases will not actually analyze the configure tests run by
238<tt>configure</tt>.</p>
239
240<p>Under the hood, <tt>ccc-analyzer</tt> directly invokes <tt>gcc</tt> to
241compile the actual code in addition to running the analyzer (which occurs by it
242calling <tt>clang</tt>). <tt>ccc-analyzer</tt> tries to correctly forward all
243the arguments over to <tt>gcc</tt>, but this may not work perfectly (please
244report bugs of this kind).
245 -->
246
247</div>
248</body>
249</html>
250