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