diff options
| -rw-r--r-- | www/analyzer/annotations.html | 383 | ||||
| -rw-r--r-- | www/analyzer/available_checks.html | 34 | ||||
| -rw-r--r-- | www/analyzer/content.css | 31 | ||||
| -rw-r--r-- | www/analyzer/filing_bugs.html | 62 | ||||
| -rw-r--r-- | www/analyzer/index.html | 186 | ||||
| -rw-r--r-- | www/analyzer/installation.html | 113 | ||||
| -rw-r--r-- | www/analyzer/latest_checker.html.incl | 1 | ||||
| -rw-r--r-- | www/analyzer/menu.css | 39 | ||||
| -rw-r--r-- | www/analyzer/menu.html.incl | 28 | ||||
| -rw-r--r-- | www/analyzer/scan-build.html | 257 |
10 files changed, 1134 insertions, 0 deletions
diff --git a/www/analyzer/annotations.html b/www/analyzer/annotations.html new file mode 100644 index 0000000000..4c05c50682 --- /dev/null +++ b/www/analyzer/annotations.html @@ -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 + +@interface MyClass : NSObject {} +- (NSString*) returnsRetained <span class="code_highlight">NS_RETURNS_RETAINED</span>; +- (NSString*) alsoReturnsRetained; +@end + +@implementation MyClass +- (NSString*) returnsRetained { + return [[NSString alloc] initWithCString:"no leak here"]; +} +- (NSString*) alsoReturnsRetained { + return [[NSString alloc] initWithCString:"flag a leak"]; +} +@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 + +@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>; +@end + +<span class="code_highlight">CF_RETURNS_RETAINED</span> +CFDateRef returnsRetainedCFDate() { + return CFDateCreate(0, CFAbsoluteTimeGetCurrent()); +} + +@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. +} +@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> + diff --git a/www/analyzer/available_checks.html b/www/analyzer/available_checks.html new file mode 100644 index 0000000000..5e74fd8ea2 --- /dev/null +++ b/www/analyzer/available_checks.html @@ -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> + diff --git a/www/analyzer/content.css b/www/analyzer/content.css new file mode 100644 index 0000000000..01a3af2a6c --- /dev/null +++ b/www/analyzer/content.css @@ -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 } diff --git a/www/analyzer/filing_bugs.html b/www/analyzer/filing_bugs.html new file mode 100644 index 0000000000..1ce02bee92 --- /dev/null +++ b/www/analyzer/filing_bugs.html @@ -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> + diff --git a/www/analyzer/index.html b/www/analyzer/index.html new file mode 100644 index 0000000000..d180e830e1 --- /dev/null +++ b/www/analyzer/index.html @@ -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> + diff --git a/www/analyzer/installation.html b/www/analyzer/installation.html new file mode 100644 index 0000000000..8913535621 --- /dev/null +++ b/www/analyzer/installation.html @@ -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> + diff --git a/www/analyzer/latest_checker.html.incl b/www/analyzer/latest_checker.html.incl new file mode 100644 index 0000000000..90d444a40b --- /dev/null +++ b/www/analyzer/latest_checker.html.incl @@ -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) diff --git a/www/analyzer/menu.css b/www/analyzer/menu.css new file mode 100644 index 0000000000..6e96a457ab --- /dev/null +++ b/www/analyzer/menu.css @@ -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; +} + |