www/analyzer/scan-build.html

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