LLVM/Clang Static Analyzer

- -

The LLVM/Clang static analyzer is a standalone tool that finds 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.

- -

Here are some important points we ask you to consider when using the static -analyzer:

- -

This tool is very early in development. 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.
Static analysis can be much slower than compilation. 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.
False positives. Static analysis is not perfect. It can falsely flag -bugs in a program where the code behaves correctly. Because some code checks -require more analysis precision than others, the frequency of false positives -can vary widely between different checks. Our eventual goal is to have the -analyzer have a low false positive rate for most code on all checks.

- -

Please tell us about False Positives

- -

If you encounter a false positive, please let us know by filing a bug report. False -positives cannot be addressed unless we know about them.

- -

Want more bugs?

- -

If there are specific kinds of bugs you would like the tool to find, -please feel free to file feature -requests.

- - - - - - - -

Using the Analyzer

- -

- - - - - - - -

Download

Mac OS X (Universal, 10.5+): -
- -
-
Other Platforms (Building from Source)

- -

- - - - - - - -

- +

This page has moved: clang.analyzer.llvm.org.

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.

This page has moved: clang.analyzer.llvm.org.