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 </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 &quot;fake&quot; 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 &quot;poor man's interposition&quot; 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 &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_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&nbsp;no&nbsp;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 &quot;debug&quot; configuration</h3>
 223
 224 <p>Most projects can be built in a &quot;debug&quot; 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 &quot;Build and Analyze&quot;</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>