| 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>scan-build: running the analyzer from the command line</title> |
| 6 |
<link type="text/css" rel="stylesheet" href="content.css"> |
| 7 |
<link type="text/css" rel="stylesheet" href="menu.css"> |
| 8 |
<script type="text/javascript" src="scripts/menu.js"></script> |
| 9 |
</head> |
| 10 |
<body> |
| 11 |
|
| 12 |
<div id="page"> |
| 13 |
<!--#include virtual="menu.html.incl"--> |
| 14 |
<div id="content"> |
| 15 |
|
| 16 |
<h1>scan-build: running the analyzer from the command line</h1> |
| 17 |
|
| 18 |
<table style="margin-top:0px" width="100%" cellpadding="0px" cellspacing="0"> |
| 19 |
<tr><td> |
| 20 |
|
| 21 |
<h3>What is it?</h3> |
| 22 |
<p><b>scan-build</b> is a command line utility that enables a user to run the |
| 23 |
static analyzer over their codebase as part of performing a regular build (from |
| 24 |
the command line).</p> |
| 25 |
|
| 26 |
<h3>How does it work?</h3> |
| 27 |
<p>During a project build, as source files are compiled they are also analyzed |
| 28 |
in tandem by the static analyzer.</p> |
| 29 |
|
| 30 |
<p>Upon completion of the build, results are then presented to the user within a |
| 31 |
web browser.</p> |
| 32 |
|
| 33 |
<h3>Will it work with any build system?</h3> |
| 34 |
<p><b>scan-build</b> has little or no knowledge about how you build your code. |
| 35 |
It works by overriding the <tt>CC</tt> and <tt>CXX</tt> environment variables to |
| 36 |
(hopefully) change your build to use a "fake" compiler instead of the |
| 37 |
one that would normally build your project. This fake compiler executes either |
| 38 |
<tt>clang</tt> or <tt>gcc</tt> (depending on the platform) to compile your |
| 39 |
code and then executes the static analyzer to analyze your code.</p> |
| 40 |
|
| 41 |
<p>This "poor man's interposition" works amazingly well in many cases |
| 42 |
and falls down in others. Please consult the information on this page on making |
| 43 |
the best use of <b>scan-build</b>, which includes getting it to work when the |
| 44 |
aforementioned hack fails to work.</p> |
| 45 |
|
| 46 |
</td> |
| 47 |
<td style="padding-left:10px; text-align:center"> |
| 48 |
<img src="images/scan_build_cmd.png" width="450px" alt="scan-build"><br> |
| 49 |
<a href="images/analyzer_html.png"><img src="images/analyzer_html.png" width="450px" alt="analyzer in browser"></a> |
| 50 |
<br><b>Viewing static analyzer results in a web browser</b> |
| 51 |
</td></tr></table> |
| 52 |
|
| 53 |
<h2>Contents</h2> |
| 54 |
|
| 55 |
<ul> |
| 56 |
<li><a href="#scanbuild">Getting Started</a> |
| 57 |
<ul> |
| 58 |
<li><a href="#scanbuild_basicusage">Basic Usage</a></li> |
| 59 |
<li><a href="#scanbuild_forwindowsusers">For Windows Users</a></li> |
| 60 |
<li><a href="#scanbuild_otheroptions">Other Options</a></li> |
| 61 |
<li><a href="#scanbuild_output">Output of scan-build</a></li> |
| 62 |
</ul> |
| 63 |
</li> |
| 64 |
<li><a href="#recommendedguidelines">Recommended Usage Guidelines</a> |
| 65 |
<ul> |
| 66 |
<li><a href="#recommended_debug">Always Analyze a Project in its "Debug" Configuration</a></li> |
| 67 |
<li><a href="#recommended_verbose">Use Verbose Output when Debugging scan-build</a></li> |
| 68 |
<li><a href="#recommended_autoconf">Run './configure' through scan-build</a></li> |
| 69 |
</ul> |
| 70 |
</li> |
| 71 |
<li><a href="#iphone">Analyzing iPhone Projects</a></li> |
| 72 |
</ul> |
| 73 |
|
| 74 |
<h2 id="scanbuild">Getting Started</h2> |
| 75 |
|
| 76 |
<p>The <tt>scan-build</tt> command can be used to analyze an entire project by |
| 77 |
essentially interposing on a project's build process. This means that to run the |
| 78 |
analyzer using <tt>scan-build</tt>, you will use <tt>scan-build</tt> to analyze |
| 79 |
the source files compiled by <tt>gcc</tt>/<tt>clang</tt> during a project build. |
| 80 |
This means that any files that are not compiled will also not be analyzed.</p> |
| 81 |
|
| 82 |
<h3 id="scanbuild_basicusage">Basic Usage</h3> |
| 83 |
|
| 84 |
<p>Basic usage of <tt>scan-build</tt> is designed to be simple: just place the |
| 85 |
word "scan-build" in front of your build command:</p> |
| 86 |
|
| 87 |
<pre class="code_example"> |
| 88 |
$ <span class="code_highlight">scan-build</span> make |
| 89 |
$ <span class="code_highlight">scan-build</span> xcodebuild |
| 90 |
</pre> |
| 91 |
|
| 92 |
<p>In the first case <tt>scan-build</tt> analyzes the code of a project built |
| 93 |
with <tt>make</tt> and in the second case <tt>scan-build</tt> analyzes a project |
| 94 |
built using <tt>xcodebuild</tt>.<p> |
| 95 |
|
| 96 |
<p>Here is the general format for invoking <tt>scan-build</tt>:</p> |
| 97 |
|
| 98 |
<pre class="code_example"> |
| 99 |
$ <span class="code_highlight">scan-build</span> <i>[scan-build options]</i> <span class="code_highlight"><command></span> <i>[command options]</i> |
| 100 |
</pre> |
| 101 |
|
| 102 |
<p>Operationally, <tt>scan-build</tt> literally runs <command> with all of the |
| 103 |
subsequent options passed to it. For example, one can pass <tt>-j4</tt> to |
| 104 |
<tt>make</tt> get a parallel build over 4 cores:</p> |
| 105 |
|
| 106 |
<pre class="code_example"> |
| 107 |
$ scan-build make <span class="code_highlight">-j4</span> |
| 108 |
</pre> |
| 109 |
|
| 110 |
<p>In almost all cases, <tt>scan-build</tt> makes no effort to interpret the |
| 111 |
options after the build command; it simply passes them through. In general, |
| 112 |
<tt>scan-build</tt> should support parallel builds, but <b>not distributed |
| 113 |
builds</b>.</p> |
| 114 |
|
| 115 |
<p>It is also possible to use <tt>scan-build</tt> to analyze specific |
| 116 |
files:</p> |
| 117 |
|
| 118 |
<pre class="code_example"> |
| 119 |
$ scan-build gcc -c <span class="code_highlight">t1.c t2.c</span> |
| 120 |
</pre> |
| 121 |
|
| 122 |
<p>This example causes the files <tt>t1.c</tt> and <tt>t2.c</tt> to be analyzed. |
| 123 |
</p> |
| 124 |
|
| 125 |
<h3 id="scanbuild_forwindowsusers">For Windows Users</h3> |
| 126 |
|
| 127 |
<p>Windows users must have Perl installed to use scan-build.</p> |
| 128 |
|
| 129 |
<p><tt>scan-build.bat</tt> script allows you to launch scan-build in the same |
| 130 |
way as it described in the Basic Usage section above. To invoke scan-build from |
| 131 |
an arbitrary location, add the path to the folder containing scan-build.bat to |
| 132 |
your PATH environment variable.</p> |
| 133 |
|
| 134 |
<p>If you have unexpected compilation/make problems when running scan-build |
| 135 |
with MinGW/MSYS the following information may be helpful:</p> |
| 136 |
|
| 137 |
<ul> |
| 138 |
<li> If getting unexpected <tt>"fatal error: no input files"</tt> while |
| 139 |
building with MSYS make from the Windows cmd, try one of these solutions:</li> |
| 140 |
<ul> |
| 141 |
<li> Use MinGW <tt>mingw32-make</tt> instead of MSYS <tt>make</tt> and |
| 142 |
exclude the path to MSYS from PATH to prevent <tt>mingw32-make</tt> from using |
| 143 |
MSYS utils. MSYS utils are dependent on the MSYS runtime and they are not |
| 144 |
intended for being run from the Windows cmd. Specifically, makefile commands |
| 145 |
with backslashed quotes may be heavily corrupted when passed for execution.</li> |
| 146 |
<li> Run <tt>make</tt> from the sh shell: |
| 147 |
<pre class="code_example"> |
| 148 |
$ <span class="code_highlight">scan-build</span> <i>[scan-build options]</i> sh -c "make <i>[make options]</i>" |
| 149 |
</pre></li> |
| 150 |
</ul> |
| 151 |
<li> If getting <tt>"Error : *** target pattern contains no `%'"</tt> while |
| 152 |
using GNU Make 3.81, try to use another version of make.</li> |
| 153 |
</ul> |
| 154 |
|
| 155 |
<h3 id="scanbuild_otheroptions">Other Options</h3> |
| 156 |
|
| 157 |
<p>As mentioned above, extra options can be passed to <tt>scan-build</tt>. These |
| 158 |
options prefix the build command. For example:</p> |
| 159 |
|
| 160 |
<pre class="code_example"> |
| 161 |
$ scan-build <span class="code_highlight">-k -V</span> make |
| 162 |
$ scan-build <span class="code_highlight">-k -V</span> xcodebuild |
| 163 |
</pre> |
| 164 |
|
| 165 |
<p>Here is a subset of useful options:</p> |
| 166 |
|
| 167 |
<table class="options"> |
| 168 |
<colgroup><col class="option"><col class="description"></colgroup> |
| 169 |
<thead><tr><td>Option</td><td>Description</td></tr></thead> |
| 170 |
|
| 171 |
<tr><td><b>-o</b></td><td>Target directory for HTML report files. Subdirectories |
| 172 |
will be created as needed to represent separate "runs" of the analyzer. If this |
| 173 |
option is not specified, a directory is created in <tt>/tmp</tt> to store the |
| 174 |
reports.</td></tr> |
| 175 |
|
| 176 |
<tr><td><b>-h</b><br><i>(or no arguments)</i></td><td>Display all |
| 177 |
<tt>scan-build</tt> options.</td></tr> |
| 178 |
|
| 179 |
<tr><td><b>-k</b><br><b>--keep-going</b></td><td>Add a "keep on |
| 180 |
going" option to the specified build command. <p>This option currently supports |
| 181 |
<tt>make</tt> and <tt>xcodebuild</tt>.</p> <p>This is a convenience option; one |
| 182 |
can specify this behavior directly using build options.</p></td></tr> |
| 183 |
|
| 184 |
<tr><td><b>-v</b></td><td>Verbose output from scan-build and the analyzer. <b>A |
| 185 |
second and third "-v" increases verbosity</b>, and is useful for filing bug |
| 186 |
reports against the analyzer.</td></tr> |
| 187 |
|
| 188 |
<tr><td><b>-V</b></td><td>View analysis results in a web browser when the build |
| 189 |
command completes.</td></tr> |
| 190 |
|
| 191 |
<tr><td><b>--use-analyzer Xcode</b><br><i>or</i><br> |
| 192 |
<b>--use-analyzer [path to clang]</b></td><td><tt>scan-build</tt> uses the |
| 193 |
'clang' executable relative to itself for static analysis. One can override this |
| 194 |
behavior with this option by using the 'clang' packaged with Xcode (on OS X) or |
| 195 |
from the PATH.</p></td></tr> </table> |
| 196 |
|
| 197 |
<p>A complete list of options can be obtained by running <tt>scan-build</tt> |
| 198 |
with no arguments.</p> |
| 199 |
|
| 200 |
<h3 id="scanbuild_output">Output of scan-build</h3> |
| 201 |
|
| 202 |
<p> |
| 203 |
The output of scan-build is a set of HTML files, each one which represents a |
| 204 |
separate bug report. A single <tt>index.html</tt> file is generated for |
| 205 |
surveying all of the bugs. You can then just open <tt>index.html</tt> in a web |
| 206 |
browser to view the bug reports. |
| 207 |
</p> |
| 208 |
|
| 209 |
<p> |
| 210 |
Where the HTML files are generated is specified with a <b>-o</b> option to |
| 211 |
<tt>scan-build</tt>. If <b>-o</b> isn't specified, a directory in <tt>/tmp</tt> |
| 212 |
is created to store the files (<tt>scan-build</tt> will print a message telling |
| 213 |
you where they are). If you want to view the reports immediately after the build |
| 214 |
completes, pass <b>-V</b> to <tt>scan-build</tt>. |
| 215 |
</p> |
| 216 |
|
| 217 |
|
| 218 |
<h2 id="recommendedguidelines">Recommended Usage Guidelines</h2> |
| 219 |
|
| 220 |
<p>This section describes a few recommendations with running the analyzer.</p> |
| 221 |
|
| 222 |
<h3 id="recommended_debug">ALWAYS analyze a project in its "debug" configuration</h3> |
| 223 |
|
| 224 |
<p>Most projects can be built in a "debug" mode that enables assertions. |
| 225 |
Assertions are picked up by the static analyzer to prune infeasible paths, which |
| 226 |
in some cases can greatly reduce the number of false positives (bogus error |
| 227 |
reports) emitted by the tool.</p> |
| 228 |
|
| 229 |
<p>Another option is to use <tt>--force-analyze-debug-code</tt> flag of |
| 230 |
<b>scan-build</b> tool which would enable assertions automatically.</p> |
| 231 |
|
| 232 |
<h3 id="recommend_verbose">Use verbose output when debugging scan-build</h3> |
| 233 |
|
| 234 |
<p><tt>scan-build</tt> takes a <b>-v</b> option to emit verbose output about |
| 235 |
what it's doing; two <b>-v</b> options emit more information. Redirecting the |
| 236 |
output of <tt>scan-build</tt> to a text file (make sure to redirect standard |
| 237 |
error) is useful for filing bug reports against <tt>scan-build</tt> or the |
| 238 |
analyzer, as we can see the exact options (and files) passed to the analyzer. |
| 239 |
For more comprehensible logs, don't perform a parallel build.</p> |
| 240 |
|
| 241 |
<h3 id="recommended_autoconf">Run './configure' through scan-build</h3> |
| 242 |
|
| 243 |
<p>If an analyzed project uses an autoconf generated <tt>configure</tt> script, |
| 244 |
you will probably need to run <tt>configure</tt> script through |
| 245 |
<tt>scan-build</tt> in order to analyze the project.</p> |
| 246 |
|
| 247 |
<p><b>Example</b></p> |
| 248 |
|
| 249 |
<pre class="code_example"> |
| 250 |
$ scan-build ./configure |
| 251 |
$ scan-build --keep-cc make |
| 252 |
</pre> |
| 253 |
|
| 254 |
<p>The reason <tt>configure</tt> also needs to be run through |
| 255 |
<tt>scan-build</tt> is because <tt>scan-build</tt> scans your source files by |
| 256 |
<i>interposing</i> on the compiler. This interposition is currently done by |
| 257 |
<tt>scan-build</tt> temporarily setting the environment variable <tt>CC</tt> to |
| 258 |
<tt>ccc-analyzer</tt>. The program <tt>ccc-analyzer</tt> acts like a fake |
| 259 |
compiler, forwarding its command line arguments over to the compiler to perform |
| 260 |
regular compilation and <tt>clang</tt> to perform static analysis.</p> |
| 261 |
|
| 262 |
<p>Running <tt>configure</tt> typically generates makefiles that have hardwired |
| 263 |
paths to the compiler, and by running <tt>configure</tt> through |
| 264 |
<tt>scan-build</tt> that path is set to <tt>ccc-analyzer</tt>.</p> |
| 265 |
|
| 266 |
<!-- |
| 267 |
<h2 id="Debugging">Debugging the Analyzer</h2> |
| 268 |
|
| 269 |
<p>This section provides information on debugging the analyzer, and troubleshooting |
| 270 |
it when you have problems analyzing a particular project.</p> |
| 271 |
|
| 272 |
<h3>How it Works</h3> |
| 273 |
|
| 274 |
<p>To analyze a project, <tt>scan-build</tt> simply sets the environment variable |
| 275 |
<tt>CC</tt> to the full path to <tt>ccc-analyzer</tt>. It also sets a few other |
| 276 |
environment variables to communicate to <tt>ccc-analyzer</tt> where to dump HTML |
| 277 |
report files.</p> |
| 278 |
|
| 279 |
<p>Some Makefiles (or equivalent project files) hardcode the compiler; for such |
| 280 |
projects simply overriding <tt>CC</tt> won't cause <tt>ccc-analyzer</tt> to be |
| 281 |
called. This will cause the compiled code <b>to not be analyzed.</b></p> If you |
| 282 |
find that your code isn't being analyzed, check to see if <tt>CC</tt> is |
| 283 |
hardcoded. If this is the case, you can hardcode it instead to the <b>full |
| 284 |
path</b> to <tt>ccc-analyzer</tt>.</p> |
| 285 |
|
| 286 |
<p>When applicable, you can also run <tt>./configure</tt> for a project through |
| 287 |
<tt>scan-build</tt> so that configure sets up the location of <tt>CC</tt> based |
| 288 |
on the environment passed in from <tt>scan-build</tt>: |
| 289 |
|
| 290 |
<pre> |
| 291 |
$ scan-build <b>./configure</b> |
| 292 |
</pre> |
| 293 |
|
| 294 |
<p><tt>scan-build</tt> has special knowledge about <tt>configure</tt>, so it in |
| 295 |
most cases will not actually analyze the configure tests run by |
| 296 |
<tt>configure</tt>.</p> |
| 297 |
|
| 298 |
<p>Under the hood, <tt>ccc-analyzer</tt> directly invokes <tt>gcc</tt> to |
| 299 |
compile the actual code in addition to running the analyzer (which occurs by it |
| 300 |
calling <tt>clang</tt>). <tt>ccc-analyzer</tt> tries to correctly forward all |
| 301 |
the arguments over to <tt>gcc</tt>, but this may not work perfectly (please |
| 302 |
report bugs of this kind). |
| 303 |
--> |
| 304 |
|
| 305 |
<h2 id="iphone">Analyzing iPhone Projects</h2> |
| 306 |
|
| 307 |
<p>Conceptually Xcode projects for iPhone applications are nearly the same as |
| 308 |
their cousins for desktop applications. <b>scan-build</b> can analyze these |
| 309 |
projects as well, but users often encounter problems with just building their |
| 310 |
iPhone projects from the command line because there are a few extra preparative |
| 311 |
steps they need to take (e.g., setup code signing).</p> |
| 312 |
|
| 313 |
<h3>Recommendation: use "Build and Analyze"</h3> |
| 314 |
|
| 315 |
<p>The absolute easiest way to analyze iPhone projects is to use the |
| 316 |
<a href="https://developer.apple.com/library/ios/recipes/xcode_help-source_editor/chapters/Analyze.html#//apple_ref/doc/uid/TP40009975-CH4-SW1"><i>Analyze</i> |
| 317 |
feature in Xcode</a> (which is based on the Clang Static Analyzer). There a |
| 318 |
user can analyze their project right from a menu without most of the setup |
| 319 |
described later.</p> |
| 320 |
|
| 321 |
<p><a href="/xcode.html">Instructions are available</a> on this |
| 322 |
website on how to use open source builds of the analyzer as a replacement for |
| 323 |
the one bundled with Xcode.</p> |
| 324 |
|
| 325 |
<h3>Using scan-build directly</h3> |
| 326 |
|
| 327 |
<p>If you wish to use <b>scan-build</b> with your iPhone project, keep the |
| 328 |
following things in mind:</p> |
| 329 |
|
| 330 |
<ul> |
| 331 |
<li>Analyze your project in the <tt>Debug</tt> configuration, either by setting |
| 332 |
this as your configuration with Xcode or by passing <tt>-configuration |
| 333 |
Debug</tt> to <tt>xcodebuild</tt>.</li> |
| 334 |
<li>Analyze your project using the <tt>Simulator</tt> as your base SDK. It is |
| 335 |
possible to analyze your code when targeting the device, but this is much |
| 336 |
easier to do when using Xcode's <i>Build and Analyze</i> feature.</li> |
| 337 |
<li>Check that your code signing SDK is set to the simulator SDK as well, and make sure this option is set to <tt>Don't Code Sign</tt>.</li> |
| 338 |
</ul> |
| 339 |
|
| 340 |
<p>Note that you can most of this without actually modifying your project. For |
| 341 |
example, if your application targets iPhoneOS 2.2, you could run |
| 342 |
<b>scan-build</b> in the following manner from the command line:</p> |
| 343 |
|
| 344 |
<pre class="code_example"> |
| 345 |
$ scan-build xcodebuild -configuration Debug -sdk iphonesimulator2.2 |
| 346 |
</pre> |
| 347 |
|
| 348 |
Alternatively, if your application targets iPhoneOS 3.0: |
| 349 |
|
| 350 |
<pre class="code_example"> |
| 351 |
$ scan-build xcodebuild -configuration Debug -sdk iphonesimulator3.0 |
| 352 |
</pre> |
| 353 |
|
| 354 |
<h3>Gotcha: using the right compiler</h3> |
| 355 |
|
| 356 |
<p>Recall that <b>scan-build</b> analyzes your project by using a compiler to |
| 357 |
compile the project and <tt>clang</tt> to analyze your project. The script uses |
| 358 |
simple heuristics to determine which compiler should be used (it defaults to |
| 359 |
<tt>clang</tt> on Darwin and <tt>gcc</tt> on other platforms). When analyzing |
| 360 |
iPhone projects, <b>scan-build</b> may pick the wrong compiler than the one |
| 361 |
Xcode would use to build your project. For example, this could be because |
| 362 |
multiple versions of a compiler may be installed on your system, especially if |
| 363 |
you are developing for the iPhone.</p> |
| 364 |
|
| 365 |
<p>When compiling your application to run on the simulator, it is important that <b>scan-build</b> |
| 366 |
finds the correct version of <tt>gcc/clang</tt>. Otherwise, you may see strange build |
| 367 |
errors that only happen when you run <tt>scan-build</tt>. |
| 368 |
|
| 369 |
<p><b>scan-build</b> provides the <tt>--use-cc</tt> and <tt>--use-c++</tt> |
| 370 |
options to hardwire which compiler scan-build should use for building your code. |
| 371 |
Note that although you are chiefly interested in analyzing your project, keep in |
| 372 |
mind that running the analyzer is intimately tied to the build, and not being |
| 373 |
able to compile your code means it won't get fully analyzed (if at all).</p> |
| 374 |
|
| 375 |
<p>If you aren't certain which compiler Xcode uses to build your project, try |
| 376 |
just running <tt>xcodebuild</tt> (without <b>scan-build</b>). You should see the |
| 377 |
full path to the compiler that Xcode is using, and use that as an argument to |
| 378 |
<tt>--use-cc</tt>.</p> |
| 379 |
|
| 380 |
</div> |
| 381 |
</div> |
| 382 |
</body> |
| 383 |
</html> |