diff options
Diffstat (limited to 'contrib/llvm/tools/clang/www/analyzer/scan-build.html')
| -rw-r--r-- | contrib/llvm/tools/clang/www/analyzer/scan-build.html | 346 |
1 files changed, 0 insertions, 346 deletions
diff --git a/contrib/llvm/tools/clang/www/analyzer/scan-build.html b/contrib/llvm/tools/clang/www/analyzer/scan-build.html deleted file mode 100644 index 1db15fe..0000000 --- a/contrib/llvm/tools/clang/www/analyzer/scan-build.html +++ /dev/null @@ -1,346 +0,0 @@ -<!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%" border="0" 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. By default, this fake compiler -executes <tt>gcc</tt> to compile your code (assuming that <tt>gcc</tt> is your -compiler) 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"> -<center> - <img src="images/scan_build_cmd.png" width="450px" border=0><br> - <a href="images/analyzer_html.png"><img src="images/analyzer_html.png" width="450px" border=0></a> -<br><b>Viewing static analyzer results in a web browser</b></center> -</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> 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 <nobr><tt>-j4</tt></nobr> 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><nobr>(or no arguments)</nobr></i></td><td>Display all -<tt>scan-build</tt> options.</td></tr> - -<tr><td><b>-k</b><br><nobr><b>--keep-going</b></nobr></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 <tt>gcc</tt> 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 targetting 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 <tt>gcc</tt> to -compile the project and <tt>clang</tt> to analyze your project. When analyzing -iPhone projects, <b>scan-build</b> may pick the wrong compiler than the one -Xcode would use to build your project. This is because multiple versions of -<tt>gcc</tt> may be installed on your system, especially if you are developing -for the iPhone.</p> - -<p>Where this particularly might be a problem is if you are using Mac OS 10.5 -(Leopard) to develop for iPhone OS 3.0. The default desktop compiler on Leopard -is gcc-4.0, while the compiler for iPhone OS 3.0 is gcc-4.2. When compiling your -application to run on the simulator, it is important that <b>scan-build</b> -finds the correct version of <tt>gcc</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> - |
