Information on using the Static Analyzer

Obtaining the Analyzer

Using the analyzer involves executing scan-build (see Basic Usage). scan-build will first look for a clang executable in the same directory as scan-build, and then search your path.

If one is using the analyzer directly from the Clang sources, it suffices to just directly execute scan-build in the utils directory. No other special installation is needed.

Packaged Builds (Mac OS X)

Semi-regular pre-built binaries of the analyzer are available on Mac OS X (10.5).

The latest build is:

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 Clang Developers' mailing list.

Packaged builds of the analyzer expand to the following files:

File	Purpose
`scan-build`	Script for running the analyzer over a project build. This is the only file you care about.
`ccc-analyzer`	GCC interceptor (called by scan-build)
`clang`	Static Analyzer (called by ccc-analyzer)
`sorttable.js`	JavaScript used for displaying error reports

Other Platforms (Building the Analyzer from Source)

Packaged builds simply consist of a few files from the Clang source tree, meaning that anyone who can build Clang can use the static analyzer. Please see the Getting Started page for more details on downloading and compiling Clang.

All files used by the analyzer (and included in packaged builds; see above) other than a compiled clang executable are found in the utils subdirectory in the Clang tree.

Basic Usage

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

For example, to analyze the files compiled under a build:

   $ scan-build make
   $ scan-build xcodebuild

In the first case scan-build analyzes the code of a project built with make, and in the second case scan-build analyzes a project built using xcodebuild. In general, the format is:

   $ scan-build [scan-build options] <command> [command options]

Operationally, scan-build literally runs with all of the subsequent options passed to it. For example:

   $ scan-build make -j4

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

   $ scan-build gcc -c t1.c t2.c

This example causes the files t1.c and t2.c to be analyzed.

Other Options

As mentioned above, extra options can be passed to scan-build. These options prefix the build command. For example:

   $ scan-build -k -V make
   $ scan-build -k -V xcodebuild

Here is a subset of useful options:

Option	Description
-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.
-h (or no arguments)	Display all `scan-build` options.
-k --keep-going	Add a "keep on going" option to the specified build command. This option currently supports `make` and `xcodebuild`. This is a convenience option; one can specify this behavior directly using build options.
-v	Verbose output from scan-build and the analyzer. A second and third "-v" increases verbosity, and is useful for filing bug reports against the analyzer.
-V	View analysis results in a web browser when the build command completes.

Output of the Analyzer

The output of the analyzer is a set of HTML files, each one which represents a separate bug report. A single index.html file is generated for surveying all of the bugs. You can then just open index.html in a web browser to view the bug reports.

Where the HTML files are generated is specified with a -o option to scan-build. If -o isn't specified, a directory in /tmp is created to store the files (scan-build will print a message telling you where they are). If you want to view the reports immediately after the build completes, pass -V to scan-build.

Recommended Usage Guidelines

Here are a few recommendations with running the analyzer:

Always Analyze a Project in its "Debug" Configuration

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.

Pass -k to scan-build

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

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

Use Verbose Output when Debugging scan-build

scan-build takes a -v option to emit verbose output about what it's doing; two -v options emit more information. Redirecting the output of scan-build to a text file (make sure to redirect standard error) is useful for filing bug reports against scan-build or the analyzer, as we can see the exact options (and files) passed to the analyzer. For more comprehensible logs, don't perform a parallel build.

Debugging the Analyzer

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

How it Works

To analyze a project, scan-build simply sets the environment variable CC to the full path to ccc-analyzer. It also sets a few other environment variables to communicate to ccc-analyzer where to dump HTML report files.

Some Makefiles (or equivalent project files) hardcode the compiler; for such projects simply overriding CC won't cause ccc-analyzer to be called. This will cause the compiled code to not be analyzed.

If you find that your code isn't being analyzed, check to see if CC is hardcoded. If this is the case, you can hardcode it instead to the full path to ccc-analyzer.

When applicable, you can also run ./configure for a project through scan-build so that configure sets up the location of CC based on the environment passed in from scan-build:

  $ scan-build ./configure

scan-build has special knowledge about configure, so it in most cases will not actually analyze the configure tests run by configure.

Under the hood, ccc-analyzer directly invokes gcc to compile the actual code in addition to running the analyzer (which occurs by it calling clang). ccc-analyzer tries to correctly forward all the arguments over to gcc, but this may not work perfectly (please report bugs of this kind).

Filing Bugs and Feature Requests

We encourage users to file bug reports for any problems that they encounter. We also welcome feature requests. When filing a bug report, please do the following:

Include the checker build (for prebuilt Mac OS X binaries) or the SVN revision number.
Provide a self-encapsulated, reduced test case that exhibits the issue you are experiencing.
Test cases don't tell us everything. Please briefly describe the problem you are seeing.

Outside Apple

Please file bugs in LLVM's Bugzilla database against the Clang Static Analyzer component.

Apple-internal Users

Please file bugs in Radar against the llvm - checker component.