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