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