From: Ted Kremenek Date: Fri, 25 Apr 2008 18:44:36 +0000 (+0000) Subject: Added some notes about the LLVM "checker". This isn't a public link yet; still refining. X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=ce2e33258a00ecea14c87995cb981c1e816d3df4;p=clang Added some notes about the LLVM "checker". This isn't a public link yet; still refining. git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@50283 91177308-0d34-0410-b5e6-96231b3b80d8 --- diff --git a/www/CheckerNotes.html b/www/CheckerNotes.html new file mode 100644 index 0000000000..3fbf0d311a --- /dev/null +++ b/www/CheckerNotes.html @@ -0,0 +1,242 @@ + + + Information on using the Static Analyzer ("LLVM Checker") + + + + +

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:

+ +

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