Information on using the Static Analyzer

LLVM/Clang Static Analyzer

This page provides some notes on using the LLVM/clang static analyzer to 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. Analysis results are -deposited in a directory as HTML files, which can then viewed using a web -browser (open the generated index.html file to view a list of flagged -errors).

- -

Important Notes (Please Read)

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.

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

@@ -70,269 +46,101 @@ of work it must do to find bugs. -

Organization

- -

This page is arranged into the following sections:

- -

Obtaining the Analyzer
Basic Usage
Output of the Analyzer
Recommended Usage Guidelines
Debugging the Analyzer
Filing Bugs

- -

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: checker-37.tar.gz (built June 16, 2008)

- -

Note: This fixes a serious bug in checker-36 where the analyzer would -never be run, thus finding no bugs.

- -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, andin 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 are a complete list of options:

- - - + + + + + + +

Using the Analyzer

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

+ + + + + + + +

Download

Mac OS X (Intel-only, 10.5+): +
checker-37.tar.gz (built June 16, 2008)
Other Platforms (Building from Source)

+ +

+ + + + + + + +

- \ No newline at end of file + + diff --git a/www/StaticAnalysisUsage.html b/www/StaticAnalysisUsage.html new file mode 100644 index 0000000000..c264fedd6e --- /dev/null +++ b/www/StaticAnalysisUsage.html @@ -0,0 +1,284 @@ + + + Information on using the Static Analyzer ("Clang Checker") + + + + + + + + +

+ +

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: checker-37.tar.gz (built June 16, 2008)

+ +

Note: This fixes a serious bug in checker-36 where the analyzer would +never be run, thus finding no bugs.

+ +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:

+ +

Option	Description

+ + + + + +

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, andin 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 are a complete list of options:

+ + + + + + + + + + + + + + + + +

Option	Description
-a	The analysis to run. The default analysis is checker-cfref. Valid options are: checker-cfref, fsyntax-only. + These translate into options passed down to the `clang` executable, and currently this option is mainly used for debugging.
-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 `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.

+ +

These options can also be viewed by running scan-build with no +arguments:

+ +

+  $ scan-build
+
+  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.
+  ...
+

+ +

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 comprehendible 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

+ +

We encourage users to file bug reports for any problems that they +encounter.

+ +

Outside Apple

+ +

Please file +bugs (against Clang) in LLVM's Bugzilla database.

+ +

Apple-internal Users

+ +

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

+ +