maxjhandsome
/
llvm-project
forked from OSchip/llvm-project
1
0
Fork 0
Code Issues Pull Requests Packages Releases Wiki Activity

Various tweaks and updates to the analyzer website. 

llvm-svn: 171885
This commit is contained in:
Jordan Rose 2013-01-08 19:29:37 +00:00
parent 454a384e59
commit a2d5f0c742
5 changed files with 107 additions and 78 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

72
clang/www/analyzer/annotations.html
View File

@ -127,7 +127,10 @@ 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>
attributes described here. However, you should consider using proper naming
conventions or the <a
href="http://clang.llvm.org/docs/LanguageExtensions.html#the-objc-method-family-attribute"><tt>objc_method_family</tt></a>
attribute, if applicable.</p>
<h4 id="attr_ns_returns_retained">Attribute 'ns_returns_retained'
(Clang-specific)</h4>
@ -135,7 +138,9 @@ attributes described here.</p>
<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>
<tt>release</tt> message to the object). The Foundation framework defines a
macro <b><tt>NS_RETURNS_RETAINED</tt></b> that is functionally equivalent to the
one shown below.</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
@ -202,7 +207,9 @@ 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 &quot;owning&quot; reference being
returned to the caller.</p>
returned to the caller. The Foundation framework defines a
macro <b><tt>NS_RETURNS_NOT_RETAINED</tt></b> that is functionally equivalent to
the one shown below.</p>
<p>Usage is identical to <a
href="#attr_ns_returns_retained">ns_returns_retained</a>. When using the
@ -229,7 +236,9 @@ its availability, as it is not available in earlier versions of the analyzer:</p
<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.
Foundation object that the caller is responsible for releasing. The
CoreFoundation framework defines a macro <b><tt>CF_RETURNS_RETAINED</tt></b>
that is functionally equivalent to the one shown below.</p>
<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'
@ -330,7 +339,9 @@ 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
&quot;owning&quot; reference being returned to the caller.</p>
&quot;owning&quot; reference being returned to the caller. The
CoreFoundation framework defines a macro <b><tt>CF_RETURNS_NOT_RETAINED</tt></b>
that is functionally equivalent to the one shown below.</p>
<p>Usage is identical to <a
href="#attr_cf_returns_retained">cf_returns_retained</a>. When using the
@ -355,9 +366,12 @@ its availability, as it is not available in earlier versions of the analyzer:</p
<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>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. The
Foundation framework defines a macro <b><tt>NS_RELEASES_ARGUMENT</tt></b> that
is functionally equivalent to the <tt>NS_CONSUMED</tt> macro shown below.</p>
<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
@ -409,14 +423,19 @@ void test_method2() {
<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>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. The CoreFoundation framework defines a macro
<b><tt>CF_RELEASES_ARGUMENT</tt></b> that is functionally equivalent to the
<tt>CF_CONSUMED</tt> macro shown below.</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>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>
@ -461,13 +480,13 @@ void test_method() {
<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 &quot;consumed&quot; (a single reference count decremented)
after the message is sent. This matches the semantics of all &quot;init&quot; methods.
</p>
<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
&quot;consumed&quot; (a single reference count decremented) after the message
is sent. This matches the semantics of all &quot;init&quot; 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>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>
@ -490,8 +509,15 @@ void test_method() {
@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>
<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>
<p>The Foundation framework defines a macro <b><tt>NS_REPLACES_RECEIVER</tt></b>
which is functionally equivalent to the combination of <tt>NS_CONSUMES_SELF</tt>
and <tt>NS_RETURNS_RETAINED</tt> shown above.</p>
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<h2 id="custom_assertions">Custom Assertion Handlers</h2>

3
clang/www/analyzer/available_checks.html
View File

@ -176,14 +176,13 @@
<td><b>unix.cstring.NullArg</b></td><td>Check for null pointers being passed as arguments to C string functions.</td>
</table>
<p>In addition to these the analyzer contains numerous experimental (beta) checkers.</p>
<p>In addition to these the analyzer contains numerous experimental (alpha) 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>

37
clang/www/analyzer/dev_cxx.html
View File

@ -15,16 +15,13 @@
<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>The Clang compiler <a
href="http://clang.llvm.org/cxx_status.html">supports almost all of C++11</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 fairly basic.</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
@ -33,16 +30,22 @@ 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>
<li>Model destructors for temporary objects</li>
<li>Model the implicit allocator call to <tt>operator new</tt></li>
</ul>
</li>
<li>Path-Sensitive Analysis Engine (GRExprEngine):
<li>Path-Sensitive Analysis Engine (ExprEngine):
<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>
<li>Allow constructors to be inlined</li>
<li>Allow destructors to be inlined</li>
<li>Fully model <tt>new</tt> and <tt>delete</tt></li>
<li>Track type info through casts more precisely</li>
</ul>
</li>
<li>Checkers:
<ul>
<li>Check that <tt>new</tt> and <tt>delete</tt> are correctly paired</li>
<li>For more ideas, see the <a href="potential_checkers.html">list of potential checkers</a></li>
</ul>
</li>
</ul>

29
clang/www/analyzer/index.html
View File

@ -69,12 +69,12 @@
<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>The Clang Static Analyzer is a source code analysis tool that finds bugs in
C, 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
<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
@ -138,14 +138,14 @@ applications.</p>
</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>
<div style="text-align:center"><b>Viewing static analyzer results in Xcode</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 &quot;static analysis&quot; is conflated, but here we use it to mean
<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
@ -155,9 +155,8 @@ 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>
industrial-quality static analysis framework for analyzing C, 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>
@ -175,11 +174,11 @@ 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>
<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 of 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>

44
clang/www/analyzer/xcode.html
View File

@ -2,7 +2,7 @@
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>Build and Analyze: running the analyzer within Xcode</title>
<title>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>
@ -14,15 +14,16 @@
<!--#include virtual="menu.html.incl"-->
<div id="content">
<h1>Build and Analyze: running the analyzer within Xcode</h1>
<h1>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
<p>Since Xcode 3.2, users have been able to run the Clang Static Analyzer
<a
href="https://developer.apple.com/library/mac/documentation/ToolsLanguages/Conceptual/Xcode4UserGuide/060-Debug_Your_App/debug_app.html#//apple_ref/doc/uid/TP40010215-CH3-SW17">directly
within Xcode</a>.</p>
<p>It integrates directly with the Xcode build system and
@ -45,23 +46,24 @@ presents analysis results directly within Xcode's editor.</p>
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>.
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>
<p>Xcode is available as a free download from Apple on the <a
href="https://itunes.apple.com/us/app/xcode/id497799835?mt=12">Mac
App Store</a>, with <a
href="https://developer.apple.com/library/mac/documentation/ToolsLanguages/Conceptual/Xcode4UserGuide/060-Debug_Your_App/debug_app.html#//apple_ref/doc/uid/TP40010215-CH3-SW17">instructions
available</a> for using the analyzer.</p>
<h2>Using open source analyzer builds with <i>Build and Analyze</i></h2>
<h2>Using open source analyzer builds with Xcode</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>
it to analyze your code. 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>
@ -78,7 +80,7 @@ issues.</p>
<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>
copy of <tt>clang</tt> that Xcode uses for analysis:</p>
<pre class="code_example">
$ <b>set-xcode-analyzer -h</b>
@ -93,8 +95,8 @@ Options:
</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>
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>
@ -104,14 +106,14 @@ specify for static analysis. Within this model it provides you two basic modes:
<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>
<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>
<p><b>Example 1</b>: Telling Xcode to use checker-235:</p>
<pre class="code_example">
$ pwd