# Information on using the Static Analyzer ("LLVM Checker")

This documents provides some notes on using the LLVM/clang static analyzer to find bugs in C and Objective-C programs.

This document is arranged into the following sections:

- Downloadable Package Contents
- Basic Usage
- Output of the Analyzer
- Recommended Usage Guidelines
- Debugging the Analyzer

## Package Contents

The static analyzer is released as a single tarball: `checker-XXX.tar.gz`, where XXX is the release tag. The tarball expands 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

## 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
-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 "-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:

      -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. Apple-internal users should file bugs in Radar against the llvm - clang component. External-Apple users should file bugs in LLVM's Bugzilla against clang.