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