/external/clang/www/analyzer/scan-build.html
HTML | 344 lines | 233 code | 72 blank | 39 comment | 0 complexity | e3ee4598f3f78a0fb283b8866ac790b9 MD5 | raw file
- <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
- "http://www.w3.org/TR/html4/strict.dtd">
- <html>
- <head>
- <title>scan-build: running the analyzer from the command line</title>
- <link type="text/css" rel="stylesheet" href="content.css">
- <link type="text/css" rel="stylesheet" href="menu.css">
- <script type="text/javascript" src="scripts/menu.js"></script>
- <script type="text/javascript" src="scripts/dbtree.js"></script>
- </head>
- <body>
- <div id="page">
- <!--#include virtual="menu.html.incl"-->
- <div id="content">
- <h1>scan-build: running the analyzer from the command line</h1>
- <table style="margin-top:0px" width="100%" cellpadding="0px" cellspacing="0">
- <tr><td>
- <h3>What is it?</h3>
- <p><b>scan-build</b> is a command line utility that enables a user to run the
- static analyzer over their codebase as part of performing a regular build (from
- the command line).</p>
- <h3>How does it work?</h3>
- <p>During a project build, as source files are compiled they are also analyzed
- in tandem by the static analyzer.</p>
- <p>Upon completion of the build, results are then presented to the user within a
- web browser.</p>
- <h3>Will it work with any build system?</h3>
- <p><b>scan-build</b> has little or no knowledge about how you build your code.
- It works by overriding the <tt>CC</tt> and <tt>CXX</tt> environment variables to
- (hopefully) change your build to use a "fake" compiler instead of the
- one that would normally build your project. This fake compiler executes either
- <tt>clang</tt> or <tt>gcc</tt> (depending on the platform) to compile your
- code and then executes the static analyzer to analyze your code.</p>
- <p>This "poor man's interposition" works amazingly well in many cases
- and falls down in others. Please consult the information on this page on making
- the best use of <b>scan-build</b>, which includes getting it to work when the
- aforementioned hack fails to work.</p>
- </td>
- <td style="padding-left:10px; text-align:center">
- <img src="images/scan_build_cmd.png" width="450px" alt="scan-build"><br>
- <a href="images/analyzer_html.png"><img src="images/analyzer_html.png" width="450px" alt="analyzer in browser"></a>
- <br><b>Viewing static analyzer results in a web browser</b>
- </td></tr></table>
- <h2>Contents</h2>
- <ul id="collapsetree" class="dbtree onclick multiple">
- <li><a href="#scanbuild">Getting Started</a>
- <ul>
- <li><a href="#scanbuild_basicusage">Basic Usage</a></li>
- <li><a href="#scanbuild_otheroptions">Other Options</a></li>
- <li><a href="#scanbuild_output">Output of scan-build</a></li>
- </ul>
- </li>
- <li><a href="#recommendedguidelines">Recommended Usage Guidelines</a>
- <ul>
- <li><a href="#recommended_debug">Always Analyze a Project in its "Debug" Configuration</a></li>
- <li><a href="#recommended_verbose">Use Verbose Output when Debugging scan-build</a></li>
- <li><a href="#recommended_autoconf">Run './configure' through scan-build</a></li>
- </ul>
- </li>
- <li><a href="#iphone">Analyzing iPhone Projects</a></li>
- </ul>
- <h2 id="scanbuild">Getting Started</h2>
- <p>The <tt>scan-build</tt> command can be used to analyze an entire project by
- essentially interposing on a project's build process. This means that to run the
- analyzer using <tt>scan-build</tt>, you will use <tt>scan-build</tt> to analyze
- the source files compiled by <tt>gcc</tt>/<tt>clang</tt> during a project build.
- This means that any files that are not compiled will also not be analyzed.</p>
- <h3 id="scanbuild_basicusage">Basic Usage</h3>
- <p>Basic usage of <tt>scan-build</tt> is designed to be simple: just place the
- word "scan-build" in front of your build command:</p>
- <pre class="code_example">
- $ <span class="code_highlight">scan-build</span> make
- $ <span class="code_highlight">scan-build</span> xcodebuild
- </pre>
- <p>In the first case <tt>scan-build</tt> analyzes the code of a project built
- with <tt>make</tt> and in the second case <tt>scan-build</tt> analyzes a project
- built using <tt>xcodebuild</tt>.<p>
-
- <p>Here is the general format for invoking <tt>scan-build</tt>:</p>
- <pre class="code_example">
- $ <span class="code_highlight">scan-build</span> <i>[scan-build options]</i> <span class="code_highlight"><command></span> <i>[command options]</i>
- </pre>
- <p>Operationally, <tt>scan-build</tt> literally runs <command> with all of the
- subsequent options passed to it. For example, one can pass <tt>-j4</tt> to
- <tt>make</tt> get a parallel build over 4 cores:</p>
- <pre class="code_example">
- $ scan-build make <span class="code_highlight">-j4</span>
- </pre>
- <p>In almost all cases, <tt>scan-build</tt> makes no effort to interpret the
- options after the build command; it simply passes them through. In general,
- <tt>scan-build</tt> should support parallel builds, but <b>not distributed
- builds</b>.</p>
- <p>It is also possible to use <tt>scan-build</tt> to analyze specific
- files:</p>
- <pre class="code_example">
- $ scan-build gcc -c <span class="code_highlight">t1.c t2.c</span>
- </pre>
- <p>This example causes the files <tt>t1.c</tt> and <tt>t2.c</tt> to be analyzed.
- </p>
- <h3 id="scanbuild_otheroptions">Other Options</h3>
- <p>As mentioned above, extra options can be passed to <tt>scan-build</tt>. These
- options prefix the build command. For example:</p>
- <pre class="code_example">
- $ scan-build <span class="code_highlight">-k -V</span> make
- $ scan-build <span class="code_highlight">-k -V</span> xcodebuild
- </pre>
- <p>Here is a subset of useful options:</p>
- <table class="options">
- <thead><tr><td>Option</td><td>Description</td></tr></thead>
- <tr><td><b>-o</b></td><td>Target directory for HTML report files. Subdirectories
- will be created as needed to represent separate "runs" of the analyzer. If this
- option is not specified, a directory is created in <tt>/tmp</tt> to store the
- reports.</td></tr>
- <tr><td><b>-h</b><br><i>(or no arguments)</i></td><td>Display all
- <tt>scan-build</tt> options.</td></tr>
- <tr><td><b>-k</b><br><b>--keep-going</b></td><td>Add a "keep on
- going" option to the specified build command. <p>This option currently supports
- <tt>make</tt> and <tt>xcodebuild</tt>.</p> <p>This is a convenience option; one
- can specify this behavior directly using build options.</p></td></tr>
- <tr><td><b>-v</b></td><td>Verbose output from scan-build and the analyzer. <b>A
- second and third "-v" increases verbosity</b>, and is useful for filing bug
- reports against the analyzer.</td></tr>
- <tr><td><b>-V</b></td><td>View analysis results in a web browser when the build
- command completes.</td></tr> </table>
- <p>A complete list of options can be obtained by running <tt>scan-build</tt>
- with no arguments.</p>
- <h3 id="scanbuild_output">Output of scan-build</h3>
- <p>
- The output of scan-build is a set of HTML files, each one which represents a
- separate bug report. A single <tt>index.html</tt> file is generated for
- surveying all of the bugs. You can then just open <tt>index.html</tt> in a web
- browser to view the bug reports.
- </p>
- <p>
- Where the HTML files are generated is specified with a <b>-o</b> option to
- <tt>scan-build</tt>. If <b>-o</b> isn't specified, a directory in <tt>/tmp</tt>
- is created to store the files (<tt>scan-build</tt> will print a message telling
- you where they are). If you want to view the reports immediately after the build
- completes, pass <b>-V</b> to <tt>scan-build</tt>.
- </p>
- <h2 id="recommendedguidelines">Recommended Usage Guidelines</h2>
- <p>This section describes a few recommendations with running the analyzer.</p>
- <h3 id="recommended_debug">ALWAYS analyze a project in its "debug" configuration</h3>
- <p>Most projects can be built in a "debug" mode that enables assertions.
- Assertions are picked up by the static analyzer to prune infeasible paths, which
- in some cases can greatly reduce the number of false positives (bogus error
- reports) emitted by the tool.</p>
- <h3 id="recommend_verbose">Use verbose output when debugging scan-build</h3>
- <p><tt>scan-build</tt> takes a <b>-v</b> option to emit verbose output about
- what it's doing; two <b>-v</b> options emit more information. Redirecting the
- output of <tt>scan-build</tt> to a text file (make sure to redirect standard
- error) is useful for filing bug reports against <tt>scan-build</tt> or the
- analyzer, as we can see the exact options (and files) passed to the analyzer.
- For more comprehensible logs, don't perform a parallel build.</p>
- <h3 id="recommended_autoconf">Run './configure' through scan-build</h3>
- <p>If an analyzed project uses an autoconf generated <tt>configure</tt> script,
- you will probably need to run <tt>configure</tt> script through
- <tt>scan-build</tt> in order to analyze the project.</p>
- <p><b>Example</b></p>
- <pre class="code_example">
- $ scan-build ./configure
- $ scan-build make
- </pre>
- <p>The reason <tt>configure</tt> also needs to be run through
- <tt>scan-build</tt> is because <tt>scan-build</tt> scans your source files by
- <i>interposing</i> on the compiler. This interposition is currently done by
- <tt>scan-build</tt> temporarily setting the environment variable <tt>CC</tt> to
- <tt>ccc-analyzer</tt>. The program <tt>ccc-analyzer</tt> acts like a fake
- compiler, forwarding its command line arguments over to the compiler to perform
- regular compilation and <tt>clang</tt> to perform static analysis.</p>
- <p>Running <tt>configure</tt> typically generates makefiles that have hardwired
- paths to the compiler, and by running <tt>configure</tt> through
- <tt>scan-build</tt> that path is set to <tt>ccc-analyzer</tt>.</p>
- <!--
- <h2 id="Debugging">Debugging the Analyzer</h2>
- <p>This section provides information on debugging the analyzer, and troubleshooting
- it when you have problems analyzing a particular project.</p>
- <h3>How it Works</h3>
- <p>To analyze a project, <tt>scan-build</tt> simply sets the environment variable
- <tt>CC</tt> to the full path to <tt>ccc-analyzer</tt>. It also sets a few other
- environment variables to communicate to <tt>ccc-analyzer</tt> where to dump HTML
- report files.</p>
- <p>Some Makefiles (or equivalent project files) hardcode the compiler; for such
- projects simply overriding <tt>CC</tt> won't cause <tt>ccc-analyzer</tt> to be
- called. This will cause the compiled code <b>to not be analyzed.</b></p> If you
- find that your code isn't being analyzed, check to see if <tt>CC</tt> is
- hardcoded. If this is the case, you can hardcode it instead to the <b>full
- path</b> to <tt>ccc-analyzer</tt>.</p>
- <p>When applicable, you can also run <tt>./configure</tt> for a project through
- <tt>scan-build</tt> so that configure sets up the location of <tt>CC</tt> based
- on the environment passed in from <tt>scan-build</tt>:
- <pre>
- $ scan-build <b>./configure</b>
- </pre>
- <p><tt>scan-build</tt> has special knowledge about <tt>configure</tt>, so it in
- most cases will not actually analyze the configure tests run by
- <tt>configure</tt>.</p>
- <p>Under the hood, <tt>ccc-analyzer</tt> directly invokes <tt>gcc</tt> to
- compile the actual code in addition to running the analyzer (which occurs by it
- calling <tt>clang</tt>). <tt>ccc-analyzer</tt> tries to correctly forward all
- the arguments over to <tt>gcc</tt>, but this may not work perfectly (please
- report bugs of this kind).
- -->
- <h2 id="iphone">Analyzing iPhone Projects</h2>
- <p>Conceptually Xcode projects for iPhone applications are nearly the same as
- their cousins for desktop applications. <b>scan-build</b> can analyze these
- projects as well, but users often encounter problems with just building their
- iPhone projects from the command line because there are a few extra preparative
- steps they need to take (e.g., setup code signing).</p>
- <h3>Recommendation: use "Build and Analyze"</h3>
- <p>The absolute easiest way to analyze iPhone projects is to use the <a
- href="http://developer.apple.com/mac/library/featuredarticles/StaticAnalysis/index.html"><i>Build
- and Analyze</i> feature in Xcode 3.2</a> (which is based on the Clang Static
- Analyzer). There a user can analyze their project with the click of a button
- without most of the setup described later.</p>
- <p><a href="/xcode.html">Instructions are available</a> on this
- website on how to use open source builds of the analyzer as a replacement for
- the one bundled with Xcode.</p>
- <h3>Using scan-build directly</h3>
- <p>If you wish to use <b>scan-build</b> with your iPhone project, keep the
- following things in mind:</p>
- <ul>
- <li>Analyze your project in the <tt>Debug</tt> configuration, either by setting
- this as your configuration with Xcode or by passing <tt>-configuration
- Debug</tt> to <tt>xcodebuild</tt>.</li>
- <li>Analyze your project using the <tt>Simulator</tt> as your base SDK. It is
- possible to analyze your code when targeting the device, but this is much
- easier to do when using Xcode's <i>Build and Analyze</i> feature.</li>
- <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>
- </ul>
- <p>Note that you can most of this without actually modifying your project. For
- example, if your application targets iPhoneOS 2.2, you could run
- <b>scan-build</b> in the following manner from the command line:</p>
- <pre class="code_example">
- $ scan-build xcodebuild -configuration Debug -sdk iphonesimulator2.2
- </pre>
- Alternatively, if your application targets iPhoneOS 3.0:
- <pre class="code_example">
- $ scan-build xcodebuild -configuration Debug -sdk iphonesimulator3.0
- </pre>
- <h3>Gotcha: using the right compiler</h3>
- <p>Recall that <b>scan-build</b> analyzes your project by using a compiler to
- compile the project and <tt>clang</tt> to analyze your project. The script uses
- simple heuristics to determine which compiler should be used (it defaults to
- <tt>clang</tt> on Darwin and <tt>gcc</tt> on other platforms). When analyzing
- iPhone projects, <b>scan-build</b> may pick the wrong compiler than the one
- Xcode would use to build your project. For example, this could be because
- multiple versions of a compiler may be installed on your system, especially if
- you are developing for the iPhone.</p>
- <p>When compiling your application to run on the simulator, it is important that <b>scan-build</b>
- finds the correct version of <tt>gcc/clang</tt>. Otherwise, you may see strange build
- errors that only happen when you run <tt>scan-build</tt>.
- <p><b>scan-build</b> provides the <tt>--use-cc</tt> and <tt>--use-c++</tt>
- options to hardwire which compiler scan-build should use for building your code.
- Note that although you are chiefly interested in analyzing your project, keep in
- mind that running the analyzer is intimately tied to the build, and not being
- able to compile your code means it won't get fully analyzed (if at all).</p>
- <p>If you aren't certain which compiler Xcode uses to build your project, try
- just running <tt>xcodebuild</tt> (without <b>scan-build</b>). You should see the
- full path to the compiler that Xcode is using, and use that as an argument to
- <tt>--use-cc</tt>.</p>
- </div>
- </div>
- </body>
- </html>