# 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

- Basic Usage
- Other Options
- Output of scan-build

- Recommended Usage Guidelines

- Always Analyze a Project in its "Debug" Configuration
- Use Verbose Output when Debugging scan-build
- Run './configure' through scan-build

## 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 <command> with all of the subsequent options passed to it. For example, one can pass `-j4` to `make` get a parallel build over 4 cores:

    $ 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 (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.

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`.</p.>