diff options
| author | Zancanaro; Carlo <czan8762@plang3.cs.usyd.edu.au> | 2012-09-24 09:58:17 +1000 |
|---|---|---|
| committer | Zancanaro; Carlo <czan8762@plang3.cs.usyd.edu.au> | 2012-09-24 09:58:17 +1000 |
| commit | 222e2a7620e6520ffaf4fc4e69d79c18da31542e (patch) | |
| tree | 7bfbc05bfa3b41c8f9d2e56d53a0bc3e310df239 /clang/www/analyzer | |
| parent | 3d206f03985b50beacae843d880bccdc91a9f424 (diff) | |
Add the clang library to the repo (with some of my changes, too).
Diffstat (limited to 'clang/www/analyzer')
26 files changed, 2415 insertions, 0 deletions
diff --git a/clang/www/analyzer/annotations.html b/clang/www/analyzer/annotations.html new file mode 100644 index 0000000..9e3583d --- /dev/null +++ b/clang/www/analyzer/annotations.html @@ -0,0 +1,602 @@ +<!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"> + <script type="text/javascript" src="scripts/menu.js"></script> +</head> +<body> + +<div id="page"> +<!--#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> + +<h4>Specific Topics</h4> + +<ul> +<li><a href="#generic">Annotations to Enhance Generic Checks</a> + <ul> + <li><a href="#null_checking"><span>Null Pointer Checking</span></a> + <ul> + <li><a href="#attr_nonnull"><span>Attribute 'nonnull'</span></a></li> + </ul> + </li> + </ul> +</li> +<li><a href="#macosx">Mac OS X API Annotations</a> + <ul> + <li><a href="#cocoa_mem">Cocoa & Core Foundation Memory Management Annotations</a> + <ul> + <li><a href="#attr_ns_returns_retained">Attribute 'ns_returns_retained'</a></li> + <li><a href="#attr_ns_returns_not_retained">Attribute 'ns_returns_not_retained'</a></li> + <li><a href="#attr_cf_returns_retained">Attribute 'cf_returns_retained'</a></li> + <li><a href="#attr_cf_returns_not_retained">Attribute 'cf_returns_not_retained'</a></li> + <li><a href="#attr_ns_consumed">Attribute 'ns_consumed'</a></li> + <li><a href="#attr_cf_consumed">Attribute 'cf_consumed'</a></li> + <li><a href="#attr_ns_consumes_self">Attribute 'ns_consumes_self'</a></li> + </ul> + </li> + </ul> +</li> +<li><a href="#custom_assertions">Custom Assertion Handlers</a> + <ul> + <li><a href="#attr_noreturn">Attribute 'noreturn'</a></li> + <li><a href="#attr_analyzer_noreturn">Attribute 'analyzer_noreturn'</a></li> + </ul> + </li> +</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); +} +</pre> + +<p>Running <tt>scan-build</tt> over this source produces the following +output:</p> + +<img src="images/example_attribute_nonnull.png" alt="example attribute nonnull"> + +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> +<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>, +--> +<p>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 contains 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 __has_feature // Optional. +#define __has_feature(x) 0 // Compatibility with non-clang compilers. +#endif + +#ifndef NS_RETURNS_RETAINED +#if __has_feature(attribute_ns_returns_retained) +<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 +</pre> + +<p>Running <tt>scan-build</tt> on this source file produces the following output:</p> + +<img src="images/example_ns_returns_retained.png" alt="example returns retained"> + +<h4 id="attr_ns_returns_not_retained">Attribute 'ns_returns_not_retained' +(Clang-specific)</h4> + +<p>The 'ns_returns_not_retained' attribute is the complement of '<a +href="#attr_ns_returns_retained">ns_returns_retained</a>'. Where a function or +method may appear to obey the Cocoa conventions and return a retained Cocoa +object, this attribute can be used to indicate that the object reference +returned should not be considered as an "owning" reference being +returned to the caller.</p> + +<p>Usage is identical to <a +href="#attr_ns_returns_retained">ns_returns_retained</a>. When using the +attribute, be sure to declare it within the proper macro that checks for +its availability, as it is not available in earlier versions of the analyzer:</p> + +<pre class="code_example"> +<span class="command">$ cat test.m</span> +#ifndef __has_feature // Optional. +#define __has_feature(x) 0 // Compatibility with non-clang compilers. +#endif + +#ifndef NS_RETURNS_NOT_RETAINED +#if __has_feature(attribute_ns_returns_not_retained) +<span class="code_highlight">#define NS_RETURNS_NOT_RETAINED __attribute__((ns_returns_not_retained))</span> +#else +#define NS_RETURNS_NOT_RETAINED +#endif +#endif +</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). +</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 __has_feature // Optional. +#define __has_feature(x) 0 // Compatibility with non-clang compilers. +#endif + +#ifndef CF_RETURNS_RETAINED +#if __has_feature(attribute_cf_returns_retained) +<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(); <b><i>// No leak.</i></b> +} + +- (NSDate*) alsoReturnsRetained { + return (NSDate*) returnsRetainedCFDate(); <b><i>// Always report a leak.</i></b> +} + +- (NSDate*) returnsNSRetained { + return (NSDate*) returnsRetainedCFDate(); <b><i>// Report a leak when using GC.</i></b> +} +@end +</pre> + +<p>Running <tt>scan-build</tt> on this example produces the following output:</p> + +<img src="images/example_cf_returns_retained.png" alt="example returns retained"> + +<p>When the above code is compiled using Objective-C garbage collection (i.e., +code is compiled with the flag <tt>-fobjc-gc</tt> or <tt>-fobjc-gc-only</tt>), +<tt>scan-build</tt> produces both the above error (with slightly different text +to indicate the code uses garbage collection) as well as the following warning, +which indicates a leak that occurs <em>only</em> when using garbage +collection:</p> + +<img src="images/example_cf_returns_retained_gc.png" alt="example returns retained gc"> + +<h4 id="attr_cf_returns_not_retained">Attribute 'cf_returns_not_retained' +(Clang-specific)</h4> + +<p>The 'cf_returns_not_retained' attribute is the complement of '<a +href="#attr_cf_returns_retained">cf_returns_retained</a>'. Where a function or +method may appear to obey the Core Foundation or Cocoa conventions and return +a retained Core Foundation object, this attribute can be used to indicate that +the object reference returned should not be considered as an +"owning" reference being returned to the caller.</p> + +<p>Usage is identical to <a +href="#attr_cf_returns_retained">cf_returns_retained</a>. When using the +attribute, be sure to declare it within the proper macro that checks for +its availability, as it is not available in earlier versions of the analyzer:</p> + +<pre class="code_example"> +<span class="command">$ cat test.m</span> +#ifndef __has_feature // Optional. +#define __has_feature(x) 0 // Compatibility with non-clang compilers. +#endif + +#ifndef CF_RETURNS_NOT_RETAINED +#if __has_feature(attribute_cf_returns_not_retained) +<span class="code_highlight">#define CF_RETURNS_NOT_RETAINED __attribute__((cf_returns_not_retained))</span> +#else +#define CF_RETURNS_NOT_RETAINED +#endif +#endif +</pre> + +<h4 id="attr_ns_consumed">Attribute 'ns_consumed' +(Clang-specific)</h4> + +<p>The 'ns_consumed' attribute can be placed on a specific parameter in either the declaration of a function or an Objective-C method. + It indicates to the static analyzer that a <tt>release</tt> message is implicitly sent to the parameter upon + completion of the call to the given function or method. + +<p><b>Important note when using Garbage Collection</b>: Note that the analyzer +essentially ignores this attribute when code is compiled to use Objective-C +garbage collection. This is because the <tt>release</tt> message does nothing +when using GC. If the underlying function/method uses something like +<tt>CFRelease</tt> to decrement the reference count, consider using +the <a href="#attr_cf_consumed">cf_consumed</a> attribute instead.</p> + +<p><b>Example</b></p> + +<pre class="code_example"> +<span class="command">$ cat test.m</span> +#ifndef __has_feature // Optional. +#define __has_feature(x) 0 // Compatibility with non-clang compilers. +#endif + +#ifndef NS_CONSUMED +#if __has_feature(attribute_ns_consumed) +<span class="code_highlight">#define NS_CONSUMED __attribute__((ns_consumed))</span> +#else +#define NS_CONSUMED +#endif +#endif + +void consume_ns(id <span class="code_highlight">NS_CONSUMED</span> x); + +void test() { + id x = [[NSObject alloc] init]; + consume_ns(x); <b><i>// No leak!</i></b> +} + +@interface Foo : NSObject ++ (void) releaseArg:(id) <span class="code_highlight">NS_CONSUMED</span> x; ++ (void) releaseSecondArg:(id)x second:(id) <span class="code_highlight">NS_CONSUMED</span> y; +@end + +void test_method() { + id x = [[NSObject alloc] init]; + [Foo releaseArg:x]; <b><i>// No leak!</i></b> +} + +void test_method2() { + id a = [[NSObject alloc] init]; + id b = [[NSObject alloc] init]; + [Foo releaseSecondArg:a second:b]; <b><i>// 'a' is leaked, but 'b' is released.</i></b> +} +</pre> + +<h4 id="attr_cf_consumed">Attribute 'cf_consumed' +(Clang-specific)</h4> + +<p>The 'cf_consumed' attribute is practically identical to <a href="#attr_ns_consumed">ns_consumed</a>. +The attribute can be placed on a specific parameter in either the declaration of a function or an Objective-C method. +It indicates to the static analyzer that the object reference is implicitly passed to a call to <tt>CFRelease</tt> upon +completion of the call to the given function or method.</p> + +<p>Operationally this attribute is nearly identical to ns_consumed +with the main difference that the reference count decrement still occurs when using Objective-C garbage +collection (which is import for Core Foundation types, which are not automatically garbage collected).</p> + +<p><b>Example</b></p> + +<pre class="code_example"> +<span class="command">$ cat test.m</span> +#ifndef __has_feature // Optional. +#define __has_feature(x) 0 // Compatibility with non-clang compilers. +#endif + +#ifndef CF_CONSUMED +#if __has_feature(attribute_cf_consumed) +<span class="code_highlight">#define CF_CONSUMED __attribute__((cf_consumed))</span> +#else +#define CF_CONSUMED +#endif +#endif + +void consume_cf(id <span class="code_highlight">CF_CONSUMED</span> x); +void consume_CFDate(CFDateRef <span class="code_highlight">CF_CONSUMED</span> x); + +void test() { + id x = [[NSObject alloc] init]; + consume_cf(x); <b><i>// No leak!</i></b> +} + +void test2() { + CFDateRef date = CFDateCreate(0, CFAbsoluteTimeGetCurrent()); + consume_CFDate(date); <b><i>// No leak, including under GC!</i></b> + +} + +@interface Foo : NSObject ++ (void) releaseArg:(CFDateRef) <span class="code_highlight">CF_CONSUMED</span> x; +@end + +void test_method() { + CFDateRef date = CFDateCreate(0, CFAbsoluteTimeGetCurrent()); + [Foo releaseArg:date]; <b><i>// No leak!</i></b> +} +</pre> + +<h4 id="attr_ns_consumes_self">Attribute 'ns_consumes_self' +(Clang-specific)</h4> + +<p>The 'ns_consumes_self' attribute can be placed only on an Objective-C method declaration. + It indicates that the receiver of the message is "consumed" (a single reference count decremented) + after the message is sent. This matches the semantics of all "init" methods. +</p> + +<p>One use of this attribute is declare your own init-like methods that do not follow the + standard Cocoa naming conventions.</p> + +<p><b>Example</b></p> + +<pre class="code_example"> +#ifndef __has_feature +#define __has_feature(x) 0 // Compatibility with non-clang compilers. +#endif + +#ifndef NS_CONSUMES_SELF +#if __has_feature((attribute_ns_consumes_self)) +<span class="code_highlight">#define NS_CONSUMES_SELF __attribute__((ns_consumes_self))</span> +#else +#define NS_CONSUMES_SELF +#endif +#endif + +@interface MyClass : NSObject +- initWith:(MyClass *)x; +- nonstandardInitWith:(MyClass *)x <span class="code_highlight">NS_CONSUMES_SELF</span> NS_RETURNS_RETAINED; +@end +</pre> + +<p>In this example, <tt>nonstandardInitWith:</tt> has the same ownership semantics as the init method <tt>initWith:</tt>. + The static analyzer will observe that the method consumes the receiver, and then returns an object with a +1 retain count.</p> + +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> +<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 __has_feature(attribute_analyzer_noreturn) +<span class="code_highlight">#define CLANG_ANALYZER_NORETURN __attribute__((analyzer_noreturn))</span> +#else +#define CLANG_ANALYZER_NORETURN +#endif +#endif + +void my_assert_rtn(const char *, const char *, int, const char *) <span class="code_highlight">CLANG_ANALYZER_NORETURN</span>; +</pre> + +</div> +</div> +</body> +</html> + diff --git a/clang/www/analyzer/available_checks.html b/clang/www/analyzer/available_checks.html new file mode 100644 index 0000000..3f40d32 --- /dev/null +++ b/clang/www/analyzer/available_checks.html @@ -0,0 +1,147 @@ +<!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"> + <script type="text/javascript" src="scripts/menu.js"></script> + <style type="text/css"> + tr:first-child { width:20%; } + </style> +</head> +<body> + +<div id="page"> +<!--#include virtual="menu.html.incl"--> + +<div id="content"> + +<h1>Available Checks</h1> + +<h3>The list of the checks the analyzer performs by default</h3> +<p> +<table border="0" cellpadding="3" cellspacing="3" width="100%"> +<!-- <tr> +<th><h4>Checker Name</h4></th> +<th><h4>Description</h4></th> +</tr>--> +<tr> +<td><b>core.AdjustedReturnValue</b></td><td>Check to see if the return value of a function call is different than the caller expects (e.g., from calls through function pointers).</td> +</tr> +<tr> +<td><b>core.AttributeNonNull</b></td><td>Check for null pointers passed as arguments to a function whose arguments are marked with the 'nonnull' attribute.</td> +</tr> +<tr> +<td><b>core.CallAndMessage</b></td><td>Check for logical errors for function calls and Objective-C message expressions (e.g., uninitialized arguments, null function pointers).</td> +</tr> +<tr> +<td><b>core.DivideZero</b></td><td>Check for division by zero.</td> +</tr> +<tr> +<td><b>core.NullDereference</b></td><td>Check for dereferences of null pointers.</td> +</tr> +<tr> +<td><b>core.StackAddressEscape</b></td><td>Check that addresses to stack memory do not escape the function.</td> +</tr> +<tr> +<td><b>core.UndefinedBinaryOperatorResult</b></td><td>Check for undefined results of binary operators.</td> +</tr> +<tr> +<td><b>core.VLASize</b></td><td>Check for declarations of VLA of undefined or zero size.</td> +</tr> +<tr> +<td><b>core.builtin.BuiltinFunctions</b></td><td>Evaluate compiler builtin functions (e.g., alloca()).</td> +</tr> +<tr> +<td><b>core.builtin.NoReturnFunctions</b></td><td>Evaluate "panic" functions that are known to not return to the caller.</td> +</tr> +<tr> +<td><b>core.uninitialized.ArraySubscript</b></td><td>Check for uninitialized values used as array subscripts.</td> +</tr> +<tr> +<td><b>core.uninitialized.Assign</b></td><td>Check for assigning uninitialized values.</td> +</tr> +<tr> +<td><b>core.uninitialized.Branch</b></td><td>Check for uninitialized values used as branch conditions.</td> +</tr> +<tr> +<td><b>core.uninitialized.CapturedBlockVariable</b></td><td>Check for blocks that capture uninitialized values.</td> +</tr> +<tr> +<td><b>core.uninitialized.UndefReturn</b></td><td>Check for uninitialized values being returned to the caller.</td> +</tr> +<tr> +<td><b>deadcode.DeadStores</b></td><td>Check for values stored to variables that are never read afterwards.</td> +</tr> +<tr> +<td><b>deadcode.IdempotentOperations</b></td><td>Warn about idempotent operations.</td> +</tr> +<tr> +<td><b>osx.API</b></td><td>Check for proper uses of various Mac OS X APIs.</td> +</tr> +<tr> +<td><b>osx.AtomicCAS</b></td><td>Evaluate calls to OSAtomic functions.</td> +</tr> +<tr> +<td><b>osx.SecKeychainAPI</b></td><td>Check for proper uses of Secure Keychain APIs.</td> +</tr> +<tr> +<td><b>osx.cocoa.AtSync</b></td><td>Check for null pointers used as mutexes for @synchronized.</td> +</tr> +<tr> +<td><b>osx.cocoa.ClassRelease</b></td><td>Check for sending 'retain', 'release', or 'autorelease' directly to a Class.</td> +</tr> +<tr> +<td><b>osx.cocoa.IncompatibleMethodTypes</b></td><td>Warn about Objective-C method signatures with type incompatibilities.</td> +</tr> +<tr> +<td><b>osx.cocoa.NSAutoreleasePool</b></td><td>Warn for suboptimal uses of NSAutoreleasePool in Objective-C GC mode.</td> +</tr> +<tr> +<td><b>osx.cocoa.NSError</b></td><td>Check usage of NSError** parameters.</td> +</tr> +<tr> +<td><b>osx.cocoa.NilArg</b></td><td>Check for prohibited nil arguments to ObjC method calls.</td> +</tr> +<tr> +<td><b>osx.cocoa.RetainCount</b></td><td>Check for leaks and improper reference count management.</td> +</tr> +<tr> +<td><b>osx.cocoa.UnusedIvars</b></td><td>Warn about private ivars that are never used.</td> +</tr> +<tr> +<td><b>osx.cocoa.VariadicMethodTypes</b></td><td>Check for passing non-Objective-C types to variadic methods that expect only Objective-C types.</td> +</tr> +<tr> +<td><b>osx.coreFoundation.CFError</b></td><td>Check usage of CFErrorRef* parameters.</td> +</tr> +<tr> +<td><b>osx.coreFoundation.CFNumber</b></td><td>Check for proper uses of CFNumberCreate.</td> +</tr> +<tr> +<td><b>osx.coreFoundation.CFRetainRelease</b></td><td>Check for null arguments to CFRetain/CFRelease.</td> +</tr> +<tr> +<td><b>unix.API</b></td><td>Check calls to various UNIX/Posix functions.</td> +</tr> +</table> + +<p>In addition to these the analyzer contains numerous experimental (beta) checkers.</p> + +<h3>Writeups with examples of some of the bugs that the analyzer finds</h3> + +<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> +</div> +</body> +</html> + diff --git a/clang/www/analyzer/checker_dev_manual.html b/clang/www/analyzer/checker_dev_manual.html new file mode 100644 index 0000000..fc9adf3 --- /dev/null +++ b/clang/www/analyzer/checker_dev_manual.html @@ -0,0 +1,346 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" + "http://www.w3.org/TR/html4/strict.dtd"> +<html> +<head> + <title>Checker Developer Manual</title> + <link type="text/css" rel="stylesheet" href="menu.css"> + <link type="text/css" rel="stylesheet" href="content.css"> + <script type="text/javascript" src="scripts/menu.js"></script> +</head> +<body> + +<div id="page"> +<!--#include virtual="menu.html.incl"--> + +<div id="content"> + +<h1 style="color:red">This Page Is Under Construction</h1> + +<h1>Checker Developer Manual</h1> + +<p>The static analyzer engine performs symbolic execution of the program and +relies on a set of checkers to implement the logic for detecting and +constructing bug reports. This page provides hints and guidelines for anyone +who is interested in implementing their own checker. The static analyzer is a +part of the Clang project, so consult <a href="http://clang.llvm.org/hacking.html">Hacking on Clang</a> +and <a href="http://llvm.org/docs/ProgrammersManual.html">LLVM Programmer's Manual</a> +for general developer guidelines and information. </p> + + <ul> + <li><a href="#start">Getting Started</a></li> + <li><a href="#analyzer">Analyzer Overview</a></li> + <li><a href="#idea">Idea for a Checker</a></li> + <li><a href="#registration">Checker Registration</a></li> + <li><a href="#skeleton">Checker Skeleton</a></li> + <li><a href="#node">Exploded Node</a></li> + <li><a href="#bugs">Bug Reports</a></li> + <li><a href="#ast">AST Visitors</a></li> + <li><a href="#testing">Testing</a></li> + <li><a href="#commands">Useful Commands</a></li> + </ul> + +<h2 id=start>Getting Started</h2> + <ul> + <li>To check out the source code and build the project, follow steps 1-4 of + the <a href="http://clang.llvm.org/get_started.html">Clang Getting Started</a> + page.</li> + + <li>The analyzer source code is located under the Clang source tree: + <br><tt> + $ <b>cd llvm/tools/clang</b> + </tt> + <br>See: <tt>include/clang/StaticAnalyzer</tt>, <tt>lib/StaticAnalyzer</tt>, + <tt>test/Analysis</tt>.</li> + + <li>The analyzer regression tests can be executed from the Clang's build + directory: + <br><tt> + $ <b>cd ../../../; cd build/tools/clang; TESTDIRS=Analysis make test</b> + </tt></li> + + <li>Analyze a file with the specified checker: + <br><tt> + $ <b>clang -cc1 -analyze -analyzer-checker=core.DivideZero test.c</b> + </tt></li> + + <li>List the available checkers: + <br><tt> + $ <b>clang -cc1 -analyzer-checker-help</b> + </tt></li> + + <li>See the analyzer help for different output formats, fine tuning, and + debug options: + <br><tt> + $ <b>clang -cc1 -help | grep "analyzer"</b> + </tt></li> + + </ul> + +<h2 id=analyzer>Static Analyzer Overview</h2> + The analyzer core performs symbolic execution of the given program. All the + input values are represented with symbolic values; further, the engine deduces + the values of all the expressions in the program based on the input symbols + and the path. The execution is path sensitive and every possible path through + the program is explored. The explored execution traces are represented with + <a href="http://clang.llvm.org/doxygen/classclang_1_1ento_1_1ExplodedGraph.html">ExplidedGraph</a> object. + Each node of the graph is + <a href="http://clang.llvm.org/doxygen/classclang_1_1ento_1_1ExplodedNode.html">ExplodedNode</a>, + which consists of a <tt>ProgramPoint</tt> and a <tt>ProgramState</tt>. + <p> + <a href="http://clang.llvm.org/doxygen/classclang_1_1ProgramPoint.html">ProgramPoint</a> + represents the corresponding location in the program (or the CFG graph). + <tt>ProgramPoint</tt> is also used to record additional information on + when/how the state was added. For example, <tt>PostPurgeDeadSymbolsKind</tt> + kind means that the state is the result of purging dead symbols - the + analyzer's equivalent of garbage collection. + <p> + <a href="http://clang.llvm.org/doxygen/classclang_1_1ento_1_1ProgramState.html">ProgramState</a> + represents abstract state of the program. It consists of: + <ul> + <li><tt>Environment</tt> - a mapping from source code expressions to symbolic + values + <li><tt>Store</tt> - a mapping from memory locations to symbolic values + <li><tt>GenericDataMap</tt> - constraints on symbolic values + </ul> + + <h3>Interaction with Checkers</h3> + Checkers are not merely passive receivers of the analyzer core changes - they + actively participate in the <tt>ProgramState</tt> construction through the + <tt>GenericDataMap</tt> which can be used to store the checker-defined part + of the state. Each time the analyzer engine explores a new statement, it + notifies each checker registered to listen for that statement, giving it an + opportunity to either report a bug or modify the state. (As a rule of thumb, + the checker itself should be stateless.) The checkers are called one after another + in the predefined order; thus, calling all the checkers adds a chain to the + <tt>ExplodedGraph</tt>. + + <h3>Representing Values</h3> + During symbolic execution, <a href="http://clang.llvm.org/doxygen/classclang_1_1ento_1_1SVal.html">SVal</a> + objects are used to represent the semantic evaluation of expressions. They can + represent things like concrete integers, symbolic values, or memory locations + (which are memory regions). They are a discriminated union of "values", + symbolic and otherwise. + <p> + <a href="http://clang.llvm.org/doxygen/classclang_1_1ento_1_1SymExpr.html">SymExpr</a> (symbol) + is meant to represent abstract, but named, symbolic value. + Symbolic values can have constraints associated with them. Symbols represent + an actual (immutable) value. We might not know what its specific value is, but + we can associate constraints with that value as we analyze a path. + <p> + + <a href="http://clang.llvm.org/doxygen/classclang_1_1ento_1_1MemRegion.html">MemRegion</a> is similar to a symbol. + It is used to provide a lexicon of how to describe abstract memory. Regions can + layer on top of other regions, providing a layered approach to representing memory. + For example, a struct object on the stack might be represented by a <tt>VarRegion</tt>, + but a <tt>FieldRegion</tt> which is a subregion of the <tt>VarRegion</tt> could + be used to represent the memory associated with a specific field of that object. + So how do we represent symbolic memory regions? That's what <a href="http://clang.llvm.org/doxygen/classclang_1_1ento_1_1SymbolicRegion.html">SymbolicRegion</a> + is for. It is a <tt>MemRegion</tt> that has an associated symbol. Since the + symbol is unique and has a unique name; that symbol names the region. + <p> + Let's see how the analyzer processes the expressions in the following example: + <p> + <pre class="code_example"> + int foo(int x) { + int y = x * 2; + int z = x; + ... + } + </pre> + <p> +Let's look at how <tt>x*2</tt> gets evaluated. When <tt>x</tt> is evaluated, +we first construct an <tt>SVal</tt> that represents the lvalue of <tt>x</tt>, in +this case it is an <tt>SVal</tt> that references the <tt>MemRegion</tt> for <tt>x</tt>. +Afterwards, when we do the lvalue-to-rvalue conversion, we get a new <tt>SVal</tt>, +which references the value <b>currently bound</b> to <tt>x</tt>. That value is +symbolic; it's whatever <tt>x</tt> was bound to at the start of the function. +Let's call that symbol <tt>$0</tt>. Similarly, we evaluate the expression for <tt>2</tt>, +and get an <tt>SVal</tt> that references the concrete number <tt>2</tt>. When +we evaluate <tt>x*2</tt>, we take the two <tt>SVals</tt> of the subexpressions, +and create a new <tt>SVal</tt> that represents their multiplication (which in +this case is a new symbolic expression, which we might call <tt>$1</tt>). When we +evaluate the assignment to <tt>y</tt>, we again compute its lvalue (a <tt>MemRegion</tt>), +and then bind the <tt>SVal</tt> for the RHS (which references the symbolic value <tt>$1</tt>) +to the <tt>MemRegion</tt> in the symbolic store. +<br> +The second line is similar. When we evaluate <tt>x</tt> again, we do the same +dance, and create an <tt>SVal</tt> that references the symbol <tt>$0</tt>. Note, two <tt>SVals</tt> +might reference the same underlying values. + +<p> +To summarize, MemRegions are unique names for blocks of memory. Symbols are +unique names for abstract symbolic values. Some MemRegions represents abstract +symbolic chunks of memory, and thus are also based on symbols. SVals are just +references to values, and can reference either MemRegions, Symbols, or concrete +values (e.g., the number 1). + + <!-- + TODO: Add a picture. + <br> + Symbols<br> + FunctionalObjects are used throughout. + --> +<h2 id=idea>Idea for a Checker</h2> + Here are several questions which you should consider when evaluating your + checker idea: + <ul> + <li>Can the check be effectively implemented without path-sensitive + analysis? See <a href="#ast">AST Visitors</a>.</li> + + <li>How high the false positive rate is going to be? Looking at the occurrences + of the issue you want to write a checker for in the existing code bases might + give you some ideas. </li> + + <li>How the current limitations of the analysis will effect the false alarm + rate? Currently, the analyzer only reasons about one procedure at a time (no + inter-procedural analysis). Also, it uses a simple range tracking based + solver to model symbolic execution.</li> + + <li>Consult the <a + href="http://llvm.org/bugs/buglist.cgi?query_format=advanced&bug_status=NEW&bug_status=REOPENED&version=trunk&component=Static%20Analyzer&product=clang">Bugzilla database</a> + to get some ideas for new checkers and consider starting with improving/fixing + bugs in the existing checkers.</li> + </ul> + +<h2 id=registration>Checker Registration</h2> + All checker implementation files are located in <tt>clang/lib/StaticAnalyzer/Checkers</tt> + folder. Follow the steps below to register a new checker with the analyzer. +<ol> + <li>Create a new checker implementation file, for example <tt>./lib/StaticAnalyzer/Checkers/NewChecker.cpp</tt> +<pre class="code_example"> +using namespace clang; +using namespace ento; + +namespace { +class NewChecker: public Checker< check::PreStmt<CallExpr> > { +public: + void checkPreStmt(const CallExpr *CE, CheckerContext &Ctx) const {} +} +} +void ento::registerNewChecker(CheckerManager &mgr) { + mgr.registerChecker<NewChecker>(); +} +</pre> + +<li>Pick the package name for your checker and add the registration code to +<tt>./lib/StaticAnalyzer/Checkers/Checkers.td</tt>. Note, all checkers should +first be developed as experimental. Suppose our new checker performs security +related checks, then we should add the following lines under +<tt>SecurityExperimental</tt> package: +<pre class="code_example"> +let ParentPackage = SecurityExperimental in { +... +def NewChecker : Checker<"NewChecker">, + HelpText<"This text should give a short description of the checks performed.">, + DescFile<"NewChecker.cpp">; +... +} // end "security.experimental" +</pre> + +<li>Make the source code file visible to CMake by adding it to +<tt>./lib/StaticAnalyzer/Checkers/CMakeLists.txt</tt>. + +<li>Compile and see your checker in the list of available checkers by running:<br> +<tt><b>$clang -cc1 -analyzer-checker-help</b></tt> +</ol> + + +<h2 id=skeleton>Checker Skeleton</h2> + There are two main decisions you need to make: + <ul> + <li> Which events the checker should be tracking. + See <a href="http://clang.llvm.org/doxygen/classento_1_1CheckerDocumentation.html">CheckerDocumentation</a> + for the list of available checker callbacks.</li> + <li> What data you want to store as part of the checker-specific program + state. Try to minimize the checker state as much as possible. </li> + </ul> + +<h2 id=bugs>Bug Reports</h2> + +<h2 id=ast>AST Visitors</h2> + Some checks might not require path-sensitivity to be effective. Simple AST walk + might be sufficient. If that is the case, consider implementing a Clang + compiler warning. On the other hand, a check might not be acceptable as a compiler + warning; for example, because of a relatively high false positive rate. In this + situation, AST callbacks <tt><b>checkASTDecl</b></tt> and + <tt><b>checkASTCodeBody</b></tt> are your best friends. + +<h2 id=testing>Testing</h2> + Every patch should be well tested with Clang regression tests. The checker tests + live in <tt>clang/test/Analysis</tt> folder. To run all of the analyzer tests, + execute the following from the <tt>clang</tt> build directory: + <pre class="code"> + $ <b>TESTDIRS=Analysis make test</b> + </pre> + +<h2 id=commands>Useful Commands/Debugging Hints</h2> +<ul> +<li> +While investigating a checker-related issue, instruct the analyzer to only +execute a single checker: +<br><tt> +$ <b>clang -cc1 -analyze -analyzer-checker=osx.KeychainAPI test.c</b> +</tt> +</li> +<li> +To dump AST: +<br><tt> +$ <b>clang -cc1 -ast-dump test.c</b> +</tt> +</li> +<li> +To view/dump CFG use <tt>debug.ViewCFG</tt> or <tt>debug.DumpCFG</tt> checkers: +<br><tt> +$ <b>clang -cc1 -analyze -analyzer-checker=debug.ViewCFG test.c</b> +</tt> +</li> +<li> +To see all available debug checkers: +<br><tt> +$ <b>clang -cc1 -analyzer-checker-help | grep "debug"</b> +</tt> +</li> +<li> +To see which function is failing while processing a large file use +<tt>-analyzer-display-progress</tt> option. +</li> +<li> +While debugging execute <tt>clang -cc1 -analyze -analyzer-checker=core</tt> +instead of <tt>clang --analyze</tt>, as the later would call the compiler +in a separate process. +</li> +<li> +To view <tt>ExplodedGraph</tt> (the state graph explored by the analyzer) while +debugging, goto a frame that has <tt>clang::ento::ExprEngine</tt> object and +execute: +<br><tt> +(gdb) <b>p ViewGraph(0)</b> +</tt> +</li> +<li> +To see the <tt>ProgramState</tt> while debugging use the following command. +<br><tt> +(gdb) <b>p State->dump()</b> +</tt> +</li> +<li> +To see <tt>clang::Expr</tt> while debugging use the following command. If you +pass in a SourceManager object, it will also dump the corresponding line in the +source code. +<br><tt> +(gdb) <b>p E->dump()</b> +</tt> +</li> +<li> +To dump AST of a method that the current <tt>ExplodedNode</tt> belongs to: +<br><tt> +(gdb) <b>p C.getPredecessor()->getCodeDecl().getBody()->dump()</b> +(gdb) <b>p C.getPredecessor()->getCodeDecl().getBody()->dump(getContext().getSourceManager())</b> +</tt> +</li> +</ul> + +</div> +</div> +</body> +</html> diff --git a/clang/www/analyzer/content.css b/clang/www/analyzer/content.css new file mode 100644 index 0000000..b22cca9 --- /dev/null +++ b/clang/www/analyzer/content.css @@ -0,0 +1,79 @@ +html { margin: 0px; } body { margin: 8px; } + +html, body { + padding:0px; + margin: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; + background-color: #808080; + +} + +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 +} + +#page { width:930px; text-align: left; margin: 0 auto; padding:0; + background-color: white; height:100%; + border-left: 1px solid #EBF0FA; +} + +#content { + clear: left; + padding: 1em 2em 0 2em; + background-color: #ffffff; +} + +.itemTitle { color:#2d58b7 } + + +/* Tables */ +tr { vertical-align:top } + +table.options thead { + background-color:#eee; color:#666666; + font-weight: bold; cursor: default; + text-align:left; + border-top: 2px solid #cccccc; + border-bottom: 2px solid #cccccc; + font-weight: bold; font-family: Verdana +} +table.options { border: 1px #cccccc solid } +table.options { border-collapse: collapse; border-spacing: 0px } +table.options { margin-left:0px; margin-top:20px; margin-bottom:20px } +table.options td { border-bottom: 1px #cccccc dotted } +table.options td { padding:5px; padding-left:8px; padding-right:8px } +table.options td { text-align:left; font-size:9pt } + +/* Collapsing Trees: http://dbtree.megalingo.com/web/demo/simple-collapsible-tree.cfm */ +#collapsetree, #collapsetree a:link, #collapsetree li a:link, #collapsetree a:visited, #collapsetree li a:visited{color:#000;text-decoration:none} +#collapsetree,#collapsetree ul{list-style-type:none; width:auto; margin:0; padding:0} +#collapsetree ul{padding-left:20px;display:none;overflow:auto} +#collapsetree li ul{margin:0 auto} +#collapsetree li{display:block;width:100%;line-height:20px;white-space:nowrap} +#collapsetree li a{display:block;padding-left:20px;color:#000;text-decoration:none;background:url(images/tree/bullet.gif) center left no-repeat;white-space:nowrap} +#collapsetree li a:hover{text-decoration:underline;background-color:transparent;color:#000} +#collapsetree li ul.click{display:block} +#collapsetree li.click a{background:url(images/tree/bullet.gif) center left no-repeat} +#collapsetree ul li.click a{background:url(images/tree/bullet.gif) center left no-repeat} +#collapsetree li a.subMenu,#collapsetree ul li a.subMenu{background:url(images/tree/plus.gif) center left no-repeat} +#collapsetree li a.click{background:url(images/tree/minus.gif) center left no-repeat} +#collapsetree ul li a.click{background:url(images/tree/minus.gif) center left no-repeat} + diff --git a/clang/www/analyzer/dev_cxx.html b/clang/www/analyzer/dev_cxx.html new file mode 100644 index 0000000..39dbf7b --- /dev/null +++ b/clang/www/analyzer/dev_cxx.html @@ -0,0 +1,54 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" + "http://www.w3.org/TR/html4/strict.dtd"> +<html> +<head> + <title>Analyzer Development: C++ Support</title> + <link type="text/css" rel="stylesheet" href="menu.css"> + <link type="text/css" rel="stylesheet" href="content.css"> + <script type="text/javascript" src="scripts/menu.js"></script> +</head> +<body> + +<div id="page"> +<!--#include virtual="menu.html.incl"--> +<div id="content"> + +<h1>C++ Support</h1> + +<p>The Clang frontend +now <a href="http://clang.llvm.org/cxx_status.html">supports the +majority of C++</a>. Support in the frontend for C++ language +features, however, does not automatically translate into support for +those features in the static analyzer. Language features need to be +specifically modeled in the static analyzer so their semantics can be +properly analyzed. Support for analyzing C++ and Objective-C++ files +is currently extremely limited, and we are only encouraging those who +are interested in contributing to the development of the analyzer to +try this functionality out at this time.</p> + +<p>Listed here are a set of open tasks that are prerequisites for +decent analysis of C++. This list is also not complete; new tasks +will be added as deemed necessary.</p> + +<ul> + <li>Control-Flow Graph Enhancements: + <ul> + <li>Model C++ destructors</li> + <li>Model C++ initializers (in constructors)</li> + </ul> + </li> + <li>Path-Sensitive Analysis Engine (GRExprEngine): + <ul> + <li>Model C++ casts</li> + <li>Model C++ constructors</li> + <li>Model C++ destructors</li> + <li>Model <tt>new</tt> and <tt>delete</tt></li> + </ul> + </li> +</ul> + +</div> +</div> +</body> +</html> + diff --git a/clang/www/analyzer/filing_bugs.html b/clang/www/analyzer/filing_bugs.html new file mode 100644 index 0000000..f32a8ab --- /dev/null +++ b/clang/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"> + <script type="text/javascript" src="scripts/menu.js"></script> +</head> +<body> + +<div id="page"> +<!--#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 is 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>clang - static analyzer</b> component.</p> +</div> +</div> +</body> +</html> + diff --git a/clang/www/analyzer/images/analyzer_html.png b/clang/www/analyzer/images/analyzer_html.png Binary files differnew file mode 100644 index 0000000..607ea18 --- /dev/null +++ b/clang/www/analyzer/images/analyzer_html.png diff --git a/clang/www/analyzer/images/analyzer_xcode.png b/clang/www/analyzer/images/analyzer_xcode.png Binary files differnew file mode 100644 index 0000000..84c6980 --- /dev/null +++ b/clang/www/analyzer/images/analyzer_xcode.png diff --git a/clang/www/analyzer/images/example_attribute_nonnull.png b/clang/www/analyzer/images/example_attribute_nonnull.png Binary files differnew file mode 100644 index 0000000..919af61 --- /dev/null +++ b/clang/www/analyzer/images/example_attribute_nonnull.png diff --git a/clang/www/analyzer/images/example_cf_returns_retained.png b/clang/www/analyzer/images/example_cf_returns_retained.png Binary files differnew file mode 100644 index 0000000..4bee499 --- /dev/null +++ b/clang/www/analyzer/images/example_cf_returns_retained.png diff --git a/clang/www/analyzer/images/example_cf_returns_retained_gc.png b/clang/www/analyzer/images/example_cf_returns_retained_gc.png Binary files differnew file mode 100644 index 0000000..023f1a2 --- /dev/null +++ b/clang/www/analyzer/images/example_cf_returns_retained_gc.png diff --git a/clang/www/analyzer/images/example_ns_returns_retained.png b/clang/www/analyzer/images/example_ns_returns_retained.png Binary files differnew file mode 100644 index 0000000..61316e1 --- /dev/null +++ b/clang/www/analyzer/images/example_ns_returns_retained.png diff --git a/clang/www/analyzer/images/scan_build_cmd.png b/clang/www/analyzer/images/scan_build_cmd.png Binary files differnew file mode 100644 index 0000000..464fd4e --- /dev/null +++ b/clang/www/analyzer/images/scan_build_cmd.png diff --git a/clang/www/analyzer/images/tree/bullet.gif b/clang/www/analyzer/images/tree/bullet.gif Binary files differnew file mode 100644 index 0000000..de15348 --- /dev/null +++ b/clang/www/analyzer/images/tree/bullet.gif diff --git a/clang/www/analyzer/images/tree/minus.gif b/clang/www/analyzer/images/tree/minus.gif Binary files differnew file mode 100644 index 0000000..225f40d --- /dev/null +++ b/clang/www/analyzer/images/tree/minus.gif diff --git a/clang/www/analyzer/images/tree/plus.gif b/clang/www/analyzer/images/tree/plus.gif Binary files differnew file mode 100644 index 0000000..5398c80 --- /dev/null +++ b/clang/www/analyzer/images/tree/plus.gif diff --git a/clang/www/analyzer/index.html b/clang/www/analyzer/index.html new file mode 100644 index 0000000..18bafd0 --- /dev/null +++ b/clang/www/analyzer/index.html @@ -0,0 +1,224 @@ +<!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="content.css"> + <link type="text/css" rel="stylesheet" href="menu.css"> + <script type="text/javascript" src="scripts/menu.js"></script> + <!-- 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; +} + + #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> +</head> +<body> + +<div id="page"> +<!--#include virtual="menu.html.incl"--> +<div id="content"> + + +<table style="margin-top:0px" width="100%" border="0" cellpadding="0px" cellspacing="0"> +<tr><td> + +<h1>Clang Static Analyzer</h1> + +<p>The Clang Static Analyzer is source code analysis tool that find bugs in C +and Objective-C programs.</p> + +<p>Currently it can be run either as a <a href="/scan-build.html">standalone +tool</a> or <a href="/xcode.html">within Xcode</a>. The standalone tool is +invoked from the command-line, and is intended to be run in tandem with a build +of a codebase.</p> + +<p>The analyzer is 100% open source and is part of the <a +href="http://clang.llvm.org">Clang</a> project. Like the rest of Clang, the +analyzer is implemented as a C++ library that can be used by other tools and +applications.</p> + +<h2>Download</h2> + +<div style="padding:0px; font-size: 90%"> + <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"> + <h3 style="margin:0px;padding:0px">Mac OS X</h3> + <ul> + <li>Latest build (Intel-only binary, 10.5+):<br> + <!--#include virtual="latest_checker.html.incl"--> + </li> + <li><a href="/release_notes.html">Release notes</a></li> + <li>This build can be used both from the command line and from within Xcode</li> + <li><a href="/installation.html">Installation</a> and <a href="/scan-build.html">usage</a></li> + </ul> + </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> + +<div style="padding:0; margin-top:10px; font-size: 90%"> + <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"> + <h3 style="margin:0px;padding:0px">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> + + +</td><td style="padding-left:10px"> +<a href="images/analyzer_xcode.png"><img src="images/analyzer_xcode.png" width="450" alt="analyzer in xcode"></a> +<div style="text-align:center"><b>Viewing static analyzer results in Xcode 3.2</b></div> +<a href="images/analyzer_html.png"><img src="images/analyzer_html.png" width="450" alt="analyzer in browser"></a> +<div style="text-align:center"><b>Viewing static analyzer results in a web browser</b></div> +</td></tr></table> + +<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> + +<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 is 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> +</div> +</body> +</html> + diff --git a/clang/www/analyzer/installation.html b/clang/www/analyzer/installation.html new file mode 100644 index 0000000..ebccd07 --- /dev/null +++ b/clang/www/analyzer/installation.html @@ -0,0 +1,114 @@ +<!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"> + <script type="text/javascript" src="scripts/menu.js"></script> +</head> +<body> + +<div id="page"> +<!--#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 location of the <tt>clang</tt> binary. + +<p>For example, if you built a <em>Debug+Asserts</em> build of LLVM/Clang (the +default), the resultant <tt>clang</tt> binary will be in <tt>$(OBJDIR)/Debug+Asserts/bin</tt> +(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/tools/scan-build</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> +</div> +</body> +</html> + diff --git a/clang/www/analyzer/latest_checker.html.incl b/clang/www/analyzer/latest_checker.html.incl new file mode 100644 index 0000000..d1b0d06 --- /dev/null +++ b/clang/www/analyzer/latest_checker.html.incl @@ -0,0 +1 @@ +<b><a href="http://bit.ly/GUmtVB">checker-263.tar.bz2</a></b> (built March 22, 2012) diff --git a/clang/www/analyzer/menu.css b/clang/www/analyzer/menu.css new file mode 100644 index 0000000..05c1bbf --- /dev/null +++ b/clang/www/analyzer/menu.css @@ -0,0 +1,52 @@ +/* From 'A list apart', 'dropdowns' */ + +#nav { + clear: left; + margin:0; + padding:0; + font-weight: bold; + width:100%; + background-color: #EBF0FA; + border-bottom: 1px solid; + font-size: 80%; +} +#nav a { + text-decoration: none; +} +#nav a:hover { + text-decoration: underline; +} +.menubar ul { + list-style: none inside; +} +.menubar li { + margin: 0; + padding: 5px; + text-align: left; + text-indent: 0px; + list-style-position: inside; + list-style:none; + float: left; + position: relative; + width: 13em; + cursor: default; + background-color: #EBF0FA; +} +.menubar li ul /* second level lists */ { + display: none; + position: absolute; + left: 0; +} +.menubar li>ul { + border-left: 1px solid; + border-right: 1px solid; + border-bottom: 1px solid; + padding: 0; + margin: 5px 0; + left:auto; + font-weight: normal; +} +.menubar li:hover ul, li.over ul { /* lists nested under hovered list items */ + display: block; +} + diff --git a/clang/www/analyzer/menu.html.incl b/clang/www/analyzer/menu.html.incl new file mode 100644 index 0000000..53a4276 --- /dev/null +++ b/clang/www/analyzer/menu.html.incl @@ -0,0 +1,41 @@ +<table width="100%" id="nav" cellspacing=0 cellpadding=0> +<tr><td> +<ul style="margin:0; padding:0" class="menubar"> +<li style="padding-left:5em"> + <a href="/index.html">About</a> + <ul class="menubar"> + <li><a href="/index.html">About the Analyzer</a></li> + <li><a href="http://llvm.org/">LLVM Project</a></li> + <li><a href="http://clang.llvm.org/">Clang Project</a></li> + </ul> +</li> +<li> + <a href="/filing_bugs.html">Filing Bugs</a> +</li> +<li> + User Manual + <ul> + <li><a href="/installation.html">Obtaining the Analyzer</a></li> + <li><a href="/scan-build.html">Command line usage</a></li> + <li><a href="/xcode.html">Using within Xcode</a></li> + <li><a href="/available_checks.html">Available Checks</a></li> + <li><a href="/annotations.html">Source-level Annotations</a></li> + </ul> +</li> +<li> + Development + <ul> + <li><a href="/checker_dev_manual.html">Checker Developer Manual</a></li> + <li><a href="/dev_cxx.html">Analysis support for C++</a></li> + </ul> +</li> +<li> + Mailing Lists + <ul> + <li><a href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev">cfe-dev</a></li> + <li><a href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits">cfe-commits</a></li> + </ul> +</li> +</ul> +</td></tr> +</table> diff --git a/clang/www/analyzer/release_notes.html b/clang/www/analyzer/release_notes.html new file mode 100644 index 0000000..42de9dd --- /dev/null +++ b/clang/www/analyzer/release_notes.html @@ -0,0 +1,188 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" + "http://www.w3.org/TR/html4/strict.dtd"> +<html> +<head> + <title>Release notes for checker-XXX builds</title> + <link type="text/css" rel="stylesheet" href="menu.css"> + <link type="text/css" rel="stylesheet" href="content.css"> + <script type="text/javascript" src="scripts/menu.js"></script> +</head> +<body> + +<div id="page"> +<!--#include virtual="menu.html.incl"--> +<div id="content"> + +<h1>Release notes for <tt>checker-XXX</tt> builds</h1> + +<h4 id="checker_263">checker-263</h4> + +<p><b>built:</b> March 22, 2012</br> + <b>download:</b> <a href="http://bit.ly/GUmtVB">checker-263.tar.bz2</a></p> +<p><b>highlights:</b></p> + +<ul> +<li>Fixes several serious bugs with inter-procedural analysis, including a case where retain/releases would be "double-counted".</li> +</ul> + +<h4 id="checker_262">checker-262</h4> + +<p><b>built: </b>March 15, 2012</br> + <b>download:</b> <a href="http://bit.ly/xETQF0">checker-262.tar.bz2</a></p> +<p><b>highlights:</b></p> + +<ul> + <li>Enables experimental interprocedural analysis (within a file), which greatly amplifies the analyzer's ability to find issues.</li> + <li>Many bug fixes to the malloc/free checker.</li> + <li>Support for new Objective-C NSArray/NSDictionary/NSNumber literals syntax, and Objective-C container subscripting.</li> +</ul> + +<p>NOTE: This build contains new interprocedural analysis that allows the analyzer to find more complicated bugs that span function boundaries. It may have problems, performance issues, etc. We'd like to <a href="/filing_bugs.html">hear about them</a>. + +<h4 id="checker_261">checker-261</h4> + +<p><b>built: </b>February 22, 2012<br> +<b>download:</b> <a href="http://bit.ly/yN1Awv">checker-261.tar.bz2</a></p> +<p><b>highlights:</b></p> + +<ul> + <li>Contains a new experimental malloc/free checker.</li> + <li>Better support for projects using ARC.</li> + <li>Warns about null pointers passed as arguments to C string functions.</li> + <li>Warns about common anti-patterns in 'strncat' size argument, which can lead to buffer overflows.</li> + <li>set-xcode-analyzer now supports self-contained Xcode.app (Xcode 4.3 and later).</li> + <li>Contains a newer version of the analyzer than Xcode 4.3.</li> + <li>Misc. bug fixes and performance work.</li> +</ul> + +<h4 id="checker_260">checker-260</h4> + +<p><b>built: </b>January 25, 2012<br> +<b>download:</b> <a href="http://bit.ly/wpAqVP">checker-260.tar.bz2</a></p> +<p><b>highlights:</b></p> + +<p>This is essentially the same as checker-259, but enables the following <i>experimental</i> checkers (please provide feedback):</p> + +<ul> + <li>Warns about unsafe uses of CFArrayCreate, CFSetCreate, and CFDictionaryCreate</li> + <li>Warns about unsafe uses of getpw, gets, which are sources of buffer overflows</li> + <li>Warns about unsafe uses of mktemp and mktemps, which can lead to insecure temporary files</li> + <li>Warns about unsafe uses of vfork, which is <a href="https://www.securecoding.cert.org/confluence/display/seccode/POS33-C.+Do+not+use+vfork()">insecure</a> to use</li> + <li>Warns about not checking the return values of setuid, setgid, seteuid, setegid, setreuid, setregid (another security issue)</li> +</ul> + +<h4 id="checker_259">checker-259</h4> + +<p><b>built: </b>January 25, 2012<br> +<b>download:</b> <a href="http://bit.ly/zOWf1P">checker-259.tar.bz2</a></p> +<p><b>highlights:</b></p> + +<ul> + <li>Contains a newer version of the analyzer than the one shipped in Xcode 4.2.</li> + <li>Significant performance optimizations to reduce memory usage of the analyzer.</li> + <li>Tweaks to scan-build to have it work more easily with Xcode projects using Clang.</li> + <li>Numerous bug fixes to better support code using ARC.</li> +</ul> + +<h4 id="checker_258">checker-258</h4> + +<p><b>built: </b>October 13, 2011<br> +<p><b>highlights:</b></p> + +<ul> + <li>Contains a newer version of the analyzer than the one shipped in Xcode 4.2.</li> + <li>Adds a new security checker for looking at correct uses of the Mac OS KeyChain API.</li> + <li>Supports ARC (please file bugs where you see issues)</li> + <li>Major under-the-cover changes. This should result in more precise results in some cases, but this is laying the groundwork for major improvements. Please file bugs where you see regressions or issues.</li> +</ul> + +<h4 id="checker_257">checker-257</h4> + +<p><b>built: </b>May 25, 2011<br> +<p><b>highlights:</b></p> + +<ul> + <li>The analyzer is now far more aggressive with checking conformance with Core Foundation conventions. Any function that returns a CF type must now obey the Core Foundation naming conventions, or use the <a href="/annotations.html#attr_cf_returns_retained">cf_returns_retained</a> or <a href="/annotations.html#attr_cf_returns_not_retained">cf_returns_not_retained</a> annotations.</li> + <li>Fixed a serious regression where the analyzer would not analyze Objective-C methods in class extensions.</li> + <li>Misc. bug fixes to improve analyzer precision. + </li> +</ul> + +<h4 id="checker_256">checker-256</h4> + +<p><b>built: </b>April 13, 2011<br> +<p><b>highlights:</b></p> + +<ul> + <li>Lots of bug fixes and improvements to analyzer precision (fewer false positives, possibly more bugs found). + <li>Introductory analysis support for C++ and Objective-C++. +</ul> + +<p>This build contains basic support for C++ and Objective-C++ that is ready to be tried out + by general users. It is still in its infancy, but establishes a baseline for things to come. The main hope is that it can find some + issues and have a reasonable false positive rate.</p> + +<p><b>Please</b> <a href="/filing_bugs.html">file bugs</a> when you see issues of any kind so we can assess + where development on C++ analysis support needs to be focused.</p> + +<p>To try out C++ analysis support, it should work out of the box using <tt>scan-build</tt>. If you are using this checker build + as a replacement to the analyzer bundled with Xcode, first use the <tt>set-xcode-analyzer</tt> script to <a href="/xcode.html">change Xcode to use + your version of the analyzer</a>. You will then need to modify one configuration file in Xcode to enable C++ analysis support. This can + be done with the following steps:</p> + +<ol> + <li>Find the clang .xcspec file: +<pre>$ cd /Developer/Library +$ find . | grep xcspec | grep Clang +./Xcode/<b><SNIP></b>/Clang LLVM 1.0.xcplugin/Contents/Resources/Clang LLVM 1.0.xcspec +</pre></li> + <li>The exact location of the file may vary depending on your installation of Xcode. Edit that file, and look for the string "--analyze": +<pre> + SourceFileOption = "--analyze"; + FileTypes = ( + "sourcecode.c.c", + "sourcecode.c.objc", + ); + ... +</pre> + Change the "FileTypes" entry to: +<pre> + FileTypes = ( + "sourcecode.c.c", + "sourcecode.c.objc", + "sourcecode.cpp.cpp", + "sourcecode.cpp.objcpp", + ); +</pre></li> +<li>Restart Xcode.</li> +</ol> + +<h4 id="checker_255">checker-255</h4> + +<p><b>built: </b> February 11, 2011<br> +<p><b>highlights:</b></p> + +<ul> +<li>Mac OS X builds are now Intel <tt>i386</tt> and <tt>x86_64</tt> only (no <tt>ppc</tt> support)</li> +<li>Turns on new <tt>-init</tt> method checker by default</li> +<li>Reduces memory usage of analyzer by 10%</li> +<li>Misc. fixes to reduce false positives on dead stores and idempotent operations.</li> +</ul> + +<h4 id="checker_254">checker-254</h4> + +<p><b>built: </b> January 27, 2011<br> +<p><b>highlights:</b></p> + +<ul> +<li>Introduces new <tt>-init</tt> method checker to check if a super class's init method is properly called.</li> +<li>Objective-C retain/release checker now reasons about calls to property accessor methods (setter/getter).</li> +<li>Introduces new attribute <a href="annotations.html#attr_ns_consumes_self">ns_consumes_self</a> to educate the Objective-C retain/release checker about custom "init-like" methods that do not follow the standard Cocoa naming conventions.</li> +<li>Introduces new attributes <a href="annotations.html#attr_ns_consumed">ns_consumed</a> and <a href="annotations.html#attr_cf_consumed">cf_consumed</a> to educate the Objective-C retain/release checker about methods/functions that decrement the reference count of a parameter.</li> +</ul> + +</div> +</div> +</body> +</html> + diff --git a/clang/www/analyzer/scan-build.html b/clang/www/analyzer/scan-build.html new file mode 100644 index 0000000..710fa0f --- /dev/null +++ b/clang/www/analyzer/scan-build.html @@ -0,0 +1,344 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" + "http://www.w3.org/TR/html4/strict.dtd"> +<html> +<head> + <title>scan-build: running the analyzer from the command line</title> + <link type="text/css" rel="stylesheet" href="content.css"> + <link type="text/css" rel="stylesheet" href="menu.css"> + <script type="text/javascript" src="scripts/menu.js"></script> + <script type="text/javascript" src="scripts/dbtree.js"></script> +</head> +<body> + +<div id="page"> +<!--#include virtual="menu.html.incl"--> +<div id="content"> + +<h1>scan-build: running the analyzer from the command line</h1> + +<table style="margin-top:0px" width="100%" cellpadding="0px" cellspacing="0"> +<tr><td> + +<h3>What is it?</h3> +<p><b>scan-build</b> is a command line utility that enables a user to run the +static analyzer over their codebase as part of performing a regular build (from +the command line).</p> + +<h3>How does it work?</h3> +<p>During a project build, as source files are compiled they are also analyzed +in tandem by the static analyzer.</p> + +<p>Upon completion of the build, results are then presented to the user within a +web browser.</p> + +<h3>Will it work with any build system?</h3> +<p><b>scan-build</b> has little or no knowledge about how you build your code. +It works by overriding the <tt>CC</tt> and <tt>CXX</tt> environment variables to +(hopefully) change your build to use a "fake" compiler instead of the +one that would normally build your project. This fake compiler executes either +<tt>clang</tt> or <tt>gcc</tt> (depending on the platform) to compile your +code and then executes the static analyzer to analyze your code.</p> + +<p>This "poor man's interposition" works amazingly well in many cases +and falls down in others. Please consult the information on this page on making +the best use of <b>scan-build</b>, which includes getting it to work when the +aforementioned hack fails to work.</p> + +</td> +<td style="padding-left:10px; text-align:center"> + <img src="images/scan_build_cmd.png" width="450px" alt="scan-build"><br> + <a href="images/analyzer_html.png"><img src="images/analyzer_html.png" width="450px" alt="analyzer in browser"></a> +<br><b>Viewing static analyzer results in a web browser</b> +</td></tr></table> + +<h2>Contents</h2> + +<ul id="collapsetree" class="dbtree onclick multiple"> +<li><a href="#scanbuild">Getting Started</a> + <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> +<li><a href="#recommendedguidelines">Recommended Usage Guidelines</a> + <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> +</li> +<li><a href="#iphone">Analyzing iPhone Projects</a></li> +</ul> + +<h2 id="scanbuild">Getting Started</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>/<tt>clang</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 <tt>-j4</tt> 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 class="options"> +<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>(or no arguments)</i></td><td>Display all +<tt>scan-build</tt> options.</td></tr> + +<tr><td><b>-k</b><br><b>--keep-going</b></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 the compiler 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). + --> + +<h2 id="iphone">Analyzing iPhone Projects</h2> + +<p>Conceptually Xcode projects for iPhone applications are nearly the same as +their cousins for desktop applications. <b>scan-build</b> can analyze these +projects as well, but users often encounter problems with just building their +iPhone projects from the command line because there are a few extra preparative +steps they need to take (e.g., setup code signing).</p> + +<h3>Recommendation: use "Build and Analyze"</h3> + +<p>The absolute easiest way to analyze iPhone projects is to use the <a +href="http://developer.apple.com/mac/library/featuredarticles/StaticAnalysis/index.html"><i>Build +and Analyze</i> feature in Xcode 3.2</a> (which is based on the Clang Static +Analyzer). There a user can analyze their project with the click of a button +without most of the setup described later.</p> + +<p><a href="/xcode.html">Instructions are available</a> on this +website on how to use open source builds of the analyzer as a replacement for +the one bundled with Xcode.</p> + +<h3>Using scan-build directly</h3> + +<p>If you wish to use <b>scan-build</b> with your iPhone project, keep the +following things in mind:</p> + +<ul> + <li>Analyze your project in the <tt>Debug</tt> configuration, either by setting +this as your configuration with Xcode or by passing <tt>-configuration +Debug</tt> to <tt>xcodebuild</tt>.</li> + <li>Analyze your project using the <tt>Simulator</tt> as your base SDK. It is +possible to analyze your code when targeting the device, but this is much +easier to do when using Xcode's <i>Build and Analyze</i> feature.</li> + <li>Check that your code signing SDK is set to the simulator SDK as well, and make sure this option is set to <tt>Don't Code Sign</tt>.</li> +</ul> + +<p>Note that you can most of this without actually modifying your project. For +example, if your application targets iPhoneOS 2.2, you could run +<b>scan-build</b> in the following manner from the command line:</p> + +<pre class="code_example"> +$ scan-build xcodebuild -configuration Debug -sdk iphonesimulator2.2 +</pre> + +Alternatively, if your application targets iPhoneOS 3.0: + +<pre class="code_example"> +$ scan-build xcodebuild -configuration Debug -sdk iphonesimulator3.0 +</pre> + +<h3>Gotcha: using the right compiler</h3> + +<p>Recall that <b>scan-build</b> analyzes your project by using a compiler to +compile the project and <tt>clang</tt> to analyze your project. The script uses +simple heuristics to determine which compiler should be used (it defaults to +<tt>clang</tt> on Darwin and <tt>gcc</tt> on other platforms). When analyzing +iPhone projects, <b>scan-build</b> may pick the wrong compiler than the one +Xcode would use to build your project. For example, this could be because +multiple versions of a compiler may be installed on your system, especially if +you are developing for the iPhone.</p> + +<p>When compiling your application to run on the simulator, it is important that <b>scan-build</b> +finds the correct version of <tt>gcc/clang</tt>. Otherwise, you may see strange build +errors that only happen when you run <tt>scan-build</tt>. + +<p><b>scan-build</b> provides the <tt>--use-cc</tt> and <tt>--use-c++</tt> +options to hardwire which compiler scan-build should use for building your code. +Note that although you are chiefly interested in analyzing your project, keep in +mind that running the analyzer is intimately tied to the build, and not being +able to compile your code means it won't get fully analyzed (if at all).</p> + +<p>If you aren't certain which compiler Xcode uses to build your project, try +just running <tt>xcodebuild</tt> (without <b>scan-build</b>). You should see the +full path to the compiler that Xcode is using, and use that as an argument to +<tt>--use-cc</tt>.</p> + +</div> +</div> +</body> +</html> + diff --git a/clang/www/analyzer/scripts/dbtree.js b/clang/www/analyzer/scripts/dbtree.js new file mode 100644 index 0000000..5face5d --- /dev/null +++ b/clang/www/analyzer/scripts/dbtree.js @@ -0,0 +1 @@ +eval(function(p,a,c,k,e,r){e=function(c){return(c<a?'':e(parseInt(c/a)))+((c=c%a)>35?String.fromCharCode(c+29):c.toString(36))};if(!''.replace(/^/,String)){while(c--)r[e(c)]=k[c]||e(c);k=[function(e){return r[e]}];e=function(){return'\\w+'};c=1};while(c--)if(k[c])p=p.replace(new RegExp('\\b'+e(c)+'\\b','g'),k[c]);return p}('7 5,r,Q,u;7 17=[];5=H;1i();9(!1Z.1j.20){1Z.1j.20=k(a){C[C.D]=a}}7 19=\'35+/\';k 36(a){7 b,R=\'\',i=0;I(;i<a.D;i+=4){b=(19.1k(a.1l(i))&1a)<<18|(19.1k(a.1l(i+1))&1a)<<12|(19.1k(a.1l(i+2))&1a)<<6|19.1k(a.1l(i+3))&1a;R+=37.38((b&39)>>16,(b&3a)>>8,b&1a)}9(a.21(i-2)==22)1m=R.23(0,R.D-2);s 9(a.21(i-1)==22)1m=R.23(0,R.D-1);s 1m=R;z 3b(1m)}7 A={24:k(){7 a=l.E(\'X\');I(7 i=0;i<a.D;i++){9(a[i].h.F(/\\1n\\b/)==-1)3c;7 b=a[i];9(b.h.F(/\\1E\\b/)!=-1){7 c=b.E(\'a\');I(7 j=0;j<c.D;j++){m.B(c[j],\'25\',1F,o);m.B(c[j],\'26\',1G,o);m.B(c[j],\'1o\',1b,o);c[j].Y=\'1H:1I(0)\'}}7 d=b.E(\'X\');I(7 j=0;j<d.D;j++){7 e=d[j].p;e.27=J;9(b.h.F(/\\3d\\b/)!=-1){m.B(e,\'w\',A.w,o);9(b.h.F(/\\3e\\b/)==-1){e.E(\'a\')[0].Y=\'1H:1I(0)\'}}s{7 t=b.h.3f(/1J(.*)1J/);t=t?t[1]:H;m.B(e,\'3g\',A.28(e,t),o);m.B(e,\'3h\',A.29(e),o)}e.E(\'a\')[0].h+=\' 2a\'}9(b.h.F(/\\3i\\b/)!=-1)A.2b(b.v)}},2b:k(a){7 b=l.G(a+\'3j\');9(b){A.1p(b);b=b.p;1c(!!b&&(b.v!=a)){9((!b.h)||(b.h==\'\')){b.h=\'w\'}s{b.h+=\' w\'}9(b.1d.K.L()==\'a\')b.1d.h+=\' w\';b=b.p}}},29:k(a){z k(){A.1p(a)}},28:k(a,b){z k(){A.2c(a,b)}},1p:k(a){7 b=a;3k(b.2d);I(7 i=0;i<b.S.D;i++){7 c=b.S[i];9(c.K.L()==\'X\'){b.E(\'a\')[0].h+=\' w\';b.h+=\' w\';c.h+=\' w\'}}},2c:k(a,b){7 c=a;c.2d=3l(k(){A.1q(c)},b)},1q:k(a){I(7 i=0;i<a.S.D;i++){7 b=a.S[i];9(b.K.L()==\'X\'){a.E(\'a\')[0].h=a.E(\'a\')[0].h.1K(/w/g,\'\');b.h=b.h.1K(/w/g,\'\');a.h=a.h.1K(/w/g,\'\')}}},w:k(e){9(M.T){M.T.1L=J}9(e&&e.1r){e.1r()}7 a=(M.T)?M.T.2e:(e)?e.1M:H;9(!a||!(a=A.1N(a,\'2f\')))z;9(a.E(\'a\')[0].h.F(/\\2g\\b/)==-1){7 b=1e(a);9(2h(b)){9(l.G(b).h.F(/\\3m\\b/)==-1){I(n=0;n<a.p.S.D;n++){N=a.p.S[n];9(N.K.L()==\'2f\'){9(N.h.F(/\\2g\\b/)!=-1)A.1q(a.p.S[n])}}}}A.1p(a)}s{A.1q(a)}9(2h(1e(a))){z J}s{z o}},1N:k(a,b){9(a.K.L()!=b&&a.K.L()!=\'U\'){z A.1N(a.p,b)}s 9(a.K.L()==\'U\'){z H}s{z a}}};k 1i(){3n{u=M.2i?O 2i():O 3o(\'3p.3q\')}3r(e){2j(\'2k 2l: 3s 3t 3u 3v 3w-3x!\')}}k 1O(a,x){a.1f.3y=x+\'2m\'}k 1P(a,y){a.1f.3z=y+\'2m\'}k 1e(a){1c(a.h.F(/\\1n\\b/)==-1){a=a.p}9((a.h.F(/\\1n\\b/)!=-1)&&(a.h.F(/\\1E\\b/)!=-1)){I(i=0;i<17.D;i++){9(a.v==17[i].q)z i}}z a.v}k 1G(a){a=O m(a);r=a.P.p.p.v;7 b=r.1s(\'Z\');r=b[1];5=17[1e(a.P)];7 c=l.G(5.q+\'10\').3A(J);7 d=l.G(5.q+\'10\');d.p.2n(d);c.v=5.q+\'10\';l.U.2o(c);1O(c,a.x);1P(c,a.y);c.1f.1Q=\'2p\';a.1t();m.B(l,\'1u\',1R,o);z o}k 1R(c){c=O m(c);7 e;7 a=c.P;7 b=a;1c((b!=H)&&(b.K.L()!=\'U\')){9(b.v==5.q+\'10\')1g;b=b.p}9((b!=H)&&(b.v==5.q+\'10\')){3B(a.p.h){1S\'3C\':a.Y=5.V+\'11=1T&N=\'+5.13;1g;1S\'1T\':a.Y=5.V+\'11=1T&N=\'+r;1g;1S\'2q\':a.Y=5.V+\'11=2q&N=\'+r;1g;3D:e=5.2r+\'?q=\'+5.q;e+=\'&13=\'+5.13;9(a.p.h==\'3E\'){e+=\'&11=2s&N=\'+r+\'&2t=\'+5.13}s{e+=\'&11=\'+a.p.h+\'&N=\'+r}7 d=O 2u();7 f=d.2v();e+=\'&2w=\'+f;e+=\'&1v=\'+5.1v;e+=\'&1w=\'+5.1w;e+=\'&1x=\'+5.1x;e+=\'&1y=\'+5.1y;e+=\'&1z=\'+5.1z;e+=\'&1A=\'+5.1A;e+=\'&v=\'+5.v;e+=\'&1B=\'+5.1B;e+=\'&1C=\'+5.1C;e+=\'&V=\'+5.V;u.2x=1U;u.1V(\'2y\',e,J);u.14(\'2z\',\'2A-2B\');u.14(\'2C-2D\',\'2E-2F\');u.14(\'2G-2H-2I\',l.2J);u.2K(H)}}7 g=l.G(5.q+\'10\');9(g){g.1f.1Q=\'3F\'};m.1h(l,\'1u\',1R,o)}k 1F(a){a=O m(a);r=a.P.p.p.v;7 b=r.1s(\'Z\');r=b[1];5=17[1e(a.P)];9(!l.G(5.q+\'15\')){7 c=(!l.G(5.q+\'15\'))?l.3G(\'3H\'):l.G(5.q+\'15\');c.v=5.q+\'15\';c.2L=a.P.1d.3I;l.U.2o(c)}m.B(l,\'2M\',1W,o);m.B(l,\'1u\',1X,o);m.B(l,\'1o\',1b,o);a.1t();z o}k 1b(a){9(!a&&M.T)a=M.T;9(a!=H){9(3J(a.1Y)==\'k\')a.1Y();s a.2N=o}z o}k 1W(a){a=O m(a);7 b=l.G(5.q+\'15\');1O(b,a.x);1P(b,a.y);b.1f.1Q=\'2p\';a.1t();z o}k 1X(a){a=O m(a);7 b=a.P.p;9(b.K.L()==\'a\'){r=5.q+\'Z\'+r;9(r!=b.p.v){7 c=J;7 d=b.p;1c(!!d&&(d.v!=5.q)){9(d.v==r){c=o;1g}s{d=d.p}}9(c==J){7 e=r.1s(\'Z\');r=e[1];Q=b.p.v;7 f=Q.1s(\'Z\');Q=f[1];2O(a)}}}7 g=l.G(5.q+\'15\');9(g){g.p.2n(g)};m.1h(l,\'2M\',1W,o);m.1h(l,\'1u\',1X,o);m.1h(l,\'1o\',1b,o)}k 2O(a){7 d=O 2u();7 b=d.2v();7 c;c=5.2r+\'?q=\'+5.q+\'&11=2s&13=\'+5.13+\'&N=\'+r+\'&2t=\'+Q+\'&2w=\'+b;c+=\'&1v=\'+5.1v;c+=\'&1w=\'+5.1w;c+=\'&1x=\'+5.1x;c+=\'&1y=\'+5.1y;c+=\'&1z=\'+5.1z;c+=\'&1A=\'+5.1A;c+=\'&v=\'+5.v;c+=\'&1B=\'+5.1B;c+=\'&1C=\'+5.1C;c+=\'&V=\'+5.V;u.2x=1U;u.1V(\'2y\',c,J);u.14(\'2z\',\'2A-2B\');u.14(\'2C-2D\',\'2E-2F\');u.14(\'2G-2H-2I\',l.2J);u.2K(H)}k 2P(){7 a=(!!Q)?Q:r;a=5.q+\'Z\'+a;a=l.G(a);9(a){a=a.E(\'X\')[0];1c(!!a&&(a.h.F(/\\1n\\b/)==-1)&&(a.h.F(/\\1E\\b/)==-1)){9((!a.h)||(a.h==\'\')){a.h=\'w\'}s{a.h+=\' w\'}9(a.1d.K.L()==\'a\')a.1d.h+=\' w\';a=a.p}}}k 3K(a,b){9(a!=\'3L\'){3M(a+".3N=\'"+b.2Q[b.2R].2S+"\'")}s{M.1V(b.2Q[b.2R].2S)}}k 2T(a){7 b=l.G(a);7 c=b.E(\'X\');I(7 j=0;j<c.D;j++){7 d=c[j].p;d.27=J;m.B(d,\'w\',A.w,o);d.E(\'a\')[0].h+=\' 2a\'}7 e=b.E(\'a\');I(7 j=0;j<e.D;j++){m.B(e[j],\'25\',1F,o);m.B(e[j],\'26\',1G,o);m.B(e[j],\'1o\',1b,o);e[j].Y=\'1H:1I(0)\'}}k 1U(){9(u.3O==4){9(u.3P==3Q){l.G(5.q+\'3R\').2L=u.3S;2T(5.q);2P();1i()}s{2j(\'2k 2l: 3T, 3U 3V 1J 3W a 3X 3Y 3Z 40:\\n\'+u.41);1i()}}}k m(a){C.W=a?a:M.T;C.P=a.1M?a.1M:a.2e;C.x=a.2U?(a.2U):(a.42+2V.2W(l.U.2X,l.2Y.2X));C.y=a.2Z?(a.2Z):(a.43+2V.2W(l.U.30,l.2Y.30))}m.1j.44=k(){z\'m [ x = \'+C.x+\', y = \'+C.y+\' ]\'};m.1j.1t=k(){9(C.W.1r){C.W.1r();C.W.1Y()}s 9(C.W.1L){C.W.1L=J;C.W.2N=o}};m.B=k(a,b,c,d){9(l.31){a.31(b,c,d)}s 9(l.32){a.32(\'1D\'+b,c,d)}s{a[\'1D\'+b]=c}};m.1h=k(a,b,c,d){9(l.33){a.33(b,c,d)}s 9(l.34){a.34(\'1D\'+b,c,d)}s{a[\'1D\'+b]=H}};m.B(M,\'45\',A.24,o);',62,254,'|||||instance||var||if||||||||className|||function|document|Evt||false|parentNode|instanceName|nid|else||client|id|click|||return|dbTree|addEvent|this|length|getElementsByTagName|search|getElementById|null|for|true|nodeName|toLowerCase|window|node|new|source|nto|decOut|childNodes|event|body|editpage|evt|ul|href|_|_options|action||rootnode|setRequestHeader|_tip||dbtreeObj||b64s|0xff|PreventDefault|while|firstChild|getObj|style|break|removeEvent|createClient|prototype|indexOf|charAt|undecOut|bdbtree|selectstart|mOver|mOut|stopPropagation|split|consume|mouseup|type|query|datasource|username|password|table|parent|contentfield|on|bedit|dragPress|contextMenu|javascript|void|to|replace|cancelBubble|target|getTarget|setX|setY|display|contextAction|case|add|callback|open|dragMove|dragRelease|preventDefault|Array|push|charCodeAt|61|substring|init|mousedown|contextmenu|hasSubMenu|getMoutFor|getMoverFor|subMenu|mExp|mTimeout|timeout|srcElement|li|bclick|isNaN|XMLHttpRequest|alert|DBTree|Error|px|removeChild|appendChild|block|edit|tagpath|move|nodeto|Date|getTime|time|onreadystatechange|get|Pragma|no|cache|Cache|Control|must|revalidate|If|Modified|Since|lastModified|send|innerHTML|mousemove|returnValue|dragBoxDropped|expandtree|options|selectedIndex|value|reinit|pageX|Math|max|scrollLeft|documentElement|pageY|scrollTop|addEventListener|attachEvent|removeEventListener|detachEvent|ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789|decode|String|fromCharCode|0xff0000|0xff00|unescape|continue|bonclick|blinkparent|match|mouseout|mouseover|bexpand|_active|clearTimeout|setTimeout|bmultiple|try|ActiveXObject|Microsoft|XMLHTTP|catch|Your|browser|is|not|Ajax|enabled|left|top|cloneNode|switch|addroot|default|moveroot|none|createElement|div|nodeValue|typeof|jumpTo|blank|eval|location|readyState|status|200|_edit|responseText|Sorry|there|seems|be|problem|retrieving|the|response|statusText|clientX|clientY|toString|load'.split('|'),0,{})) diff --git a/clang/www/analyzer/scripts/menu.js b/clang/www/analyzer/scripts/menu.js new file mode 100644 index 0000000..6b393c0 --- /dev/null +++ b/clang/www/analyzer/scripts/menu.js @@ -0,0 +1,17 @@ +startList = function() { + if (document.all&&document.getElementById) { + navRoot = document.getElementById("nav"); + for (i=0; i<navRoot.childNodes.length; i++) { + node = navRoot.childNodes[i]; + if (node.nodeName=="LI") { + node.onmouseover=function() { + this.className+=" over"; + } + node.onmouseout=function() { + this.className=this.className.replace(" over", ""); + } + } + } + } +} +window.onload=startList; diff --git a/clang/www/analyzer/xcode.html b/clang/www/analyzer/xcode.html new file mode 100644 index 0000000..ac75a04 --- /dev/null +++ b/clang/www/analyzer/xcode.html @@ -0,0 +1,143 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" + "http://www.w3.org/TR/html4/strict.dtd"> +<html> +<head> + <title>Build and Analyze: running the analyzer within Xcode</title> + <link type="text/css" rel="stylesheet" href="content.css"> + <link type="text/css" rel="stylesheet" href="menu.css"> + <script type="text/javascript" src="scripts/menu.js"></script> + <script type="text/javascript" src="scripts/dbtree.js"></script> +</head> +<body> + +<div id="page"> +<!--#include virtual="menu.html.incl"--> +<div id="content"> + +<h1>Build and Analyze: running the analyzer within Xcode</h1> + +<table style="margin-top:0px" width="100%" border="0" cellpadding="0px" cellspacing="0"> +<tr><td> + +<h3>What is it?</h3> +<p><i>Build and Analyze</i> is an Xcode feature (introduced in Xcode 3.2) that +allows users to run the Clang Static Analyzer <a +href="http://developer.apple.com/mac/library/featuredarticles/StaticAnalysis/index.html">directly +within Xcode</a>.</p> + +<p>It integrates directly with the Xcode build system and +presents analysis results directly within Xcode's editor.</p> + +<h3>Can I use the open source analyzer builds with Xcode?</h3> + +<p><b>Yes</b>. Instructions are included below.</p> + +</td> +<td style="padding-left:10px; text-align:center"> + <a href="images/analyzer_xcode.png"><img src="images/analyzer_xcode.png" width="620px" alt="analyzer in xcode"></a> +<br><b>Viewing static analyzer results in Xcode</b> +</td></tr></table> + +<h3>Key features:</h3> +<ul> + <li><b>Integrated workflow:</b> Results are integrated within Xcode. There is + no experience of using a separate tool, and activating the analyzer requires a + single keystroke or mouse click.</li> + <li><b>Transparency:</b> Works effortlessly with Xcode projects (including iPhone projects). + <li><b>Cons:</b> Doesn't work well with non-Xcode projects. For those, + consider using <a href="/scan-build.html"><b>scan-build</b></a>. +</ul> + + +<h2>Getting Started</h2> + +<p>Xcode 3.2 is available as a free download from Apple, with <a +href="http://developer.apple.com/mac/library/featuredarticles/StaticAnalysis/index.html">instructions available</a> +for using <i>Build and Analyze</i>.</p> + +<h2>Using open source analyzer builds with <i>Build and Analyze</i></h2> + +<p>By default, Xcode uses the version of <tt>clang</tt> that came bundled with +it to provide the results for <i>Build and Analyze</i>. It is possible to change +Xcode's behavior to use an alternate version of <tt>clang</tt> for this purpose +while continuing to use the <tt>clang</tt> that came with Xcode for compiling +projects.</p> + +<h3>Why try open source builds?</h3> + +<p>The advantage of using open source analyzer builds (provided on this website) +is that they are often newer than the analyzer provided with Xcode, and thus can +contain bug fixes, new checks, or simply better analysis.</p> + +<p>On the other hand, new checks can be experimental, with results of variable +quality. Users are encouraged to <a href="filing_bugs.html">file bug reports</a> +(for any version of the analyzer) where they encounter false positives or other +issues.</p> + +<h3>set-xcode-analyzer</h3> + +<p>Starting with analyzer build checker-234, analyzer builds contain a command +line utility called <tt>set-xcode-analyzer</tt> that allows users to change what +copy of <tt>clang</tt> that Xcode uses for <i>Build and Analyze</i>:</p> + +<pre class="code_example"> +$ <b>set-xcode-analyzer -h</b> +Usage: set-xcode-analyzer [options] + +Options: + -h, --help show this help message and exit + --use-checker-build=PATH + Use the Clang located at the provided absolute path, + e.g. /Users/foo/checker-1 + --use-xcode-clang Use the Clang bundled with Xcode +</pre> + +<p>Operationally, <b>set-xcode-analyzer</b> edits Xcode's configuration files +(in <tt>/Developer</tt>) to point it to use the version of <tt>clang</tt> you +specify for static analysis. Within this model it provides you two basic modes:</p> + +<ul> + <li><b>--use-xcode-clang</b>: Switch Xcode (back) to using the <tt>clang</tt> that came bundled with it for static analysis.</li> + <li><b>--use-checker-build</b>: Switch Xcode to using the <tt>clang</tt> provided by the specified analyzer build.</li> +</ul> + +<h4>Things to keep in mind</h4> + +<ul> +<li>You should quit Xcode prior to running <tt>set-xcode-analyzer</tt>.</li> +<li>You will need to run <tt>set-xcode-analyzer</tt> under <b><tt>sudo</tt></b> + in order to have write privileges to modify the Xcode configuration files.</li> +</ul> + +<h4>Examples</h4> + +<p><b>Example 1</b>: Telling Xcode to use checker-235 for <i>Build and Analyze</i>:</p> + +<pre class="code_example"> +$ pwd +/tmp +$ tar xjf checker-235.tar.bz2 +$ sudo checker-235/set-xcode-analyzer --use-checker-build=/tmp/checker-235 +</pre> + +<p>Note that you typically won't install an analyzer build in <tt>/tmp</tt>, but +the point of this example is that <tt>set-xcode-analyzer</tt> just wants a full +path to an untarred analyzer build.</p> + +<p><b>Example 2</b>: Telling Xcode to use a very specific version of <tt>clang</tt>:</p> + +<pre class="code_example"> +$ sudo set-xcode-analyzer --use-checker-build=~/mycrazyclangbuild/bin/clang +</pre> + +<p><b>Example 3</b>: Resetting Xcode to its default behavior:</p> + +<pre class="code_example"> +$ sudo set-xcode-analyzer --use-xcode-clang +</pre> + +</div> +</div> +</body> +</html> + |
