diff options
| author | Ted Kremenek <kremenek@apple.com> | 2008-04-25 18:44:36 +0000 |
|---|---|---|
| committer | Ted Kremenek <kremenek@apple.com> | 2008-04-25 18:44:36 +0000 |
| commit | ce2e33258a00ecea14c87995cb981c1e816d3df4 (patch) | |
| tree | 0c9294e921609c792a9acc30c9cd8875b1a52f91 | |
| parent | 5827754da1773a7288480ce34bdf1f0a909fff21 (diff) | |
Added some notes about the LLVM "checker". This isn't a public link yet; still refining.
git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@50283 91177308-0d34-0410-b5e6-96231b3b80d8
| -rw-r--r-- | www/CheckerNotes.html | 242 |
1 files changed, 242 insertions, 0 deletions
diff --git a/www/CheckerNotes.html b/www/CheckerNotes.html new file mode 100644 index 0000000000..3fbf0d311a --- /dev/null +++ b/www/CheckerNotes.html @@ -0,0 +1,242 @@ +<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 } + h1 { font-size:12pt } + 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; width:80%;} + 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. + +<p>This document is arranged into the following sections:</p> + +<ul> + <li><a href="#Contents">Downloadable Package Contents</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">Package Contents</h2> + +<p>The static analyzer is released as a single tarball: +<tt>checker-XXX.tar.gz</tt>, where <b>XXX</b> is the release tag. The tarball +expands to the following files:</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> + +<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 +<ttscan-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>. |