src/llvm/tools/clang/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%" 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. This fake compiler executes either
  39 <tt>clang</tt> or <tt>gcc</tt> (depending on the platform) to compile your
  40 code 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; text-align:center">
  49   <img src="images/scan_build_cmd.png" width="450px" alt="scan-build"><br>
  50   <a href="images/analyzer_html.png"><img src="images/analyzer_html.png" width="450px" alt="analyzer in browser"></a>
  51 <br><b>Viewing static analyzer results in a web browser</b>
  52 </td></tr></table>
  53
  54 <h2>Contents</h2>
  55
  56 <ul id="collapsetree" class="dbtree onclick multiple">
  57 <li><a href="#scanbuild">Getting Started</a>
  58  <ul>
  59   <li><a href="#scanbuild_basicusage">Basic Usage</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 &quot;Debug&quot; 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 &quot;scan-build&quot; 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">&lt;command&gt;</span> <i>[command options]</i>
 100 </pre>
 101
 102 <p>Operationally, <tt>scan-build</tt> literally runs &lt;command&gt; 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_otheroptions">Other Options</h3>
 126
 127 <p>As mentioned above, extra options can be passed to <tt>scan-build</tt>. These
 128 options prefix the build command. For example:</p>
 129
 130 <pre class="code_example">
 131  $ scan-build <span class="code_highlight">-k -V</span> make
 132  $ scan-build <span class="code_highlight">-k -V</span> xcodebuild
 133 </pre>
 134
 135 <p>Here is a subset of useful options:</p>
 136
 137 <table class="options">
 138 <thead><tr><td>Option</td><td>Description</td></tr></thead>
 139
 140 <tr><td><b>-o</b></td><td>Target directory for HTML report files. Subdirectories
 141 will be created as needed to represent separate "runs" of the analyzer. If this
 142 option is not specified, a directory is created in <tt>/tmp</tt> to store the
 143 reports.</td></tr>
 144
 145 <tr><td><b>-h</b><br><i>(or&nbsp;no&nbsp;arguments)</i></td><td>Display all
 146 <tt>scan-build</tt> options.</td></tr>
 147
 148 <tr><td><b>-k</b><br><b>--keep-going</b></td><td>Add a "keep on
 149 going" option to the specified build command. <p>This option currently supports
 150 <tt>make</tt> and <tt>xcodebuild</tt>.</p> <p>This is a convenience option; one
 151 can specify this behavior directly using build options.</p></td></tr>
 152
 153 <tr><td><b>-v</b></td><td>Verbose output from scan-build and the analyzer. <b>A
 154 second and third "-v" increases verbosity</b>, and is useful for filing bug
 155 reports against the analyzer.</td></tr>
 156
 157 <tr><td><b>-V</b></td><td>View analysis results in a web browser when the build
 158 command completes.</td></tr> </table>
 159
 160 <p>A complete list of options can be obtained by running <tt>scan-build</tt>
 161 with no arguments.</p>
 162
 163 <h3 id="scanbuild_output">Output of scan-build</h3>
 164
 165 <p>
 166 The output of scan-build is a set of HTML files, each one which represents a
 167 separate bug report. A single <tt>index.html</tt> file is generated for
 168 surveying all of the bugs. You can then just open <tt>index.html</tt> in a web
 169 browser to view the bug reports.
 170 </p>
 171
 172 <p>
 173 Where the HTML files are generated is specified with a <b>-o</b> option to
 174 <tt>scan-build</tt>. If <b>-o</b> isn't specified, a directory in <tt>/tmp</tt>
 175 is created to store the files (<tt>scan-build</tt> will print a message telling
 176 you where they are). If you want to view the reports immediately after the build
 177 completes, pass <b>-V</b> to <tt>scan-build</tt>.
 178 </p>
 179
 180
 181 <h2 id="recommendedguidelines">Recommended Usage Guidelines</h2>
 182
 183 <p>This section describes a few recommendations with running the analyzer.</p>
 184
 185 <h3 id="recommended_debug">ALWAYS analyze a project in its &quot;debug&quot; configuration</h3>
 186
 187 <p>Most projects can be built in a &quot;debug&quot; mode that enables assertions.
 188 Assertions are picked up by the static analyzer to prune infeasible paths, which
 189 in some cases can greatly reduce the number of false positives (bogus error
 190 reports) emitted by the tool.</p>
 191
 192 <h3 id="recommend_verbose">Use verbose output when debugging scan-build</h3>
 193
 194 <p><tt>scan-build</tt> takes a <b>-v</b> option to emit verbose output about
 195 what it's doing; two <b>-v</b> options emit more information. Redirecting the
 196 output of <tt>scan-build</tt> to a text file (make sure to redirect standard
 197 error) is useful for filing bug reports against <tt>scan-build</tt> or the
 198 analyzer, as we can see the exact options (and files) passed to the analyzer.
 199 For more comprehensible logs, don't perform a parallel build.</p>
 200
 201 <h3 id="recommended_autoconf">Run './configure' through scan-build</h3>
 202
 203 <p>If an analyzed project uses an autoconf generated <tt>configure</tt> script,
 204 you will probably need to run <tt>configure</tt> script through
 205 <tt>scan-build</tt> in order to analyze the project.</p>
 206
 207 <p><b>Example</b></p>
 208
 209 <pre class="code_example">
 210 $ scan-build ./configure
 211 $ scan-build make
 212 </pre>
 213
 214 <p>The reason <tt>configure</tt> also needs to be run through
 215 <tt>scan-build</tt> is because <tt>scan-build</tt> scans your source files by
 216 <i>interposing</i> on the compiler. This interposition is currently done by
 217 <tt>scan-build</tt> temporarily setting the environment variable <tt>CC</tt> to
 218 <tt>ccc-analyzer</tt>. The program <tt>ccc-analyzer</tt> acts like a fake
 219 compiler, forwarding its command line arguments over to the compiler to perform
 220 regular compilation and <tt>clang</tt> to perform static analysis.</p>
 221
 222 <p>Running <tt>configure</tt> typically generates makefiles that have hardwired
 223 paths to the compiler, and by running <tt>configure</tt> through
 224 <tt>scan-build</tt> that path is set to <tt>ccc-analyzer</tt>.</p>
 225
 226 <!--
 227 <h2 id="Debugging">Debugging the Analyzer</h2>
 228
 229 <p>This section provides information on debugging the analyzer, and troubleshooting
 230 it when you have problems analyzing a particular project.</p>
 231
 232 <h3>How it Works</h3>
 233
 234 <p>To analyze a project, <tt>scan-build</tt> simply sets the environment variable
 235 <tt>CC</tt> to the full path to <tt>ccc-analyzer</tt>. It also sets a few other
 236 environment variables to communicate to <tt>ccc-analyzer</tt> where to dump HTML
 237 report files.</p>
 238
 239 <p>Some Makefiles (or equivalent project files) hardcode the compiler; for such
 240 projects simply overriding <tt>CC</tt> won't cause <tt>ccc-analyzer</tt> to be
 241 called. This will cause the compiled code <b>to not be analyzed.</b></p> If you
 242 find that your code isn't being analyzed, check to see if <tt>CC</tt> is
 243 hardcoded. If this is the case, you can hardcode it instead to the <b>full
 244 path</b> to <tt>ccc-analyzer</tt>.</p>
 245
 246 <p>When applicable, you can also run <tt>./configure</tt> for a project through
 247 <tt>scan-build</tt> so that configure sets up the location of <tt>CC</tt> based
 248 on the environment passed in from <tt>scan-build</tt>:
 249
 250 <pre>
 251   $ scan-build <b>./configure</b>
 252 </pre>
 253
 254 <p><tt>scan-build</tt> has special knowledge about <tt>configure</tt>, so it in
 255 most cases will not actually analyze the configure tests run by
 256 <tt>configure</tt>.</p>
 257
 258 <p>Under the hood, <tt>ccc-analyzer</tt> directly invokes <tt>gcc</tt> to
 259 compile the actual code in addition to running the analyzer (which occurs by it
 260 calling <tt>clang</tt>). <tt>ccc-analyzer</tt> tries to correctly forward all
 261 the arguments over to <tt>gcc</tt>, but this may not work perfectly (please
 262 report bugs of this kind).
 263  -->
 264
 265 <h2 id="iphone">Analyzing iPhone Projects</h2>
 266
 267 <p>Conceptually Xcode projects for iPhone applications are nearly the same as
 268 their cousins for desktop applications. <b>scan-build</b> can analyze these
 269 projects as well, but users often encounter problems with just building their
 270 iPhone projects from the command line because there are a few extra preparative
 271 steps they need to take (e.g., setup code signing).</p>
 272
 273 <h3>Recommendation: use &quot;Build and Analyze&quot;</h3>
 274
 275 <p>The absolute easiest way to analyze iPhone projects is to use the <a
 276 href="http://developer.apple.com/mac/library/featuredarticles/StaticAnalysis/index.html"><i>Build
 277 and Analyze</i> feature in Xcode 3.2</a> (which is based on the Clang Static
 278 Analyzer). There a user can analyze their project with the click of a button
 279 without most of the setup described later.</p>
 280
 281 <p><a href="/xcode.html">Instructions are available</a> on this
 282 website on how to use open source builds of the analyzer as a replacement for
 283 the one bundled with Xcode.</p>
 284
 285 <h3>Using scan-build directly</h3>
 286
 287 <p>If you wish to use <b>scan-build</b> with your iPhone project, keep the
 288 following things in mind:</p>
 289
 290 <ul>
 291  <li>Analyze your project in the <tt>Debug</tt> configuration, either by setting
 292 this as your configuration with Xcode or by passing <tt>-configuration
 293 Debug</tt> to <tt>xcodebuild</tt>.</li>
 294  <li>Analyze your project using the <tt>Simulator</tt> as your base SDK. It is
 295 possible to analyze your code when targeting the device, but this is much
 296 easier to do when using Xcode's <i>Build and Analyze</i> feature.</li>
 297  <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>
 298 </ul>
 299
 300 <p>Note that you can most of this without actually modifying your project. For
 301 example, if your application targets iPhoneOS 2.2, you could run
 302 <b>scan-build</b> in the following manner from the command line:</p>
 303
 304 <pre class="code_example">
 305 $ scan-build xcodebuild -configuration Debug -sdk iphonesimulator2.2
 306 </pre>
 307
 308 Alternatively, if your application targets iPhoneOS 3.0:
 309
 310 <pre class="code_example">
 311 $ scan-build xcodebuild -configuration Debug -sdk iphonesimulator3.0
 312 </pre>
 313
 314 <h3>Gotcha: using the right compiler</h3>
 315
 316 <p>Recall that <b>scan-build</b> analyzes your project by using a compiler to
 317 compile the project and <tt>clang</tt> to analyze your project. The script uses
 318 simple heuristics to determine which compiler should be used (it defaults to
 319 <tt>clang</tt> on Darwin and <tt>gcc</tt> on other platforms). When analyzing
 320 iPhone projects, <b>scan-build</b> may pick the wrong compiler than the one
 321 Xcode would use to build your project. For example, this could be because
 322 multiple versions of a compiler may be installed on your system, especially if
 323 you are developing for the iPhone.</p>
 324
 325 <p>When compiling your application to run on the simulator, it is important that <b>scan-build</b>
 326 finds the correct version of <tt>gcc/clang</tt>. Otherwise, you may see strange build
 327 errors that only happen when you run <tt>scan-build</tt>.
 328
 329 <p><b>scan-build</b> provides the <tt>--use-cc</tt> and <tt>--use-c++</tt>
 330 options to hardwire which compiler scan-build should use for building your code.
 331 Note that although you are chiefly interested in analyzing your project, keep in
 332 mind that running the analyzer is intimately tied to the build, and not being
 333 able to compile your code means it won't get fully analyzed (if at all).</p>
 334
 335 <p>If you aren't certain which compiler Xcode uses to build your project, try
 336 just running <tt>xcodebuild</tt> (without <b>scan-build</b>). You should see the
 337 full path to the compiler that Xcode is using, and use that as an argument to
 338 <tt>--use-cc</tt>.</p>
 339
 340 </div>
 341 </div>
 342 </body>
 343 </html>
 344