Running the Analyzer
While the static analyzer engine can be used as a library, many users will likely use the command-line interface to the analyzer to analyze projects. This page documents scan-build, a program that users can use from the command line to analyze all the source files used to build a project.
Contents
scan-build
The scan-build command can be used to analyze an entire project by essentially interposing on a project's build process. This means that to run the analyzer using scan-build, you will use scan-build to analyze the source files compiled by gcc during a project build. This means that any files that are not compiled will also not be analyzed.
Basic Usage
Basic usage of scan-build is designed to be simple: just place the word "scan-build" in front of your build command:
$ 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.
Here is the general format for invoking scan-build:
$ scan-build [scan-build options] <command> [command options]
Operationally, scan-build literally runs
$ scan-build make -j4
In almost all cases, scan-build makes no effort to interpret the options after the build command; it simply passes them through. In general, scan-build should support parallel builds, but not distributed builds.
It is also possible to 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 | Display all scan-build options. |
| -k | 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. |
A complete list of options can be obtained by running scan-build with no arguments.
Output of scan-build
The output of scan-build 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
This section describes 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.
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.
Run './configure' through scan-build
If an analyzed project uses an autoconf generated configure script, you will probably need to run configure script through scan-build in order to analyze the project.
Example
$ scan-build ./configure $ scan-build make
The reason configure also needs to be run through scan-build is because scan-build scans your source files by interposing on the compiler. This interposition is currently done by scan-build temporarily setting the environment variable CC to ccc-analyzer. The program ccc-analyzer acts like a fake compiler, forwarding its command line arguments over to gcc to perform regular compilation and clang to perform static analysis.
Running configure typically generates makefiles that have hardwired paths to the compiler, and by running configure through scan-build that path is set to ccc-analyzer.