2008-04-26 02:44:36 +08:00
< html >
< head >
2008-06-13 03:14:13 +08:00
< title > Information on using the Static Analyzer ("Clang Checker")< / title >
2008-06-11 13:26:52 +08:00
< link type = "text/css" rel = "stylesheet" href = "menu.css" / >
< link type = "text/css" rel = "stylesheet" href = "content.css" / >
2008-06-11 13:55:39 +08:00
< style >
2008-06-11 13:28:36 +08:00
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 >
2008-04-26 02:44:36 +08:00
< / head >
< body >
2008-06-11 13:26:52 +08:00
<!-- #include virtual="menu.html.incl" -->
< div id = "content" >
2008-06-11 14:01:28 +08:00
< h1 > Information on using the Static Analyzer< / h1 >
2008-04-26 02:44:36 +08:00
2008-06-13 03:14:13 +08:00
< p > This page provides some notes on using the LLVM/clang static analyzer to find
bugs in C and Objective-C programs.< / p >
2008-06-11 13:25:12 +08:00
2008-06-12 00:09:34 +08:00
< p > Currently the analyzer is invoked as a command-line tool. It is intended to
2008-06-13 02:39:02 +08:00
run in tandem with a build of a project or code base. Analysis results are
2008-06-12 00:09:34 +08:00
deposited in a directory as HTML files, which can then viewed using a web
2008-06-13 02:39:02 +08:00
browser (open the generated < tt > index.html< / tt > file to view a list of flagged
errors).< / p >
< h3 > Important Notes (Please Read)< / h3 >
< p > Here are some important points we ask you to consider when using the static
analyzer:< / p >
< ul >
2008-06-12 00:09:34 +08:00
2008-06-13 02:39:02 +08:00
< li > < b > This tool is < b > very early< / b > in development.< / b > There are many planned
enhancements to improve both the precision and scope of its analysis algorithms
as well as the kinds bugs it will find.< / li >
< li > < b > False positives.< / b > Static analysis reasons about the run-time behavior
of a program without actually running the program. Static analysis is not
perfect, and can falsely flag bugs in a program where the code behaves
correctly. Because some code checks performed by the analyzer require more
analysis than others, the frequency of false positives can vary widely between
different checks. Our goal is to have the analyzer have a low false positive
rate for most code on all checks, and we will reach this goal by gradually
improving over time the analysis precision of the tool.< / li >
< li > < b > Static analysis can be much slower than compilation.< / b > The analyzer
performs a variety of checks on code, each requiring different levels of
analysis precision (more precision = more CPU time). While the analyzer is being
designed to be as fast and light-weight as possible, please do not expect it to
be as fast as compiling a program (even with optimizations enabled). Some of the
algorithms needed to find bugs require in the worst case exponential time. The
analyzer runs in a reasonable amount of time by both bounding the amount of
checking work it will do as well as using clever algorithms to reduce the amount
of work it must do to find bugs.< / li >
< / ul >
2008-06-12 00:09:34 +08:00
< h3 > Organization< / h3 >
< p > This page is arranged into the following sections:< / p >
2008-04-26 02:44:36 +08:00
< ul >
2008-06-09 22:30:01 +08:00
< li > < a href = "#Contents" > Obtaining the Analyzer< / a > < / li >
2008-04-26 02:44:36 +08:00
< li > < a href = "#BasicUsage" > Basic Usage< / a > < / li >
2008-04-26 04:29:37 +08:00
< li > < a href = "#Output" > Output of the Analyzer< / a > < / li >
< li > < a href = "#RecommendedUsageGuidelines" > Recommended Usage Guidelines< / a > < / li >
2008-06-13 02:39:02 +08:00
< li > < a href = "#Debugging" > Debugging the Analyzer< / a > < / li >
< li > < a href = "#filingbugs" > Filing Bugs< / a > < / li >
2008-04-26 02:44:36 +08:00
< / ul >
2008-06-09 22:30:01 +08:00
< h2 id = "ReleaseContents" > Obtaining the Analyzer< / h2 >
2008-04-26 02:44:36 +08:00
2008-06-11 13:25:12 +08:00
< 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 >
2008-06-12 00:16:41 +08:00
< h3 > Packaged Builds (Mac OS X)< / h3 >
2008-06-11 13:25:12 +08:00
2008-06-13 02:39:02 +08:00
< p > Semi-regular pre-built binaries of the analyzer are available on Mac OS X
(10.5).< / p >
2008-06-12 00:16:41 +08:00
< p > The latest build is: < b > < a
2008-06-13 02:39:02 +08:00
href="http://keeda.stanford.edu/~kremenek/checker/checker-36.tar.gz">checker-36.tar.gz< / a > < / b > (built June 11, 2008)< / p >
2008-06-12 00:16:41 +08:00
2008-06-13 02:39:02 +08:00
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 >
2008-06-09 22:30:01 +08:00
2008-06-11 13:25:12 +08:00
< p > Packaged builds of the analyzer expand to the following files:< / p >
2008-04-26 02:44:36 +08:00
2008-06-11 13:25:12 +08:00
< table id = "package" >
2008-04-26 02:44:36 +08:00
< 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 >
2008-06-11 13:25:12 +08:00
< 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 >
2008-06-09 22:30:01 +08:00
2008-04-26 02:44:36 +08:00
< 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 >
2008-06-11 13:25:12 +08:00
< 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 >
2008-04-26 02:44:36 +08:00
< 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 >
2008-06-11 13:25:12 +08:00
< tr > < td > < b > -v< b > < / td > < td > Verbose output from scan-build and the analyzer. < b > A second and third
2008-04-26 02:44:36 +08:00
"-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:
2008-06-11 13:25:12 +08:00
-a - The analysis to run. The default is 'checker-cfref'.
Valid options are: 'checker-cfref', 'fsyntax-only'
2008-04-26 02:44:36 +08:00
-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
2008-04-26 04:31:58 +08:00
< tt > scan-build< / tt > . If < b > -o< / b > isn't specified, a directory in < tt > /tmp< / tt >
2008-04-26 02:44:36 +08:00
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 >
2008-04-26 04:30:34 +08:00
< h2 id = "RecommendedUsageGuidelines" > Recommended Usage Guidelines< / h2 >
2008-04-26 02:44:36 +08:00
Here are a few recommendations with running the analyzer:
< h3 > Always Analyze a Project in its "Debug" Configuration< / h3 >
2008-06-13 02:39:02 +08:00
< 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 >
2008-04-26 02:44:36 +08:00
< 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 >
2008-06-13 02:39:02 +08:00
< 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 >
2008-04-26 02:44:36 +08:00
< h2 id = "Debugging" > Debugging the Analyzer< / h2 >
2008-06-13 02:39:02 +08:00
< p > This section provides information on debugging the analyzer, and troubleshooting
it when you have problems analyzing a particular project.< / p >
2008-04-26 02:44:36 +08:00
< h3 > How it Works< / h3 >
2008-06-13 02:39:02 +08:00
< p > To analyze a project, < tt > scan-build< / tt > simply sets the environment variable
2008-04-26 02:44:36 +08:00
< 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
2008-06-13 02:39:02 +08:00
report files.< / p >
2008-04-26 02:44:36 +08:00
< 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).
2008-06-13 02:39:02 +08:00
< h2 id = "filingbugs" > Filing Bugs< / h2 >
2008-04-26 02:44:36 +08:00
2008-06-13 02:39:02 +08:00
< p > We encourage users to file bug reports for any problems that they
encounter.< / p >
2008-06-11 13:25:12 +08:00
2008-06-13 02:39:02 +08:00
< h3 > Outside Apple< / h3 >
2008-06-11 13:25:12 +08:00
2008-06-13 02:39:02 +08:00
< p > Please < a href = "http://llvm.org/bugs/enter_bug.cgi?product=clang" > file
bugs< / a > (against Clang) in LLVM's Bugzilla database.< / p >
2008-06-11 13:25:12 +08:00
2008-06-13 02:39:02 +08:00
< h3 > Apple-internal Users< / h3 >
2008-06-11 13:26:52 +08:00
2008-06-13 02:39:02 +08:00
< p > Please file bugs in Radar against the < b > llvm - clang< / b > component.< / p >
< / div >
2008-06-11 13:25:12 +08:00
< / body >
< / html >
