Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / clang / ba67f6aa95733aaa9d79c82a8802e67b84e5d8e5 / . / www / StaticAnalysisUsage.html
blob: daab89f724aa231eb674772ae3f9736ec9c07662 [file] [log] [blame]
Ted Kremenekcf2e3042008-06-19 23:14:24 +0000[diff] [blame]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd">
Ted Kremenek92c23cb2008-06-17 06:38:07 +0000[diff] [blame]3<html>
4<head>
5 <title>Information on using the Static Analyzer ("Clang Checker")</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 #000000;
14 border-bottom: 2px solid #000000;
15 font-weight: bold; font-family: Verdana
16 }
17 table { border: 1px #000000 solid }
18 table { border-collapse: collapse; border-spacing: 0px }
19 table { margin-left:20px; margin-top:20px; margin-bottom:20px }
20 td { border-bottom: 1px #000000 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>Information on using the Static Analyzer</h1>
33
34<h2 id="Obtaining">Obtaining the Analyzer</h2>
35
36<p> Using the analyzer involves executing <tt>scan-build</tt> (see <a
37href="#BasicUsage">Basic Usage</a>). <tt>scan-build</tt> will first look for a
38<tt>clang</tt> executable in the same directory as <tt>scan-build</tt>, and then
39search your path.</p>
40
41<p>If one is using the analyzer directly from the Clang sources, it suffices to
42just directly execute <tt>scan-build</tt> in the <tt>utils</tt> directory. No
43other special installation is needed.</p>
44
45<h3>Packaged Builds (Mac OS X)</h3>
46
47<p>Semi-regular pre-built binaries of the analyzer are available on Mac OS X
48(10.5).</p>
49
Ted Kremenek34239e92008-06-17 06:43:11 +0000[diff] [blame]50<p>The latest build is:
51 <!--#include virtual="latest_checker.html.incl"-->
Ted Kremenekcfcc2472008-07-15 03:49:15 +0000[diff] [blame]52</p>
Ted Kremenek92c23cb2008-06-17 06:38:07 +0000[diff] [blame]53
54Packaged builds for other platforms may eventually be provided, but as the tool
55is in its early stages we are not actively promoting releases yet. If you wish
56to help contribute regular builds of the analyzer on other platforms, please
57email the <a href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev">Clang
58Developers' mailing list</a>.</p>
59
60<p>Packaged builds of the analyzer expand to the following files:</p>
61
62<table id="package">
63<thead><tr><td>File</td><td>Purpose</td></tr></thead>
64<tr><td><tt><b>scan-build</b></tt></td><td>Script for running the analyzer over a project build. <b>This is the only file you care about.</b></td></tr>
65<tr><td><tt>ccc-analyzer</tt></td><td>GCC interceptor (called by scan-build)</td></tr>
66<tr><td><tt>clang</tt></td><td>Static Analyzer (called by ccc-analyzer)</td><tr>
67<tr><td><tt>sorttable.js</tt></td><td>JavaScript used for displaying error reports</td></tr>
68</table>
69
70<h3 id="OtherPlatforms">Other Platforms (Building the Analyzer from Source)</h3>
71
72<p>Packaged builds simply consist of a few files from the Clang source tree,
73meaning that <b>anyone</b> who can build Clang can use the static analyzer.
74Please see the <a href="get_started.html">Getting Started</a> page for more
75details on downloading and compiling Clang.</p>
76
77<p>All files used by the analyzer (and included in packaged builds; <a
78href="#package">see above</a>) other than a compiled <tt>clang</tt> executable
79are found in the <tt>utils</tt> subdirectory in the Clang tree.</p>
80
81<h2 id="BasicUsage">Basic Usage</h2>
82
83<p>The analyzer is executed from the command-line. To run the analyzer, you will
84use <tt>scan-build</tt> to analyze the source files compiled by <tt>gcc</tt>
85during a project build.</p>
86
87<p>For example, to analyze the files compiled under a build:</p>
88
89<pre>
90 $ <b>scan-build</b> make
91 $ <b>scan-build</b> xcodebuild
92</pre>
93
94<p> In the first case <tt>scan-build</tt> analyzes the code of a project built
Chris Lattnerd9069d12008-07-20 04:22:06 +0000[diff] [blame]95with <tt>make</tt>, and in the second case <tt>scan-build</tt> analyzes a project
Ted Kremenek92c23cb2008-06-17 06:38:07 +0000[diff] [blame]96built using <tt>xcodebuild</tt>. In general, the format is: </p>
97
98<pre>
99 $ <b>scan-build</b> <i>[scan-build options]</i> <b>&lt;command&gt;</b> <i>[command options]</i>
100</pre>
101
102<p> Operationally, <tt>scan-build</tt> literally runs <command> with all of the
Chris Lattnerd9069d12008-07-20 04:22:06 +0000[diff] [blame]103subsequent options passed to it. For example:</p>
Ted Kremenek92c23cb2008-06-17 06:38:07 +0000[diff] [blame]104
105<pre>
106 $ scan-build make <b>-j4</b>
107</pre>
108
109<p>In this example, <tt>scan-build</tt> makes no effort to interpret the options
110after the build command (in this case, <tt>make</tt>); it just passes them
111through. In general, <tt>scan-build</tt> should support parallel builds, but
112<b>not distributed builds</b>. Similarly, you can use <tt>scan-build</tt> to
113analyze specific files:
114
115<pre>
116 $ scan-build gcc -c <b>t1.c t2.c</b>
117</pre>
118
119<p>
120This example causes the files <tt>t1.c</tt> and <tt>t2.c</tt> to be analyzed.
121</p>
122
123<h3>Other Options</h3>
124
125<p>
126As mentioned above, extra options can be passed to <tt>scan-build</tt>. These
127options prefix the build command. For example:</p>
128
129<pre>
130 $ scan-build <b>-k -V</b> make
131 $ scan-build <b>-k -V</b> xcodebuild
132</pre>
133
Ted Kremenekb951d9d2008-07-26 05:21:44 +0000[diff] [blame]134<p>Here is a subset of useful options:</p>
Ted Kremenek92c23cb2008-06-17 06:38:07 +0000[diff] [blame]135
136<table>
137 <thead><tr><td>Option</td><td>Description</td></tr></thead>
138
Ted Kremenek92c23cb2008-06-17 06:38:07 +0000[diff] [blame]139 <tr><td><b>-o</b></td><td>Target directory for HTML report files. Subdirectories will be
140 created as needed to represent separate "runs" of the analyzer. If this option
141is not specified, a directory is created in <tt>/tmp</tt> to store the
142reports.</td><tr>
143
Ted Kremenekb951d9d2008-07-26 05:21:44 +0000[diff] [blame]144 <tr><td><b>-h</b><br><i><nobr>(or no arguments)</nobr></i></td><td>Display all <tt>scan-build</tt> options.</td></tr>
Ted Kremenek92c23cb2008-06-17 06:38:07 +0000[diff] [blame]145
146 <tr><td><b>-k</b><br><nobr><b>--keep-going</b></nobr></td><td>Add a "keep on going" option to the
147 specified build command. <p>This option currently supports <tt>make</tt> and
148 <tt>xcodebuild</tt>.</p> <p>This is a convenience option; one can specify this
149 behavior directly using build options.</p></td></tr>
150
151 <tr><td><b>-v<b></td><td>Verbose output from scan-build and the analyzer. <b>A second and third
152 "-v" increases verbosity</b>, and is useful for filing bug reports against the analyzer.</td></tr>
153
154 <tr><td><b>-V</b></td><td>View analysis results in a web browser when the build command completes.</td></tr>
155</table>
156
Ted Kremenek92c23cb2008-06-17 06:38:07 +0000[diff] [blame]157<h2 id="Output">Output of the Analyzer</h2>
158
159<p>
160The output of the analyzer is a set of HTML files, each one which represents a
161separate bug report. A single <tt>index.html</tt> file is generated for
162surveying all of the bugs. You can then just open <tt>index.html</tt> in a web
163browser to view the bug reports.
164</p>
165
166<p>
167Where the HTML files are generated is specified with a <b>-o</b> option to
168<tt>scan-build</tt>. If <b>-o</b> isn't specified, a directory in <tt>/tmp</tt>
169is created to store the files (<tt>scan-build</tt> will print a message telling
170you where they are). If you want to view the reports immediately after the build
171completes, pass <b>-V</b> to <tt>scan-build</tt>.
172</p>
173
174
175<h2 id="RecommendedUsageGuidelines">Recommended Usage Guidelines</h2>
176
177Here are a few recommendations with running the analyzer:
178
179<h3>Always Analyze a Project in its "Debug" Configuration</h3>
180
181<p>Most projects can be built in a "debug" mode that enables assertions.
182Assertions are picked up by the static analyzer to prune infeasible paths, which
183in some cases can greatly reduce the number of false positives (bogus error
184reports) emitted by the tool.</p>
185
186<h3>Pass -k to scan-build</h3>
187
188<p>While <tt>ccc-analyzer</tt> invokes <tt>gcc</tt> to compile code, any
189problems in correctly forwarding arguments to <tt>gcc</tt> may result in a build
190failure. Passing <b>-k</b> to <tt>scan-build</tt> potentially allows you to
191analyze other code in a project for which this problem doesn't occur.</p>
192
193<p> Also, it is useful to analyze a project even if not all of the source files
194are compilable. This is great when using <tt>scan-build</tt> as part of your
195compile-debug cycle.</p>
196
197<h3>Use Verbose Output when Debugging scan-build</h3>
198
199<p><tt>scan-build</tt> takes a <b>-v</b> option to emit verbose output about
200what it's doing; two <b>-v</b> options emit more information. Redirecting the
201output of <tt>scan-build</tt> to a text file (make sure to redirect standard
202error) is useful for filing bug reports against <tt>scan-build</tt> or the
203analyzer, as we can see the exact options (and files) passed to the analyzer.
Chris Lattnerd9069d12008-07-20 04:22:06 +0000[diff] [blame]204For more comprehensible logs, don't perform a parallel build.</p>
Ted Kremenek92c23cb2008-06-17 06:38:07 +0000[diff] [blame]205
206<h2 id="Debugging">Debugging the Analyzer</h2>
207
208<p>This section provides information on debugging the analyzer, and troubleshooting
209it when you have problems analyzing a particular project.</p>
210
211<h3>How it Works</h3>
212
213<p>To analyze a project, <tt>scan-build</tt> simply sets the environment variable
214<tt>CC</tt> to the full path to <tt>ccc-analyzer</tt>. It also sets a few other
215environment variables to communicate to <tt>ccc-analyzer</tt> where to dump HTML
216report files.</p>
217
218<p>Some Makefiles (or equivalent project files) hardcode the compiler; for such
219projects simply overriding <tt>CC</tt> won't cause <tt>ccc-analyzer</tt> to be
220called. This will cause the compiled code <b>to not be analyzed.</b></p> If you
221find that your code isn't being analyzed, check to see if <tt>CC</tt> is
222hardcoded. If this is the case, you can hardcode it instead to the <b>full
223path</b> to <tt>ccc-analyzer</tt>.</p>
224
225<p>When applicable, you can also run <tt>./configure</tt> for a project through
226<tt>scan-build</tt> so that configure sets up the location of <tt>CC</tt> based
227on the environment passed in from <tt>scan-build</tt>:
228
229<pre>
230 $ scan-build <b>./configure</b>
231</pre>
232
233<p><tt>scan-build</tt> has special knowledge about <tt>configure</tt>, so it in
234most cases will not actually analyze the configure tests run by
235<tt>configure</tt>.</p>
236
237<p>Under the hood, <tt>ccc-analyzer</tt> directly invokes <tt>gcc</tt> to
238compile the actual code in addition to running the analyzer (which occurs by it
239calling <tt>clang</tt>). <tt>ccc-analyzer</tt> tries to correctly forward all
240the arguments over to <tt>gcc</tt>, but this may not work perfectly (please
241report bugs of this kind).
242
Ted Kremenekf7946752008-07-08 21:25:35 +0000[diff] [blame]243<h2 id="filingbugs">Filing Bugs and Feature Requests</h2>
Ted Kremenek92c23cb2008-06-17 06:38:07 +0000[diff] [blame]244
Ted Kremenekf7946752008-07-08 21:25:35 +0000[diff] [blame]245<p>We encourage users to file bug reports for any problems that they encounter.
246We also welcome feature requests. When filing a bug report, please do the
247following:</p>
248
249<ul>
250
251<li>Include the checker build (for prebuilt Mac OS X binaries) or the SVN
252revision number.</li>
253
254<li>Provide a self-encapsulated, reduced test case that exhibits the issue
255 you are experiencing.</li>
256
257<li>Test cases don't tell us everything. Please briefly describe the problem you are seeing.</li>
258
259</ul>
Ted Kremenek92c23cb2008-06-17 06:38:07 +0000[diff] [blame]260
261<h3>Outside Apple</h3>
262
263<p>Please <a href="http://llvm.org/bugs/enter_bug.cgi?product=clang">file
Ted Kremeneka80e4482008-07-09 22:20:56 +0000[diff] [blame]264bugs</a> in LLVM's Bugzilla database against the Clang <b>Static Analyzer</b>
265component.</p>
Ted Kremenek92c23cb2008-06-17 06:38:07 +0000[diff] [blame]266
267<h3>Apple-internal Users</h3>
268
Ted Kremenek0ef77d42008-07-15 03:51:09 +0000[diff] [blame]269<p>Please file bugs in Radar against the <b>llvm - checker</b> component.</p>
Ted Kremenek92c23cb2008-06-17 06:38:07 +0000[diff] [blame]270
271</div>
272</body>
273</html>
274