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