diff options
| -rw-r--r-- | www/StaticAnalysis.html | 384 | ||||
| -rw-r--r-- | www/StaticAnalysisUsage.html | 284 |
2 files changed, 380 insertions, 288 deletions
diff --git a/www/StaticAnalysis.html b/www/StaticAnalysis.html index eea51d5f70..66f46df97b 100644 --- a/www/StaticAnalysis.html +++ b/www/StaticAnalysis.html @@ -1,25 +1,8 @@ <html> <head> - <title>Information on using the Static Analyzer ("Clang Checker")</title> + <title>LLVM/Clang Static Analyzer</title> <link type="text/css" rel="stylesheet" href="menu.css" /> <link type="text/css" rel="stylesheet" href="content.css" /> - <style> - 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> @@ -27,18 +10,11 @@ <div id="content"> -<h1>Information on using the Static Analyzer</h1> +<h1>LLVM/Clang Static Analyzer</h1> -<p>This page provides some notes on using the LLVM/clang static analyzer to find -bugs in C and Objective-C programs.</p> - -<p>Currently the analyzer is invoked as a command-line tool. It is intended to -run in tandem with a build of a project or code base. Analysis results are -deposited in a directory as HTML files, which can then viewed using a web -browser (open the generated <tt>index.html</tt> file to view a list of flagged -errors).</p> - -<h3>Important Notes (Please Read)</h3> +<p>The LLVM/Clang static analyzer is a standalone tool that find bugs in C and +Objective-C programs. Currently the analyzer is invoked as a command-line tool. +It is intended to run in tandem with a build of a project or code base.</p> <p>Here are some important points we ask you to consider when using the static analyzer:</p> @@ -70,269 +46,101 @@ of work it must do to find bugs.</li> </ul> -<h3>Organization</h3> - -<p>This page 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></li> - <li><a href="#filingbugs">Filing Bugs</a></li> -</ul> - -<h2 id="ReleaseContents">Obtaining the Analyzer</h2> - -<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.</p> - -<p>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> - -<h3>Packaged Builds (Mac OS X)</h3> - -<p>Semi-regular pre-built binaries of the analyzer are available on Mac OS X -(10.5).</p> - -<p>The latest build is: <b><a -href="http://keeda.stanford.edu/~kremenek/checker/checker-37.tar.gz">checker-37.tar.gz</a></b> (built June 16, 2008)</p> - -<p><b>Note: This fixes a serious bug in checker-36 where the analyzer would -never be run, thus finding no bugs.</b></p> - -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. If you wish -to help contribute regular builds of the analyzer on other platforms, please -email the <a href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev">Clang -Developers' mailing list</a>.</p> - -<p>Packaged builds of the analyzer expand to the following files:</p> - -<table id="package"> -<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> - -<h3>Other Platforms (Building the Analyzer from Source)</h3> - -<p>Packaged builds simply consist of a few files from the Clang source tree, -meaning that <b>anyone</b> who can build Clang can use the static analyzer. -Please see the <a href="get_started.html">Getting Started</a> page for more -details on downloading and compiling Clang.</p> - -<p>All files used by the analyzer (and included in packaged builds; <a -href="#package">see above</a>) other than a compiled <tt>clang</tt> executable -are found in the <tt>utils</tt> subdirectory in the Clang tree.</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> +<!-- Generated from: http://www.spiffycorners.com/index.php --> + +<style type="text/css"> +.spiffy{display:block} +.spiffy *{ + display:block; + height:1px; + overflow:hidden; + font-size:.01em; + background:#EBF0FA} +.spiffy1{ + margin-left:3px; + margin-right:3px; + padding-left:1px; + padding-right:1px; + border-left:1px solid #f6f8fc; + border-right:1px solid #f6f8fc; + background:#f0f3fb} +.spiffy2{ + margin-left:1px; + margin-right:1px; + padding-right:1px; + padding-left:1px; + border-left:1px solid #fdfdfe; + border-right:1px solid #fdfdfe; + background:#eef2fa} +.spiffy3{ + margin-left:1px; + margin-right:1px; + border-left:1px solid #eef2fa; + border-right:1px solid #eef2fa;} +.spiffy4{ + border-left:1px solid #f6f8fc; + border-right:1px solid #f6f8fc} +.spiffy5{ + border-left:1px solid #f0f3fb; + border-right:1px solid #f0f3fb} +.spiffyfg{ + background:#EBF0FA} - <tr><td><b>-a</b></td> - <td>The analysis to run. The default analysis is <i>checker-cfref</i>. Valid options are: <i>checker-cfref</i>, <i>fsyntax-only</i>. - These translate into options passed down to the <tt>clang</tt> executable, and currently this option is mainly used for debugging.</td></tr> - - <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 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>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: - - -a - The analysis to run. The default is 'checker-cfref'. - Valid options are: 'checker-cfref', 'fsyntax-only' - - -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> - -<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>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> - -<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 comprehendible logs, don't perform a parallel build.</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="filingbugs">Filing Bugs</h2> - -<p>We encourage users to file bug reports for any problems that they -encounter.</p> - -<h3>Outside Apple</h3> - -<p>Please <a href="http://llvm.org/bugs/enter_bug.cgi?product=clang">file -bugs</a> (against Clang) in LLVM's Bugzilla database.</p> - -<h3>Apple-internal Users</h3> +.spiffyfg h2 { + margin:0px; padding:10px; +} +</style> + +<style type="text/css"> + #left { float:left; } + #left h2 { margin:1px; padding-top:0px; } + #right { float:left; margin-left:50px; padding:0px ;} + #right h2 { padding:0px; margin:0px; } + #wrappedcontent { padding:15px;} +</style> + +<div id="left"> + <h2>Using the Analyzer</h2> + <ul> + <li><a href="StaticAnalysisUsage.html#Obtaining">Obtaining the Analyzer</a></li> + <li><a href="StaticAnalysisUsage.html#BasicUsage">Basic Usage</a></li> + <li><a href="StaticAnalysisUsage.html#Output">Output of the Analyzer</a></li> + <li><a href="StaticAnalysisUsage.html#RecommendedUsageGuidelines">Recommended Usage Guidelines</a></li> + <li><a href="StaticAnalysisUsage.html#Debugging">Debugging the Analyzer</a></li> + <li><a href="StaticAnalysisUsage.html#filingbugs">Filing Bugs</a></li> + </ul> +</div> -<p>Please file bugs in Radar against the <b>llvm - clang</b> component.</p> +<div id="right"> + <b class="spiffy"> + <b class="spiffy1"><b></b></b> + <b class="spiffy2"><b></b></b> + <b class="spiffy3"></b> + <b class="spiffy4"></b> + <b class="spiffy5"></b></b> + + <div class="spiffyfg"> + <div id="wrappedcontent"> + <h2>Download</h2> + <ul> + <li>Mac OS X (Intel-only, 10.5+): + <p><b><a href="http://keeda.stanford.edu/~kremenek/checker/checker-37.tar.gz">checker-37.tar.gz</a></b> (built June 16, 2008)</p></li> + <li><a href="StaticAnalysisUsage.html#OtherUsage">Other Platforms</a> (Building from Source)</li> + </div> + + </div> + + <b class="spiffy"> + <b class="spiffy5"></b> + <b class="spiffy4"></b> + <b class="spiffy3"></b> + <b class="spiffy2"><b></b></b> + <b class="spiffy1"><b></b></b></b> +</div> </div> </body> -</html>
\ No newline at end of file +</html> + diff --git a/www/StaticAnalysisUsage.html b/www/StaticAnalysisUsage.html new file mode 100644 index 0000000000..c264fedd6e --- /dev/null +++ b/www/StaticAnalysisUsage.html @@ -0,0 +1,284 @@ +<html> +<head> + <title>Information on using the Static Analyzer ("Clang Checker")</title> + <link type="text/css" rel="stylesheet" href="menu.css" /> + <link type="text/css" rel="stylesheet" href="content.css" /> + <style> + 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> + +<!--#include virtual="menu.html.incl"--> + +<div id="content"> + +<h1>Information on using the Static Analyzer</h1> + +<h2 id="Obtaining">Obtaining the Analyzer</h2> + +<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.</p> + +<p>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> + +<h3>Packaged Builds (Mac OS X)</h3> + +<p>Semi-regular pre-built binaries of the analyzer are available on Mac OS X +(10.5).</p> + +<p>The latest build is: <b><a +href="http://keeda.stanford.edu/~kremenek/checker/checker-37.tar.gz">checker-37.tar.gz</a></b> (built June 16, 2008)</p> + +<p><b>Note: This fixes a serious bug in checker-36 where the analyzer would +never be run, thus finding no bugs.</b></p> + +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. If you wish +to help contribute regular builds of the analyzer on other platforms, please +email the <a href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev">Clang +Developers' mailing list</a>.</p> + +<p>Packaged builds of the analyzer expand to the following files:</p> + +<table id="package"> +<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> + +<h3 id="OtherPlatforms">Other Platforms (Building the Analyzer from Source)</h3> + +<p>Packaged builds simply consist of a few files from the Clang source tree, +meaning that <b>anyone</b> who can build Clang can use the static analyzer. +Please see the <a href="get_started.html">Getting Started</a> page for more +details on downloading and compiling Clang.</p> + +<p>All files used by the analyzer (and included in packaged builds; <a +href="#package">see above</a>) other than a compiled <tt>clang</tt> executable +are found in the <tt>utils</tt> subdirectory in the Clang tree.</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>-a</b></td> + <td>The analysis to run. The default analysis is <i>checker-cfref</i>. Valid options are: <i>checker-cfref</i>, <i>fsyntax-only</i>. + These translate into options passed down to the <tt>clang</tt> executable, and currently this option is mainly used for debugging.</td></tr> + + <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 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>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: + + -a - The analysis to run. The default is 'checker-cfref'. + Valid options are: 'checker-cfref', 'fsyntax-only' + + -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> + +<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>Pass -k to scan-build</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 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 comprehendible logs, don't perform a parallel build.</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="filingbugs">Filing Bugs</h2> + +<p>We encourage users to file bug reports for any problems that they +encounter.</p> + +<h3>Outside Apple</h3> + +<p>Please <a href="http://llvm.org/bugs/enter_bug.cgi?product=clang">file +bugs</a> (against Clang) in LLVM's Bugzilla database.</p> + +<h3>Apple-internal Users</h3> + +<p>Please file bugs in Radar against the <b>llvm - clang</b> component.</p> + +</div> +</body> +</html> + |