forked from OSchip/llvm-project
Split static analysis page into two pages: a high-level information page (with quick download links) and a usage page.
llvm-svn: 52386
This commit is contained in:
Ted Kremenek
parent
7d14f86f4a
commit
2d93ec7eca
|
|
@ -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>
|
||||
<!-- Generated from: http://www.spiffycorners.com/index.php -->
|
||||
|
||||
<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>
|
||||
<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>
|
||||
.spiffyfg h2 {
|
||||
margin:0px; padding:10px;
|
||||
}
|
||||
</style>
|
||||
|
||||
<tr><td><b>-h</b><br><i><nobr>(or no arguments)</nobr></i></td><td>Display <tt>scan-build</tt> options.</td></tr>
|
||||
<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>
|
||||
|
||||
<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>
|
||||
<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>
|
||||
|
||||
<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>
|
||||
<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>
|
||||
|
||||
<tr><td><b>-V</b></td><td>View analysis results in a web browser when the build command completes.</td></tr>
|
||||
</table>
|
||||
<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>
|
||||
|
||||
<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>
|
||||
|
||||
<p>Please file bugs in Radar against the <b>llvm - clang</b> component.</p>
|
||||
<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>
|
||||
</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>
|
||||
|
||||
Loading…
Reference in New Issue