www/StaticAnalysis.html - fp2-dev/platform/external/clang - Gitiles

 <html>
 <head>
   <title>Information on using the Static Analyzer ("LLVM Checker")</title>
   <style type="text/css">
    body { color:#000000; background-color:#ffffff }
    body { font-family: Helvetica, sans-serif; font-size:9pt }
    thead {
      background-color:#eee; color:#666666;
      font-weight: bold; cursor: default;
      text-align:center;
      border-top: 2px solid #000000;
      border-bottom: 2px solid #000000;
      font-weight: bold; font-family: Verdana
    }
    table { border: 1px #000000 solid }
    table { border-collapse: collapse; border-spacing: 0px }
    table { margin-left:20px; margin-top:20px; margin-bottom:20px }
    td { border-bottom: 1px #000000 dotted }
    td { padding:5px; padding-left:8px; padding-right:8px }
    td { text-align:left; font-size:9pt }
    td.View   { padding-left: 10px }
   </style>
 </head>
 <body>

 <h1>Information on using the Static Analyzer ("LLVM Checker")</h1>

 <p>This documents provides some notes on using the LLVM/clang static analyzer
 to find bugs in C and Objective-C programs. Please note that this tool is very
 earlier in development, and there are many planned enhancements to improve both
 the analysis precision of the tool and the number of bugs it will find.</p>

 <p>This document is arranged into the following sections:</p>

 <ul>
   <li><a href="#Contents">Obtaining the Analyzer</a></li>
   <li><a href="#BasicUsage">Basic Usage</a></li>
   <li><a href="#Output">Output of the Analyzer</a></li>
   <li><a href="#RecommendedUsageGuidelines">Recommended Usage Guidelines</a></li>
   <li><a href="#Debugging">Debugging the Analyzer</a>
 </ul>

 <h2 id="ReleaseContents">Obtaining the Analyzer</h2>

 <p> Semi-regular builds of the analyzer on Mac OS X (10.5) are available <a
 href="http://keeda.stanford.edu/~kremenek/checker">here</a>. Packaged builds for
 other platforms may eventually be provided, but as the tool is in its early
 stages we are not actively promoting releases yet.</p>

 <p>Packaged builds consist of a few files from the Clang source tree, meaning
 that <b>anyone</b> who can build Clang can use the static analyzer. The packaged
 builds of the analyzer expand to the following files that are taken from the
 <tt>utils</tt> and <tt>Driver</tt> subdirectories in the Clang tree:</p>

 <table>
 <thead><tr><td>File</td><td>Purpose</td></tr></thead>
 <tr><td><tt><b>scan-build</b></tt></td><td>Script for running the analyzer over a project build.  <b>This is the only file you care about.</b></td></tr>
 <tr><td><tt>ccc-analyzer</tt></td><td>GCC interceptor (called by scan-build)</td></tr>
 <tr><td><tt>clang</tt></td><td>Static Analyzer (called by ccc-analyzer)</td><tr>
 <tr><td><tt>sorttable.js</tt></td><td>JavaScript used for displaying error reports</td></tr>
 </table>

 <p> Using the analyzer involves executing <tt>scan-build</tt> (see <a
 href="#BasicUsage">Basic Usage</a>). <tt>scan-build</tt> will first look for a
 <tt>clang</tt> executable in the same directory as <tt>scan-build</tt>, and then
 search your path. If one is using the analyzer directly from the Clang sources,
 it suffices to just directly execute <tt>scan-build</tt> in the <tt>utils</tt>
 directory. No other special installation is needed.</p>

 <h2 id="BasicUsage">Basic Usage</h2>

 <p>The analyzer is executed from the command-line. To run the analyzer, you will
 use <tt>scan-build</tt> to analyze the source files compiled by <tt>gcc</tt>
 during a project build.</p>

 <p>For example, to analyze the files compiled under a build:</p>

 <pre>
    $ <b>scan-build</b> make
    $ <b>scan-build</b> xcodebuild
 </pre>

 <p> In the first case <tt>scan-build</tt> analyzes the code of a project built
 with <tt>make</tt>, andin the second case <tt>scan-build</tt> analyzes a project
 built using <tt>xcodebuild</tt>. In general, the format is: </p>

 <pre>
    $ <b>scan-build</b> <i>[scan-build options]</i> <b>&lt;command&gt;</b> <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</p>

 <pre>
    $ scan-build make <b>-j4</b>
 </pre>

 <p>In this example, <tt>scan-build</tt> makes no effort to interpret the options
 after the build command (in this case, <tt>make</tt>); it just passes them
 through. In general, <tt>scan-build</tt> should support parallel builds, but
 <b>not distributed builds</b>. Similarly, you can use <tt>scan-build</tt> to
 analyze specific files:

 <pre>
    $ scan-build gcc -c <b>t1.c t2.c</b>
 </pre>

 <p>
 This example causes the files <tt>t1.c</tt> and <tt>t2.c</tt> to be analyzed.
 </p>

 <h3>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>
    $ scan-build <b>-k -V</b> make
    $ scan-build <b>-k -V</b> xcodebuild
 </pre>

 <p>Here are a complete list of options:</p>

 <table>
   <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 <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
   "-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>These options can also be viewed by running <tt>scan-build</tt> with no
 arguments:</p>

 <pre>
   $ <b>scan-build</b>

   USAGE: scan-build [options] &lt;build command&gt; [build options]

   OPTIONS:

   -o            - 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 /tmp to store the reports.
   <b>...</b>
 </pre>

 <h2 id="Output">Output of the Analyzer</h2>

 <p>
 The output of the analyzer 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="RecommendedUsageGuidelines">Recommended Usage Guidelines</h2>

 Here are a few recommendations with running the analyzer:

 <h3>Always Analyze a Project in its "Debug" Configuration</h3>

 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.

 <h3>Pass -k to <tt>scan-build</tt></h3>

 <p>While <tt>ccc-analyzer</tt> invokes <tt>gcc</tt> to compile code, any
 problems in correctly forwarding arguments to <tt>gcc</tt> may result in a build
 failure. Passing <b>-k</b> to <tt>scan-build</tt> potentially allows you to
 analyze other code in a project for which this problem doesn't occur.</p>

 <p> Also, it is useful to analyze a project even if not all of the source files
 are compilable. This is great when using <tt>scan-build</tt> as part of your
 compile-debug cycle.</p>

 <h3>Use Verbose Output when Debugging <tt>scan-build</tt></h3>

 <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
 comprehendible logs, don't perform a parallel build.

 <h2 id="Debugging">Debugging the Analyzer</h2>

 This section provides information on debugging the analyzer, and troubleshooting
 it when you have problems analyzing a particular project.

 <h3>How it Works</h3>

 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>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).

 <h3>Filing Bugs</h3>

 We encourage users to file bug reports for any problems that they encounter.
 Apple-internal users should file bugs in Radar against the <b>llvm - clang</b>
 component. External-Apple users should file bugs in <a
 href="http://llvm.org/bugs/enter_bug.cgi?product=clang">LLVM's Bugzilla against
 clang</a>.
	<html>
	<head>
	<title>Information on using the Static Analyzer ("LLVM Checker")</title>
	<style type="text/css">
	body { color:#000000; background-color:#ffffff }
	body { font-family: Helvetica, sans-serif; font-size:9pt }
	thead {
	background-color:#eee; color:#666666;
	font-weight: bold; cursor: default;
	text-align:center;
	border-top: 2px solid #000000;
	border-bottom: 2px solid #000000;
	font-weight: bold; font-family: Verdana
	}
	table { border: 1px #000000 solid }
	table { border-collapse: collapse; border-spacing: 0px }
	table { margin-left:20px; margin-top:20px; margin-bottom:20px }
	td { border-bottom: 1px #000000 dotted }
	td { padding:5px; padding-left:8px; padding-right:8px }
	td { text-align:left; font-size:9pt }
	td.View { padding-left: 10px }
	</style>
	</head>
	<body>

	<h1>Information on using the Static Analyzer ("LLVM Checker")</h1>

	<p>This documents provides some notes on using the LLVM/clang static analyzer
	to find bugs in C and Objective-C programs. Please note that this tool is very
	earlier in development, and there are many planned enhancements to improve both
	the analysis precision of the tool and the number of bugs it will find.</p>

	<p>This document is arranged into the following sections:</p>

	<ul>
	<li><a href="#Contents">Obtaining the Analyzer</a></li>
	<li><a href="#BasicUsage">Basic Usage</a></li>
	<li><a href="#Output">Output of the Analyzer</a></li>
	<li><a href="#RecommendedUsageGuidelines">Recommended Usage Guidelines</a></li>
	<li><a href="#Debugging">Debugging the Analyzer</a>
	</ul>

	<h2 id="ReleaseContents">Obtaining the Analyzer</h2>

	<p> Semi-regular builds of the analyzer on Mac OS X (10.5) are available <a
	href="http://keeda.stanford.edu/~kremenek/checker">here</a>. Packaged builds for
	other platforms may eventually be provided, but as the tool is in its early
	stages we are not actively promoting releases yet.</p>

	<p>Packaged builds consist of a few files from the Clang source tree, meaning
	that <b>anyone</b> who can build Clang can use the static analyzer. The packaged
	builds of the analyzer expand to the following files that are taken from the
	<tt>utils</tt> and <tt>Driver</tt> subdirectories in the Clang tree:</p>

	<table>
	<thead><tr><td>File</td><td>Purpose</td></tr></thead>
	<tr><td><tt><b>scan-build</b></tt></td><td>Script for running the analyzer over a project build. <b>This is the only file you care about.</b></td></tr>
	<tr><td><tt>ccc-analyzer</tt></td><td>GCC interceptor (called by scan-build)</td></tr>
	<tr><td><tt>clang</tt></td><td>Static Analyzer (called by ccc-analyzer)</td><tr>
	<tr><td><tt>sorttable.js</tt></td><td>JavaScript used for displaying error reports</td></tr>
	</table>

	<p> Using the analyzer involves executing <tt>scan-build</tt> (see <a
	href="#BasicUsage">Basic Usage</a>). <tt>scan-build</tt> will first look for a
	<tt>clang</tt> executable in the same directory as <tt>scan-build</tt>, and then
	search your path. If one is using the analyzer directly from the Clang sources,
	it suffices to just directly execute <tt>scan-build</tt> in the <tt>utils</tt>
	directory. No other special installation is needed.</p>

	<h2 id="BasicUsage">Basic Usage</h2>

	<p>The analyzer is executed from the command-line. To run the analyzer, you will
	use <tt>scan-build</tt> to analyze the source files compiled by <tt>gcc</tt>
	during a project build.</p>

	<p>For example, to analyze the files compiled under a build:</p>

	<pre>
	$ <b>scan-build</b> make
	$ <b>scan-build</b> xcodebuild
	</pre>

	<p> In the first case <tt>scan-build</tt> analyzes the code of a project built
	with <tt>make</tt>, andin the second case <tt>scan-build</tt> analyzes a project
	built using <tt>xcodebuild</tt>. In general, the format is: </p>

	<pre>
	$ <b>scan-build</b> <i>[scan-build options]</i> <b><command></b> <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</p>

	<pre>
	$ scan-build make <b>-j4</b>
	</pre>

	<p>In this example, <tt>scan-build</tt> makes no effort to interpret the options
	after the build command (in this case, <tt>make</tt>); it just passes them
	through. In general, <tt>scan-build</tt> should support parallel builds, but
	<b>not distributed builds</b>. Similarly, you can use <tt>scan-build</tt> to
	analyze specific files:

	<pre>
	$ scan-build gcc -c <b>t1.c t2.c</b>
	</pre>

	<p>
	This example causes the files <tt>t1.c</tt> and <tt>t2.c</tt> to be analyzed.
	</p>

	<h3>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>
	$ scan-build <b>-k -V</b> make
	$ scan-build <b>-k -V</b> xcodebuild
	</pre>

	<p>Here are a complete list of options:</p>

	<table>
	<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 <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
	"-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>These options can also be viewed by running <tt>scan-build</tt> with no
	arguments:</p>

	<pre>
	$ <b>scan-build</b>

	USAGE: scan-build [options] <build command> [build options]

	OPTIONS:

	-o - 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 /tmp to store the reports.
	<b>...</b>
	</pre>

	<h2 id="Output">Output of the Analyzer</h2>

	<p>
	The output of the analyzer 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="RecommendedUsageGuidelines">Recommended Usage Guidelines</h2>

	Here are a few recommendations with running the analyzer:

	<h3>Always Analyze a Project in its "Debug" Configuration</h3>

	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.

	<h3>Pass -k to <tt>scan-build</tt></h3>

	<p>While <tt>ccc-analyzer</tt> invokes <tt>gcc</tt> to compile code, any
	problems in correctly forwarding arguments to <tt>gcc</tt> may result in a build
	failure. Passing <b>-k</b> to <tt>scan-build</tt> potentially allows you to
	analyze other code in a project for which this problem doesn't occur.</p>

	<p> Also, it is useful to analyze a project even if not all of the source files
	are compilable. This is great when using <tt>scan-build</tt> as part of your
	compile-debug cycle.</p>

	<h3>Use Verbose Output when Debugging <tt>scan-build</tt></h3>

	<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
	comprehendible logs, don't perform a parallel build.

	<h2 id="Debugging">Debugging the Analyzer</h2>

	This section provides information on debugging the analyzer, and troubleshooting
	it when you have problems analyzing a particular project.

	<h3>How it Works</h3>

	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>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).

	<h3>Filing Bugs</h3>

	We encourage users to file bug reports for any problems that they encounter.
	Apple-internal users should file bugs in Radar against the <b>llvm - clang</b>
	component. External-Apple users should file bugs in <a
	href="http://llvm.org/bugs/enter_bug.cgi?product=clang">LLVM's Bugzilla against
	clang</a>.