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