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