[cfe-commits] r73086 - in /cfe/trunk/www/analyzer: ./ annotations.html available_checks.html content.css filing_bugs.html index.html installation.html latest_checker.html.incl menu.css menu.html.incl scan-build.html
Ted Kremenek
kremenek at apple.com
Mon Jun 8 14:21:25 PDT 2009
Author: kremenek
Date: Mon Jun 8 16:21:24 2009
New Revision: 73086
URL: http://llvm.org/viewvc/llvm-project?rev=73086&view=rev
Log:
Add skeleton files for new analyzer site.
Added:
cfe/trunk/www/analyzer/
cfe/trunk/www/analyzer/annotations.html
cfe/trunk/www/analyzer/available_checks.html
cfe/trunk/www/analyzer/content.css
cfe/trunk/www/analyzer/filing_bugs.html
cfe/trunk/www/analyzer/index.html
cfe/trunk/www/analyzer/installation.html
cfe/trunk/www/analyzer/latest_checker.html.incl
cfe/trunk/www/analyzer/menu.css
cfe/trunk/www/analyzer/menu.html.incl
cfe/trunk/www/analyzer/scan-build.html
Added: cfe/trunk/www/analyzer/annotations.html
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/www/analyzer/annotations.html?rev=73086&view=auto
==============================================================================
--- cfe/trunk/www/analyzer/annotations.html (added)
+++ cfe/trunk/www/analyzer/annotations.html Mon Jun 8 16:21:24 2009
@@ -0,0 +1,383 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+ <title>Source Annotations</title>
+ <link type="text/css" rel="stylesheet" href="menu.css" />
+ <link type="text/css" rel="stylesheet" href="content.css" />
+</head>
+<body>
+
+<!--#include virtual="menu.html.incl"-->
+
+<div id="content">
+
+<h1>Source Annotations</h1>
+
+<p>The Clang frontend supports several source-level annotations in the form of
+<a href="http://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html">GCC-style
+attributes</a> and pragmas that can help make using the Clang Static Analyzer
+more useful. These annotations can both help suppress false positives as well as
+enhance the analyzer's ability to find bugs.</p>
+
+<p>This page gives a practical overview of such annotations. For more technical
+specifics regarding Clang-specific annotations please see the Clang's list of <a
+href="http://clang.llvm.org/docs/LanguageExtensions.html">language
+extensions</a>. Details of "standard" GCC attributes (that Clang also
+supports) can be found in the <a href="http://gcc.gnu.org/onlinedocs/gcc/">GCC
+manual</a>, with the majority of the relevant attributes being in the section on
+<a href="http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html">function
+attributes</a>.</p>
+
+<p>Note that attributes that are labeled <b>Clang-specific</b> are not
+recognized by GCC. Their use can be conditioned using preprocessor macros
+(examples included on this page).</p>
+
+<ul>
+<li><a href="#generic">Annotations to Enhance Generic Checks</a></li>
+ <ul>
+ <li><a href="#null_checking">Null Pointer Checking</a></li>
+ <ul>
+ <li><a href="#attr_nonnull">Attribute 'nonnull'</a></li>
+ </ul>
+ </ul>
+<li><a href="#macosx">Mac OS X API Annotations</a></li>
+ <ul>
+ <li><a href="#cocoa_mem">Cocoa & Core Foundation Memory Management
+ Annotations</a></li>
+ <ul>
+ <li><a href="#attr_ns_returns_retained">Attribute
+ 'ns_returns_retained'</a></li>
+ <li><a href="#attr_cf_returns_retained">Attribute
+ 'cf_returns_retained'</a></li>
+ </ul>
+ </ul>
+<li><a href="#custom_assertions">Custom Assertion Handlers</a></li>
+ <ul>
+ <li><a href="#attr_noreturn">Attribute 'noreturn'</a></li>
+ <li><a href="#attr_analyzer_noreturn">Attribute 'analyzer_noreturn'</a></li>
+ </ul>
+</ul>
+
+<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
+<h2 id="generic">Annotations to Enhance Generic Checks</h2>
+<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
+
+<h3 id="null_checking">Null Pointer Checking</h3>
+
+<h4 id="attr_nonnull">Attribute 'nonnull'</h4>
+
+<p>The analyzer recognizes the GCC attribute 'nonnull', which indicates that a
+function expects that a given function parameter is not a null pointer. Specific
+details of the syntax of using the 'nonnull' attribute can be found in <a
+href="http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html#index-g_t_0040code_007bnonnull_007d-function-attribute-2263">GCC's
+documentation</a>.</p>
+
+<p>Both the Clang compiler and GCC will flag warnings for simple cases where a
+null pointer is directly being passed to a function with a 'nonnull' parameter
+(e.g., as a constant). The analyzer extends this checking by using its deeper
+symbolic analysis to track what pointer values are potentially null and then
+flag warnings when they are passed in a function call via a 'nonnull'
+parameter.</p>
+
+<p><b>Example</b></p>
+
+<pre class="code_example">
+<span class="command">$ cat test.m</span>
+int bar(int*p, int q, int *r) __attribute__((nonnull(1,3)));
+
+int foo(int *p, int *q) {
+ return !p ? bar(q, 2, p)
+ : bar(p, 2, q);
+}
+
+<span class="command">$ clang --analyze test.m</span>
+test.m:4:16: warning: Null pointer passed as an argument to a 'nonnull' parameter
+ return !p ? bar(q, 2, p)
+ ^ ~
+1 diagnostic generated.
+</pre>
+
+<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
+<h2 id="macosx">Mac OS X API Annotations</h2>
+<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
+
+<h3 id="cocoa_mem">Cocoa & Core Foundation Memory Management
+Annotations</h3>
+
+<p>As described in <a href="/available_checks.html#retain_release">Available
+Checks</a>, the analyzer supports the proper management of retain counts for
+both Cocoa and Core Foundation objects. This checking is largely based on
+enforcing Cocoa and Core Foundation naming conventions for Objective-C methods
+(Cocoa) and C functions (Core Foundation). Not strictly following these
+conventions can cause the analyzer to miss bugs or flag false positives.</p>
+
+<p>One can educate the analyzer (and others who read your code) about methods or
+functions that deviate from the Cocoa and Core Foundation conventions using the
+attributes described here.</p>
+
+<h4 id="attr_ns_returns_retained">Attribute 'ns_returns_retained'
+(Clang-specific)</h4>
+
+<p>The GCC-style (Clang-specific) attribute 'ns_returns_retained' allows one to
+annotate an Objective-C method or C function as returning a retained Cocoa
+object that the caller is responsible for releasing (via sending a
+<tt>release</tt> message to the object).</p>
+
+<p><b>Placing on Objective-C methods</b>: For Objective-C methods, this
+annotation essentially tells the analyzer to treat the method as if its name
+begins with "alloc" or "new" or contais the word
+"copy".</p>
+
+<p><b>Placing on C functions</b>: For C functions returning Cocoa objects, the
+analyzer typically does not make any assumptions about whether or not the object
+is returned retained. Explicitly adding the 'ns_returns_retained' attribute to C
+functions allows the analyzer to perform extra checking.</p>
+
+<p><b>Important note when using Garbage Collection</b>: Note that the analyzer
+interprets this attribute slightly differently when using Objective-C garbage
+collection (available on Mac OS 10.5+). When analyzing Cocoa code that uses
+garbage collection, "alloc" methods are assumed to return an object
+that is managed by the garbage collector (and thus doesn't have a retain count
+the caller must balance). These same assumptions are applied to methods or
+functions annotated with 'ns_returns_retained'. If you are returning a Core
+Foundation object (which may not be managed by the garbage collector) you should
+use 'cf_returns_retained'.</p>
+
+<p><b>Example</b></p>
+
+<pre class="code_example">
+<span class="command">$ cat test.m</span>
+#import <Foundation/Foundation.h>
+
+#ifndef NS_RETURNS_RETAINED
+#if __clang__
+<span class="code_highlight">#define NS_RETURNS_RETAINED __attribute__((ns_returns_retained))</span>
+#else
+#define NS_RETURNS_RETAINED
+#endif
+#endif
+
+ at interface MyClass : NSObject {}
+- (NSString*) returnsRetained <span class="code_highlight">NS_RETURNS_RETAINED</span>;
+- (NSString*) alsoReturnsRetained;
+ at end
+
+ at implementation MyClass
+- (NSString*) returnsRetained {
+ return [[NSString alloc] initWithCString:"no leak here"];
+}
+- (NSString*) alsoReturnsRetained {
+ return [[NSString alloc] initWithCString:"flag a leak"];
+}
+ at end
+
+<span class="command">$ clang --analyze test.m</span>
+$ clang --analyze test.m
+test.m:21:10: warning: Potential leak of an object allocated on line 21
+ return [[NSString alloc] initWithCString:"flag a leak"];
+ ^
+1 diagnostic generated.
+</pre>
+
+<h4 id="attr_cf_returns_retained">Attribute 'cf_returns_retained'
+(Clang-specific)</h4>
+
+<p>The GCC-style (Clang-specific) attribute 'cf_returns_retained' allows one to
+annotate an Objective-C method or C function as returning a retained Core
+Foundation object that the caller is responsible for releasing.
+
+<p><b>Placing on Objective-C methods</b>: With respect to Objective-C methods.,
+this attribute is identical in its behavior and usage to 'ns_returns_retained'
+except for the distinction of returning a Core Foundation object instead of a
+Cocoa object. This distinction is important for two reasons:</p>
+
+<ul>
+ <li>Core Foundation objects are not automatically managed by the Objective-C
+ garbage collector.</li>
+ <li>Because Core Foundation is a C API, the analyzer cannot always tell that a
+ pointer return value refers to a Core Foundation object. In contrast, it is
+ trivial for the analyzer to recognize if a pointer refers to a Cocoa object
+ (given the Objective-C type system).</p>
+</ul>
+
+<p><b>Placing on C functions</b>: When placing the attribute
+'cf_returns_retained' on the declarations of C functions, the analyzer
+interprets the function as:</p>
+
+<ol>
+ <li>Returning a Core Foundation Object</li>
+ <li>Treating the function as if it its name
+contained the keywords "create" or "copy". This means the
+returned object as a +1 retain count that must be released by the caller, either
+by sending a <tt>release</tt> message (via toll-free bridging to an Objective-C
+object pointer), calling <tt>CFRelease</tt> (or similar function), or using
+<tt>CFMakeCollectable</tt> to register the object with the Objective-C garbage
+collector.</li>
+</ol>
+
+<p><b>Example</b></p>
+
+<p>In this example, observe the difference in output when the code is compiled
+to not use garbage collection versus when it is compiled to only use garbage
+collection (<tt>-fobjc-gc-only</tt>).</p>
+
+<pre class="code_example">
+<span class="command">$ cat test.m</span>
+$ cat test.m
+#import <Cocoa/Cocoa.h>
+
+#ifndef CF_RETURNS_RETAINED
+#if __clang__
+<span class="code_highlight">#define CF_RETURNS_RETAINED __attribute__((cf_returns_retained))</span>
+#else
+#define CF_RETURNS_RETAINED
+#endif
+#endif
+
+ at interface MyClass : NSObject {}
+- (NSDate*) returnsCFRetained <span class="code_highlight">CF_RETURNS_RETAINED</span>;
+- (NSDate*) alsoReturnsRetained;
+- (NSDate*) returnsNSRetained <span class="code_highlight">NS_RETURNS_RETAINED</span>;
+ at end
+
+<span class="code_highlight">CF_RETURNS_RETAINED</span>
+CFDateRef returnsRetainedCFDate() {
+ return CFDateCreate(0, CFAbsoluteTimeGetCurrent());
+}
+
+ at implementation MyClass
+- (NSDate*) returnsCFRetained {
+ return (NSDate*) returnsRetainedCFDate(); // No leak.
+}
+
+- (NSDate*) alsoReturnsRetained {
+ return (NSDate*) returnsRetainedCFDate(); // Always report a leak.
+}
+
+- (NSDate*) returnsNSRetained {
+ return (NSDate*) returnsRetainedCFDate(); // Report a leak when using GC.
+}
+ at end
+
+<span class="command">$ clang --analyze test.m</span>
+test.m:28:20: warning: Potential leak of an object allocated on line 28
+ return (NSDate*) returnsRetainedCFDate(); // Always report a leak.
+ ^
+1 diagnostic generated.
+
+<span class="command">$ clang --analyze test.m <span class="code_highlight">-fobjc-gc-only</span></span>
+test.m:28:20: warning: Potential leak (when using garbage collection) of an object allocated on line 28
+ return (NSDate*) returnsRetainedCFDate(); // Always report a leak.
+ ^
+test.m:32:20: warning: Potential leak (when using garbage collection) of an object allocated on line 32
+ return (NSDate*) returnsRetainedCFDate(); // Report a leak when using GC.
+ ^
+2 diagnostics generated.
+</pre>
+
+<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
+<h2 id="custom_assertions">Custom Assertion Handlers</h2>
+<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
+
+<p>The analyzer exploits code assertions by pruning off paths where the
+assertion condition is false. The idea is capture any program invariants
+specified in the assertion that the developer may know but is not immediately
+apparent in the code itself. In this way assertions make implicit assumptions
+explicit in the code, which not only makes the analyzer more accurate when
+finding bugs, but can help others better able to understand your code as well.
+It can also help remove certain kinds of analyzer false positives by pruning off
+false paths.</p>
+
+<p>In order to exploit assertions, however, the analyzer must understand when it
+encounters an "assertion handler." Typically assertions are
+implemented with a macro, with the macro performing a check for the assertion
+condition and, when the check fails, calling an assertion handler. For example, consider the following code
+fragment:</p>
+
+<pre class="code_example">
+void foo(int *p) {
+ assert(p != NULL);
+}
+</pre>
+
+<p>When this code is preprocessed on Mac OS X it expands to the following:</p>
+
+<pre class="code_example">
+void foo(int *p) {
+ (__builtin_expect(!(p != NULL), 0) ? __assert_rtn(__func__, "t.c", 4, "p != NULL") : (void)0);
+}
+</pre>
+
+<p>In this example, the assertion handler is <tt>__assert_rtn</tt>. When called,
+most assertion handlers typically print an error and terminate the program. The
+analyzer can exploit such semantics by ending the analysis of a path once it
+hits a call to an assertion handler.</p>
+
+<p>The trick, however, is that the analyzer needs to know that a called function
+is an assertion handler; otherwise the analyzer might assume the function call
+returns and it will continue analyzing the path where the assertion condition
+failed. This can lead to false positives, as the assertion condition usually
+implies a safety condition (e.g., a pointer is not null) prior to performing
+some action that depends on that condition (e.g., dereferencing a pointer).</p>
+
+<p>The analyzer knows about several well-known assertion handlers, but can
+automatically infer if a function should be treated as an assertion handler if
+it is annotated with the 'noreturn' attribute or the (Clang-specific)
+'analyzer_noreturn' attribute.</p>
+
+<h4 id="attr_noreturn">Attribute 'noreturn'</h4>
+
+<p>The 'noreturn' attribute is a GCC-attribute that can be placed on the
+declarations of functions. It means exactly what its name implies: a function
+with a 'noreturn' attribute should never return.</p>
+
+<p>Specific details of the syntax of using the 'noreturn' attribute can be found
+in <a
+href="http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html#index-g_t_0040code_007bnoreturn_007d-function-attribute-2264">GCC's
+documentation</a>.</p>
+
+<p>Not only does the analyzer exploit this information when pruning false paths,
+but the compiler also takes it seriously and will generate different code (and
+possibly better optimized) under the assumption that the function does not
+return.</p>
+
+<p><b>Example</b></p>
+
+<p>On Mac OS X, the function prototype for <tt>__assert_rtn</tt> (declared in
+<tt>assert.h</tt>) is specifically annotated with the 'noreturn' attribute:</p>
+
+<pre class="code_example">
+void __assert_rtn(const char *, const char *, int, const char *) <span class="code_highlight">__attribute__((__noreturn__))</span>;
+</pre>
+
+<h4 id="attr_analyzer_noreturn">Attribute 'analyzer_noreturn' (Clang-specific)</h4>
+
+<p>The Clang-specific 'analyzer_noreturn' attribute is almost identical to
+'noreturn' except that it is ignored by the compiler for the purposes of code
+generation.</p>
+
+<p>This attribute is useful for annotating assertion handlers that actually
+<em>can</em> return, but for the purpose of using the analyzer we want to
+pretend that such functions do not return.</p>
+
+<p>Because this attribute is Clang-specific, its use should be conditioned with
+the use of preprocessor macros.</p>
+
+<p><b>Example</b>
+
+<pre class="code_example">
+#ifndef CLANG_ANALYZER_NORETURN
+#if __clang__
+<span class="code_highlight">#define CLANG_ANALYZER_NORETURN __attribute__((analyzer_noreturn))</span>
+#else
+#define CLANG_ANALYZER_NORETURN
+#endif
+
+void my_assert_rtn(const char *, const char *, int, const char *) <span class="code_highlight">CLANG_ANALYZER_NORETURN</span>;
+</pre>
+
+</div>
+</body>
+</html>
+
Added: cfe/trunk/www/analyzer/available_checks.html
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/www/analyzer/available_checks.html?rev=73086&view=auto
==============================================================================
--- cfe/trunk/www/analyzer/available_checks.html (added)
+++ cfe/trunk/www/analyzer/available_checks.html Mon Jun 8 16:21:24 2009
@@ -0,0 +1,34 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+ <title>Available Checks</title>
+ <link type="text/css" rel="stylesheet" href="menu.css" />
+ <link type="text/css" rel="stylesheet" href="content.css" />
+</head>
+<body>
+
+<!--#include virtual="menu.html.incl"-->
+
+<div id="content">
+
+<h1>Available Checks</h1>
+
+<p>This page is slated to contain a list of the current checks the analyzer
+performs along with some self-contained code examples. In the meantime, please
+check out any of the following writeups about the analyzer that contain examples
+of some of the bugs that it finds:</p>
+
+<ul>
+<li><a href="http://www.mobileorchard.com/bug-finding-with-clang-5-resources-to-get-you-started/">Bug Finding With Clang: 5 Resources To Get You Started</a></li>
+<li><a href="http://fruitstandsoftware.com/blog/index.php/2008/08/finding-memory-leaks-with-the-llvmclang-static-analyzer/#comment-2">Finding Memory Leaks With The LLVM/Clang Static Analyzer</a></li>
+<li><a href="http://www.therareair.com/howto-static-analyze-your-objective-c-code-using-the-clang-static-analyzer-tool-gallery/">HOWTO: Static Analyze Your Objective-C Code Using the Clang Static Analyzer Tool Gallery</a></li>
+<li><a href="http://www.rogueamoeba.com/utm/2008/07/14/the-clang-static-analyzer/">Under the Microscope - The Clang Static Analyzer</a></li>
+<li><a href="http://www.mikeash.com/?page=pyblog/friday-qa-2009-03-06-using-the-clang-static-analyzer.html">Mike Ash - Using the Clang Static Analyzer</a></li>
+</ul>
+
+
+</div>
+</body>
+</html>
+
Added: cfe/trunk/www/analyzer/content.css
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/www/analyzer/content.css?rev=73086&view=auto
==============================================================================
--- cfe/trunk/www/analyzer/content.css (added)
+++ cfe/trunk/www/analyzer/content.css Mon Jun 8 16:21:24 2009
@@ -0,0 +1,31 @@
+html, body {
+ padding:0px;
+ font-size:small; font-family:"Lucida Grande", "Lucida Sans Unicode", Arial, Verdana, Helvetica, sans-serif; background-color: #fff; color: #222;
+ line-height:1.5;
+}
+
+h1, h2, h3, tt { color: #000 }
+
+h1 { padding-top:0px; margin-top:0px;}
+h2 { color:#333333; padding-top:0.5em; }
+h3 { padding-top: 0.5em; margin-bottom: -0.25em; color:#2d58b7 }
+h4 { color:#2d58b7 }
+li { padding-bottom: 0.5em }
+ul { padding-left:1.5em; }
+
+.command { font-weight:bold }
+.code_highlight { font-weight:bold; color:#2d58b7 }
+.code_example { border-width:1px; border-style:solid; border-color:#cccccc;
+ background-color:#eeeeee; padding:10px }
+
+/* Slides */
+IMG.img_slide {
+ display: block;
+ margin-left: auto;
+ margin-right: auto
+}
+
+.itemTitle { color:#2d58b7 }
+
+/* Tables */
+tr { vertical-align:top }
Added: cfe/trunk/www/analyzer/filing_bugs.html
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/www/analyzer/filing_bugs.html?rev=73086&view=auto
==============================================================================
--- cfe/trunk/www/analyzer/filing_bugs.html (added)
+++ cfe/trunk/www/analyzer/filing_bugs.html Mon Jun 8 16:21:24 2009
@@ -0,0 +1,62 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+ <title>Filing Bugs and Feature Requests</title>
+ <link type="text/css" rel="stylesheet" href="menu.css" />
+ <link type="text/css" rel="stylesheet" href="content.css" />
+</head>
+<body>
+
+<!--#include virtual="menu.html.incl"-->
+
+<div id="content">
+
+<h1>Filing Bugs and Feature Requests</h1>
+
+<p>We encourage users to file bug reports for any problems that they encounter.
+We also welcome feature requests. When filing a bug report, please do the
+following:</p>
+
+<ul>
+
+<li>Include the checker build (for prebuilt Mac OS X binaries) or the SVN
+revision number.</li>
+
+<li>Provide a self-contained, reduced test case that exhibits the issue you are
+experiencing.</li>
+
+<li>Test cases don't tell us everything. Please briefly describe the problem you
+are seeing, including what you thought should have been the expected behavior
+and why.</li>
+
+</ul>
+
+<h2>Outside of Apple</h2>
+
+<h3>Bugzilla</h3>
+
+<p>Please <a href="http://llvm.org/bugs/enter_bug.cgi?product=clang">file
+bugs</a> in LLVM's Bugzilla database against the Clang <b>Static Analyzer</b>
+component.</p>
+
+<h3>Bugreporter.apple.com</h3>
+
+<p>If you are using the analyzer to analyze code associated with an Apple NDA
+(e.g., preview versions of SDKs or seed releases of Mac OS X) please file bug
+reports to Apple's <a href="http://bugreporter.apple.com">Bug Reporter</a> web
+site.</p>
+
+<p>You are free to always file bugs through this website, but this option less
+attractive than filing bug reports through Bugzilla as not everyone who works on
+the analyzer has access to that bug database.</p>
+
+<h2>Apple-internal Users</h2>
+
+<p>Please file bugs in Radar against the <b>llvm - checker</b> component.</p>
+
+
+</div>
+</body>
+</html>
+
Added: cfe/trunk/www/analyzer/index.html
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/www/analyzer/index.html?rev=73086&view=auto
==============================================================================
--- cfe/trunk/www/analyzer/index.html (added)
+++ cfe/trunk/www/analyzer/index.html Mon Jun 8 16:21:24 2009
@@ -0,0 +1,186 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+ <title>Clang Static Analyzer</title>
+ <link type="text/css" rel="stylesheet" href="menu.css" />
+ <link type="text/css" rel="stylesheet" href="content.css" />
+</head>
+<body>
+
+<!--#include virtual="menu.html.incl"-->
+
+<div id="content">
+
+<h1>Clang Static Analyzer</h1>
+
+<p>The Clang Static Analyzer consists of both a source code analysis framework
+and a standalone tool that finds bugs in C and Objective-C programs. The
+standalone tool is invoked from the command-line, and is intended to run in
+tandem with a build of a project or code base.</p>
+
+<p>Both are 100% open source and are part of the <a
+href="http://clang.llvm.org">Clang</a> project.</p>
+
+<!-- Generated from: http://www.spiffycorners.com/index.php -->
+
+<style type="text/css">
+.spiffy{display:block}
+.spiffy *{
+ display:block;
+ height:1px;
+ overflow:hidden;
+ font-size:.01em;
+ background:#EBF0FA}
+.spiffy1{
+ margin-left:3px;
+ margin-right:3px;
+ padding-left:1px;
+ padding-right:1px;
+ border-left:1px solid #f6f8fc;
+ border-right:1px solid #f6f8fc;
+ background:#f0f3fb}
+.spiffy2{
+ margin-left:1px;
+ margin-right:1px;
+ padding-right:1px;
+ padding-left:1px;
+ border-left:1px solid #fdfdfe;
+ border-right:1px solid #fdfdfe;
+ background:#eef2fa}
+.spiffy3{
+ margin-left:1px;
+ margin-right:1px;
+ border-left:1px solid #eef2fa;
+ border-right:1px solid #eef2fa;}
+.spiffy4{
+ border-left:1px solid #f6f8fc;
+ border-right:1px solid #f6f8fc}
+.spiffy5{
+ border-left:1px solid #f0f3fb;
+ border-right:1px solid #f0f3fb}
+.spiffyfg{
+ background:#EBF0FA}
+
+.spiffyfg h2 {
+ margin:0px; padding:10px;
+}
+</style>
+
+<style type="text/css">
+ #left { float:left; }
+ #left h2 { margin:1px; padding-top:0px; }
+ #right { float:left; margin-left:20px; margin-right:20px; padding:0px ;}
+ #right h2 { padding:0px; margin:0px; }
+ #wrappedcontent { padding:15px;}
+</style>
+
+<div style="padding:0px">
+ <b class="spiffy">
+ <b class="spiffy1"><b></b></b>
+ <b class="spiffy2"><b></b></b>
+ <b class="spiffy3"></b>
+ <b class="spiffy4"></b>
+ <b class="spiffy5"></b></b>
+ <div class="spiffyfg">
+ <div style="padding:15px">
+ <h2 style="padding:0px; margin:0px">Download</h2>
+ <h3 style="margin-top:5px">Mac OS X</h3>
+ <ul>
+ <li>Latest build (Universal binary, 10.5+):
+ <!--#include virtual="latest_checker.html.incl"-->
+ </li>
+ <li><a href="/installation.html">Installation</a> and <a
+ href="/scan-build.html">usage</a></li>
+ </ul>
+ <h3>Other Platforms</h3>
+ <p>For other platforms, please follow the instructions for <a
+ href="/installation#OtherPlatforms">building the analyzer</a> from
+ source code.<p>
+ </div>
+ </div>
+ <b class="spiffy">
+ <b class="spiffy5"></b>
+ <b class="spiffy4"></b>
+ <b class="spiffy3"></b>
+ <b class="spiffy2"><b></b></b>
+ <b class="spiffy1"><b></b></b></b>
+</div>
+
+<h2 id="StaticAnalysis">What is Static Analysis?</h2>
+
+<p>The term "static analysis" is conflated, but here we use it to mean
+a collection of algorithms and techniques used to analyze source code in order
+to automatically find bugs. The idea is similar in spirit to compiler warnings
+(which can be useful for finding coding errors) but to take that idea a step
+further and find bugs that are traditionally found using run-time debugging
+techniques such as testing.</p>
+
+<p>Static analysis bug-finding tools have evolved over the last several decades
+from basic syntactic checkers to those that find deep bugs by reasoning about
+the semantics of code. The goal of the Clang Static Analyzer is to provide a
+industrial-quality static analysis framework for analyzing C and Objective-C
+programs that is freely available, extensible, and has a high quality of
+implementation.</p>
+
+<h3 id="Clang">Part of Clang and LLVM</h3>
+
+<p>As its name implies, the Clang Static Analyzer is built on top of <a
+href="http://clang.llvm.org">Clang</a> and <a href="http://llvm.org">LLVM</a>.
+Strictly speaking, the analyzer is part of Clang, as Clang consists of a set of
+reusable C++ libraries for building powerful source-level tools. The static
+analysis engine used by the Clang Static Analyzer is a Clang library, and has
+the capability to be reused in different contexts and by different clients.</p>
+
+<h2>Important Points to Consider</h2>
+
+<p>While we believe that the static analyzer is already very useful for finding
+bugs, we ask you to bear in mind a few points when using it.</p>
+
+<h3>Work-in-Progress</h3>
+
+<p>The analyzer is a continuous work-in-progress.
+There are many planned enhancements to improve both the precision and scope of
+its analysis algorithms as well as the kinds bugs it will find. While there are
+fundamental limitations to what static analysis can do, we have a long way to go
+before hitting that wall.</p>
+
+<h3>Slower than Compilation</h3>
+
+<p>Operationally, using static analysis to
+automatically find deep program bugs is about trading CPU time for the hardening
+of code. Because of the deep analysis performed by state-of-the-art static
+analysis tools, static analysis can be much slower than compilation.</p>
+
+<p>While the Clang Static Analyzer is being designed to be as fast and
+light-weight as possible, please do not expect it to be as fast as compiling a
+program (even with optimizations enabled). Some of the algorithms needed to find
+bugs require in the worst case exponential time.</p>
+
+<p>The Clang Static Analyzer runs in a reasonable amount of time by both
+bounding the amount of checking work it will do as well as using clever
+algorithms to reduce the amount of work it must do to find bugs.</p></li>
+
+<h3>False Positives</h3>
+
+<p>Static analysis is not perfect. It can falsely flag bugs in a program where
+the code behaves correctly. Because some code checks require more analysis
+precision than others, the frequency of false positives can vary widely between
+different checks. Our long-term goal is to have the analyzer have a low false
+positive rate for most code on all checks.</p>
+
+<p>Please help us in this endeavor by <a href="filing_bugs.html">reporting false
+positives</a>. False positives cannot be addressed unless we know about
+them.</p>
+
+<h3>More Checks</h3>
+
+<p>Static analysis not magic; a static analyzer can only find bugs that it has
+been specifically engineered to find. If there are specific kinds of bugs you
+would like the Clang Static Analyzer to find, please feel free to file <a
+href="filing_bugs.html">feature requests</a> or contribute your own patches.</p>
+
+</div>
+</body>
+</html>
+
Added: cfe/trunk/www/analyzer/installation.html
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/www/analyzer/installation.html?rev=73086&view=auto
==============================================================================
--- cfe/trunk/www/analyzer/installation.html (added)
+++ cfe/trunk/www/analyzer/installation.html Mon Jun 8 16:21:24 2009
@@ -0,0 +1,113 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+ <title>Obtaining the Static Analyzer</title>
+ <link type="text/css" rel="stylesheet" href="menu.css" />
+ <link type="text/css" rel="stylesheet" href="content.css" />
+</head>
+<body>
+
+<!--#include virtual="menu.html.incl"-->
+
+<div id="content">
+
+<h1>Obtaining the Static Analyzer</h1>
+
+<p>This page describes how to download and install the analyzer. Once
+the analyzer is installed, follow the <a
+href="/scan-build.html">instructions</a> on using <tt>scan-build</tt> to
+get started analyzing your code.</p>
+
+<h2>Packaged Builds (Mac OS X)</h2>
+
+<p>Semi-regular pre-built binaries of the analyzer are available on Mac
+OS X. These are built to run on Mac OS 10.5 and later.</p>
+
+<p>Builds are released frequently. Often the differences between build
+numbers being a few bug fixes or minor feature improvements. When using
+the analyzer, we recommend that you check back here occasionally for new
+builds, especially if the build you are using is more than a couple
+weeks old.</p>
+
+<p>The latest build is:
+ <!--#include virtual="latest_checker.html.incl"-->
+</p>
+
+<p>Packaged builds for other platforms may eventually be provided, but
+we need volunteers who are willing to help provide such regular builds.
+If you wish to help contribute regular builds of the analyzer on other
+platforms, please email the <a
+href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev">Clang
+Developers' mailing list</a>.</p>
+
+<h3>Using Packaged Builds</h3>
+
+<p>To use a package build, simply unpack it anywhere. If the build
+archive has the name <b><tt>checker-XXX.tar.bz2</tt></b> then the
+archive will expand to a directory called <b><tt>checker-XXX</tt></b>.
+You do not need to place this directory or the contents of this
+directory in any special place. Uninstalling the analyzer is as simple
+as deleting this directory.</p>
+
+<p>Most of the files in the <b><tt>checker-XXX</tt></b> directory will
+be supporting files for the analyzer that you can simply ignore. Most
+users will only care about two files, which are located at the top of
+the <b><tt>checker-XXX</tt></b> directory:</p>
+
+<ul>
+<li><b>scan-build</b>: <tt>scan-build</tt> is the high-level command line utility for running the analyzer</li>
+<li><b>scan-view</b>: <tt>scan-view</tt> a companion comannd line
+utility to <tt>scan-build</tt>, <tt>scan-view</tt> is used to view
+analysis results generated by <tt>scan-build</tt>. There is an option
+that one can pass to <tt>scan-build</tt> to cause <tt>scan-view</tt> to
+run as soon as it the analysis of a build completes</li>
+</ul>
+
+<h4>Running scan-build</h4>
+
+<p>For specific details on using <tt>scan-build</tt>, please see
+<tt>scan-build</tt>'s <a href="/scan-build">documentation</a>.</p>
+
+<p>To run <tt>scan-build</tt>, either add the
+<b><tt>checker-XXX</tt></b> directory to your path or specify a complete
+path for <tt>scan-build</tt> when running it. It is also possible to use
+a symbolic link to <tt>scan-build</tt>, such one located in a directory
+in your path. When <tt>scan-build</tt> runs it will automatically
+determine where to find its accompanying files.</p>
+
+<h2 id="OtherPlatforms">Other Platforms (Building the Analyzer from Source)</h2>
+
+<p>For other platforms, you must build Clang and LLVM manually. To do
+so, please follow the instructions for <a
+href="http://clang.llvm.org/get_started.html#build">building Clang from
+source code</a>.<p>
+
+<p>Once the Clang is built, you need to add the following to your path:</p>
+
+<ul>
+
+<li>The locations of the <tt>clang-cc</tt> and <tt>clang</tt> binaries.
+
+<p>For example, if you built a <em>Debug</em> build of LLVM/Clang, the
+resultant binaries will be in $(OBJDIR)/Debug (where <tt>$(OBJDIR)</tt>
+is often the same as the root source directory). You can also do
+<tt>make install</tt> to install the LLVM/Clang libaries and binaries to
+the installation directory of your choice (specified when you run
+<tt>configure</tt>).</p></li>
+
+<li>The locations of the <tt>scan-build</tt> and <tt>scan-view</tt>
+programs.
+
+<p>Currently these are not installed using <tt>make install</tt>, and
+are located in <tt>$(SRCDIR)/tools/clang/util</tt> and
+<tt>$(SRCDIR)/tools/clang/tools/scan-view</tt> respectively (where
+<tt>$(SRCDIR)</tt> is the root LLVM source directory). These locations
+are subject to change.</p></li>
+
+</ul>
+
+</div>
+</body>
+</html>
+
Added: cfe/trunk/www/analyzer/latest_checker.html.incl
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/www/analyzer/latest_checker.html.incl?rev=73086&view=auto
==============================================================================
--- cfe/trunk/www/analyzer/latest_checker.html.incl (added)
+++ cfe/trunk/www/analyzer/latest_checker.html.incl Mon Jun 8 16:21:24 2009
@@ -0,0 +1 @@
+<b><a href="http://checker.minormatter.com/checker-0.209.tar.bz2">checker-0.209.tar.bz2</a></b> (built May 18, 2009)
Added: cfe/trunk/www/analyzer/menu.css
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/www/analyzer/menu.css?rev=73086&view=auto
==============================================================================
--- cfe/trunk/www/analyzer/menu.css (added)
+++ cfe/trunk/www/analyzer/menu.css Mon Jun 8 16:21:24 2009
@@ -0,0 +1,39 @@
+/***************/
+/* page layout */
+/***************/
+
+[id=menu] {
+ position:fixed;
+ width:25ex;
+}
+[id=content] {
+ /* ***** EDIT THIS VALUE IF CONTENT OVERLAPS MENU ***** */
+ position:absolute;
+ left:29ex;
+ padding-right:4ex;
+}
+
+/**************/
+/* menu style */
+/**************/
+
+#menu .submenu {
+ padding-top:1em;
+ display:block;
+}
+
+#menu label {
+ display:block;
+ font-weight: bold;
+ text-align: center;
+ background-color: rgb(192,192,192);
+}
+#menu a {
+ padding:0 .2em;
+ display:block;
+ text-align: center;
+ background-color: rgb(235,235,235);
+}
+#menu a:visited {
+ color:rgb(100,50,100);
+}
\ No newline at end of file
Added: cfe/trunk/www/analyzer/menu.html.incl
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/www/analyzer/menu.html.incl?rev=73086&view=auto
==============================================================================
--- cfe/trunk/www/analyzer/menu.html.incl (added)
+++ cfe/trunk/www/analyzer/menu.html.incl Mon Jun 8 16:21:24 2009
@@ -0,0 +1,28 @@
+<div id="menu">
+ <div>
+ <a href="http://llvm.org/">LLVM Home</a>
+ <a href="http://clang.llvm.org/">Clang Home</a>
+ </div>
+
+ <div class="submenu">
+ <label>Quick Links</label>
+ <a href="/index.html">About the Analyzer</a>
+ <a href="/filing_bugs.html">Filing Bugs</a>
+ </div>
+
+ <div class="submenu">
+ <label>User Manual</label>
+<!-- <a href="/design_philosphy.html">Design Philosophy</a> -->
+ <a href="/installation.html">Obtaining the Analyzer</a>
+ <a href="/scan_build.html">Running the Analyzer</tt></a>
+ <a href="/available_checks.html">Available Checks</a>
+<!-- <a href="/false_positives.html">False Positives</a> -->
+ <a href="/annotations.html">Source-level Annotations</a>
+ </div>
+
+ <div class="submenu">
+ <label>Clang Mailing Lists</label>
+ <a href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev">cfe-dev</a>
+ <a href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits">cfe-commits</a>
+ </div>
+</div>
Added: cfe/trunk/www/analyzer/scan-build.html
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/www/analyzer/scan-build.html?rev=73086&view=auto
==============================================================================
--- cfe/trunk/www/analyzer/scan-build.html (added)
+++ cfe/trunk/www/analyzer/scan-build.html Mon Jun 8 16:21:24 2009
@@ -0,0 +1,257 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+ <title>Running the Analyzer</title>
+ <link type="text/css" rel="stylesheet" href="menu.css" />
+ <link type="text/css" rel="stylesheet" href="content.css" />
+ <style>
+ thead {
+ background-color:#eee; color:#666666;
+ font-weight: bold; cursor: default;
+ text-align:center;
+ border-top: 2px solid #cccccc;
+ border-bottom: 2px solid #cccccc;
+ font-weight: bold; font-family: Verdana
+ }
+ table { border: 1px #cccccc solid }
+ table { border-collapse: collapse; border-spacing: 0px }
+ table { margin-left:0px; margin-top:20px; margin-bottom:20px }
+ td { border-bottom: 1px #cccccc dotted }
+ td { padding:5px; padding-left:8px; padding-right:8px }
+ td { text-align:left; font-size:9pt }
+ td.View { padding-left: 10px }
+ </style>
+</head>
+<body>
+
+<!--#include virtual="menu.html.incl"-->
+
+<div id="content">
+
+<h1>Running the Analyzer</h1>
+
+<p>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. There
+are essentially two commands one can use the run the analyzer:</p>
+
+<ul>
+<li><b>scan-build</b>: The <tt>scan-build</tt> command can be used to analyze
+an entire project.</li>
+<li><b>clang</b>: The <tt>clang</tt> command is both Clang's compiler and
+static analysis driver. This can be used both to compile and analyze
+individual source files.
+</ul>
+
+<h3>Contents</h3>
+
+<ul>
+<li><a href="#scanbuild">scan-build</a></li>
+ <ul>
+ <li><a href="#scanbuild_basicusage">Basic Usage</a></li>
+ <li><a href="#scanbuild_otheroptions">Other Options</a></li>
+ <li><a href="#scanbuild_output">Output of scan-build</a></li>
+ </ul>
+<li><a href="#recommendedguidelines">Recommended Usage Guidelines</a></li>
+ <ul>
+ <li><a href="#recommended_debug">Always Analyze a Project in its "Debug" Configuration</a></li>
+ <li><a href="#recommended_verbose">Use Verbose Output when Debugging scan-build</a></li>
+ <li><a href="#recommended_autoconf">Run './configure' through scan-build</a></li>
+ </ul>
+</ul>
+
+<h2 id="scanbuild">scan-build</h2>
+
+<p>The <tt>scan-build</tt> 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 <tt>scan-build</tt>, you will use <tt>scan-build</tt> to analyze
+the source files compiled by <tt>gcc</tt> during a project build. This means
+that any files that are not compiled will also not be analyzed.</p>
+
+<h3 id="scanbuild_basicusage">Basic Usage</h3>
+
+<p>Basic usage of <tt>scan-build</tt> is designed to be simple: just place the
+word "scan-build" in front of your build command:</p>
+
+<pre class="code_example">
+$ <span class="code_highlight">scan-build</span> make
+$ <span class="code_highlight">scan-build</span> xcodebuild
+</pre>
+
+<p>In the first case <tt>scan-build</tt> analyzes the code of a project built
+with <tt>make</tt> and in the second case <tt>scan-build</tt> analyzes a project
+built using <tt>xcodebuild</tt>.<p>
+
+<p>Here is the general format for invoking <tt>scan-build</tt>:</p>
+
+<pre class="code_example">
+$ <span class="code_highlight">scan-build</span> <i>[scan-build options]</i> <span class="code_highlight"><command></span> <i>[command options]</i>
+</pre>
+
+<p>Operationally, <tt>scan-build</tt> literally runs <command> with all of the
+subsequent options passed to it. For example, one can pass <nobr><tt>-j4</tt></nobr> to
+<tt>make</tt> get a parallel build over 4 cores:</p>
+
+<pre class="code_example">
+$ scan-build make <span class="code_highlight">-j4</span>
+</pre>
+
+<p>In almost all cases, <tt>scan-build</tt> makes no effort to interpret the
+options after the build command; it simply passes them through. In general,
+<tt>scan-build</tt> should support parallel builds, but <b>not distributed
+builds</b>.</p>
+
+<p>It is also possible to use <tt>scan-build</tt> to analyze specific
+files:</p>
+
+<pre class="code_example">
+ $ scan-build gcc -c <span class="code_highlight">t1.c t2.c</span>
+</pre>
+
+<p>This example causes the files <tt>t1.c</tt> and <tt>t2.c</tt> to be analyzed.
+</p>
+
+<h3 id="scanbuild_otheroptions">Other Options</h3>
+
+<p>As mentioned above, extra options can be passed to <tt>scan-build</tt>. These
+options prefix the build command. For example:</p>
+
+<pre class="code_example">
+ $ scan-build <span class="code_highlight">-k -V</span> make
+ $ scan-build <span class="code_highlight">-k -V</span> xcodebuild
+</pre>
+
+<p>Here is a subset of useful options:</p>
+
+<table>
+<thead><tr><td>Option</td><td>Description</td></tr></thead>
+
+<tr><td><b>-o</b></td><td>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 <tt>/tmp</tt> to store the
+reports.</td><tr>
+
+<tr><td><b>-h</b><br><i><nobr>(or no arguments)</nobr></i></td><td>Display all
+<tt>scan-build</tt> options.</td></tr>
+
+<tr><td><b>-k</b><br><nobr><b>--keep-going</b></nobr></td><td>Add a "keep on
+going" option to the specified build command. <p>This option currently supports
+<tt>make</tt> and <tt>xcodebuild</tt>.</p> <p>This is a convenience option; one
+can specify this behavior directly using build options.</p></td></tr>
+
+<tr><td><b>-v<b></td><td>Verbose output from scan-build and the analyzer. <b>A
+second and third "-v" increases verbosity</b>, and is useful for filing bug
+reports against the analyzer.</td></tr>
+
+<tr><td><b>-V</b></td><td>View analysis results in a web browser when the build
+command completes.</td></tr> </table>
+
+<p>A complete list of options can be obtained by running <tt>scan-build</tt>
+with no arguments.</p>
+
+<h3 id="scanbuild_output">Output of scan-build</h3>
+
+<p>
+The output of scan-build is a set of HTML files, each one which represents a
+separate bug report. A single <tt>index.html</tt> file is generated for
+surveying all of the bugs. You can then just open <tt>index.html</tt> in a web
+browser to view the bug reports.
+</p>
+
+<p>
+Where the HTML files are generated is specified with a <b>-o</b> option to
+<tt>scan-build</tt>. If <b>-o</b> isn't specified, a directory in <tt>/tmp</tt>
+is created to store the files (<tt>scan-build</tt> will print a message telling
+you where they are). If you want to view the reports immediately after the build
+completes, pass <b>-V</b> to <tt>scan-build</tt>.
+</p>
+
+
+<h2 id="recommendedguidelines">Recommended Usage Guidelines</h2>
+
+<p>This section describes a few recommendations with running the analyzer.</p>
+
+<h3 id="recommended_debug">Always Analyze a Project in its "Debug" Configuration</h3>
+
+<p>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.</p>
+
+<h3 id="recommend_verbose">Use Verbose Output when Debugging scan-build</h3>
+
+<p><tt>scan-build</tt> takes a <b>-v</b> option to emit verbose output about
+what it's doing; two <b>-v</b> options emit more information. Redirecting the
+output of <tt>scan-build</tt> to a text file (make sure to redirect standard
+error) is useful for filing bug reports against <tt>scan-build</tt> 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.</p>
+
+<h3 id="recommended_autoconf">Run './configure' through scan-build</h3>
+
+<p>If an analyzed project uses an autoconf generated <tt>configure</tt> script,
+you will probably need to run <tt>configure</tt> script through
+<tt>scan-build</tt> in order to analyze the project.</p>
+
+<p><b>Example</b></p>
+
+<pre class="code_example">
+$ scan-build ./configure
+$ scan-build make
+</pre>
+
+<p>The reason <tt>configure</tt> also needs to be run through
+<tt>scan-build</tt> is because <tt>scan-build</tt> scans your source files by
+<i>interposing</i> on the compiler. This interposition is currently done by
+<tt>scan-build</tt> temporarily setting the environment variable <tt>CC</tt> to
+<tt>ccc-analyzer</tt>. The program <tt>ccc-analyzer</tt> acts like a fake
+compiler, forwarding its command line arguments over to <tt>gcc</tt> to perform
+regular compilation and <tt>clang</tt> to perform static analysis.</p>
+
+<p>Running <tt>configure</tt> typically generates makefiles that have hardwired
+paths to the compiler, and by running <tt>configure</tt> through
+<tt>scan-build</tt> that path is set to <tt>ccc-analyzer</tt>.</p.>
+
+<!--
+<h2 id="Debugging">Debugging the Analyzer</h2>
+
+<p>This section provides information on debugging the analyzer, and troubleshooting
+it when you have problems analyzing a particular project.</p>
+
+<h3>How it Works</h3>
+
+<p>To analyze a project, <tt>scan-build</tt> simply sets the environment variable
+<tt>CC</tt> to the full path to <tt>ccc-analyzer</tt>. It also sets a few other
+environment variables to communicate to <tt>ccc-analyzer</tt> where to dump HTML
+report files.</p>
+
+<p>Some Makefiles (or equivalent project files) hardcode the compiler; for such
+projects simply overriding <tt>CC</tt> won't cause <tt>ccc-analyzer</tt> to be
+called. This will cause the compiled code <b>to not be analyzed.</b></p> If you
+find that your code isn't being analyzed, check to see if <tt>CC</tt> is
+hardcoded. If this is the case, you can hardcode it instead to the <b>full
+path</b> to <tt>ccc-analyzer</tt>.</p>
+
+<p>When applicable, you can also run <tt>./configure</tt> for a project through
+<tt>scan-build</tt> so that configure sets up the location of <tt>CC</tt> based
+on the environment passed in from <tt>scan-build</tt>:
+
+<pre>
+ $ scan-build <b>./configure</b>
+</pre>
+
+<p><tt>scan-build</tt> has special knowledge about <tt>configure</tt>, so it in
+most cases will not actually analyze the configure tests run by
+<tt>configure</tt>.</p>
+
+<p>Under the hood, <tt>ccc-analyzer</tt> directly invokes <tt>gcc</tt> to
+compile the actual code in addition to running the analyzer (which occurs by it
+calling <tt>clang</tt>). <tt>ccc-analyzer</tt> tries to correctly forward all
+the arguments over to <tt>gcc</tt>, but this may not work perfectly (please
+report bugs of this kind).
+ -->
+
+</div>
+</body>
+</html>
+
More information about the cfe-commits
mailing list