From a2d5f0c7429485f2b03979f361cbbf01452ca458 Mon Sep 17 00:00:00 2001 From: Jordan Rose Date: Tue, 8 Jan 2013 19:29:37 +0000 Subject: [PATCH] Various tweaks and updates to the analyzer website. llvm-svn: 171885 --- clang/www/analyzer/annotations.html | 72 ++++++++++++++++-------- clang/www/analyzer/available_checks.html | 3 +- clang/www/analyzer/dev_cxx.html | 37 ++++++------ clang/www/analyzer/index.html | 29 +++++----- clang/www/analyzer/xcode.html | 44 ++++++++------- 5 files changed, 107 insertions(+), 78 deletions(-) diff --git a/clang/www/analyzer/annotations.html b/clang/www/analyzer/annotations.html index bb4bc448c7f4..ca6a185c1d9b 100644 --- a/clang/www/analyzer/annotations.html +++ b/clang/www/analyzer/annotations.html @@ -127,7 +127,10 @@ conventions can cause the analyzer to miss bugs or flag false positives.

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.

+attributes described here. However, you should consider using proper naming +conventions or the objc_method_family +attribute, if applicable.

Attribute 'ns_returns_retained' (Clang-specific)

@@ -135,7 +138,9 @@ attributes described here.

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 -release message to the object).

+release message to the object). The Foundation framework defines a +macro NS_RETURNS_RETAINED that is functionally equivalent to the +one shown below.

Placing on Objective-C methods: 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'. 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.

+returned to the caller. The Foundation framework defines a +macro NS_RETURNS_NOT_RETAINED that is functionally equivalent to +the one shown below.

Usage is identical to ns_returns_retained. When using the @@ -229,7 +236,9 @@ its availability, as it is not available in earlier versions of the analyzer:

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 CF_RETURNS_RETAINED +that is functionally equivalent to the one shown below.

Placing on Objective-C methods: 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'. 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.

+"owning" reference being returned to the caller. The +CoreFoundation framework defines a macro CF_RETURNS_NOT_RETAINED +that is functionally equivalent to the one shown below.

Usage is identical to cf_returns_retained. When using the @@ -355,9 +366,12 @@ its availability, as it is not available in earlier versions of the analyzer:

Attribute 'ns_consumed' (Clang-specific) -

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 release message is implicitly sent to the parameter upon - completion of the call to the given function or method. +

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 release message is implicitly sent to the +parameter upon completion of the call to the given function or method. The +Foundation framework defines a macro NS_RELEASES_ARGUMENT that +is functionally equivalent to the NS_CONSUMED macro shown below.

Important note when using Garbage Collection: Note that the analyzer essentially ignores this attribute when code is compiled to use Objective-C @@ -409,14 +423,19 @@ void test_method2() {

Attribute 'cf_consumed' (Clang-specific)

-

The 'cf_consumed' attribute is practically identical to ns_consumed. -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 CFRelease upon -completion of the call to the given function or method.

+

The 'cf_consumed' attribute is practically identical to ns_consumed. 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 CFRelease upon completion of the call +to the given function or method. The CoreFoundation framework defines a macro +CF_RELEASES_ARGUMENT that is functionally equivalent to the +CF_CONSUMED macro shown below.

-

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

+

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

Example

@@ -461,13 +480,13 @@ void test_method() {

Attribute 'ns_consumes_self' (Clang-specific)

-

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

+

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.

-

One use of this attribute is declare your own init-like methods that do not follow the - standard Cocoa naming conventions.

+

One use of this attribute is declare your own init-like methods that do not +follow the standard Cocoa naming conventions.

Example

@@ -490,8 +509,15 @@ void test_method() { @end -

In this example, nonstandardInitWith: has the same ownership semantics as the init method initWith:. - The static analyzer will observe that the method consumes the receiver, and then returns an object with a +1 retain count.

+

In this example, -nonstandardInitWith: has the same ownership +semantics as the init method -initWith:. The static analyzer will +observe that the method consumes the receiver, and then returns an object with +a +1 retain count.

+ +

The Foundation framework defines a macro NS_REPLACES_RECEIVER +which is functionally equivalent to the combination of NS_CONSUMES_SELF +and NS_RETURNS_RETAINED shown above.

+

Custom Assertion Handlers

diff --git a/clang/www/analyzer/available_checks.html b/clang/www/analyzer/available_checks.html index 4f8971c5507f..be15125a7e89 100644 --- a/clang/www/analyzer/available_checks.html +++ b/clang/www/analyzer/available_checks.html @@ -176,14 +176,13 @@ unix.cstring.NullArgCheck for null pointers being passed as arguments to C string functions. -

In addition to these the analyzer contains numerous experimental (beta) checkers.

+

In addition to these the analyzer contains numerous experimental (alpha) checkers.

Writeups with examples of some of the bugs that the analyzer finds

diff --git a/clang/www/analyzer/dev_cxx.html b/clang/www/analyzer/dev_cxx.html index 39dbf7b4af8f..4424a9a8b5be 100644 --- a/clang/www/analyzer/dev_cxx.html +++ b/clang/www/analyzer/dev_cxx.html @@ -15,16 +15,13 @@

C++ Support

-

The Clang frontend -now supports the -majority of C++. 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.

+

The Clang compiler supports almost all of C++11. +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.

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.

diff --git a/clang/www/analyzer/index.html b/clang/www/analyzer/index.html index 18bafd056288..33e858179df5 100644 --- a/clang/www/analyzer/index.html +++ b/clang/www/analyzer/index.html @@ -69,12 +69,12 @@

Clang Static Analyzer

-

The Clang Static Analyzer is source code analysis tool that find bugs in C -and Objective-C programs.

+

The Clang Static Analyzer is a source code analysis tool that finds bugs in +C, C++, and Objective-C programs.

-

Currently it can be run either as a standalone -tool or within Xcode. The standalone tool is -invoked from the command-line, and is intended to be run in tandem with a build +

Currently it can be run either as a standalone +tool or within Xcode. The standalone tool is +invoked from the command line, and is intended to be run in tandem with a build of a codebase.

The analyzer is 100% open source and is part of the analyzer in xcode -

Viewing static analyzer results in Xcode 3.2
+
Viewing static analyzer results in Xcode
analyzer in browser
Viewing static analyzer results in a web browser

What is Static Analysis?

-

The term "static analysis" is conflated, but here we use it to mean +

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.

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.

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

Part of Clang and LLVM

@@ -175,11 +174,11 @@ bugs, we ask you to bear in mind a few points when using it.

Work-in-Progress

-

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.

+

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.

Slower than Compilation

diff --git a/clang/www/analyzer/xcode.html b/clang/www/analyzer/xcode.html index ac75a0475470..4bae1c15b868 100644 --- a/clang/www/analyzer/xcode.html +++ b/clang/www/analyzer/xcode.html @@ -2,7 +2,7 @@ "http://www.w3.org/TR/html4/strict.dtd"> - Build and Analyze: running the analyzer within Xcode + Running the analyzer within Xcode @@ -14,15 +14,16 @@
-

Build and Analyze: running the analyzer within Xcode

+

Running the analyzer within Xcode

What is it?

-

Build and Analyze is an Xcode feature (introduced in Xcode 3.2) that -allows users to run the Clang Static Analyzer directly + +

Since Xcode 3.2, users have been able to run the Clang Static Analyzer +directly within Xcode.

It integrates directly with the Xcode build system and @@ -45,23 +46,24 @@ presents analysis results directly within Xcode's editor.

single keystroke or mouse click.
  • Transparency: Works effortlessly with Xcode projects (including iPhone projects).
  • Cons: Doesn't work well with non-Xcode projects. For those, - consider using scan-build. + consider using scan-build.

    Getting Started

    -

    Xcode 3.2 is available as a free download from Apple, with instructions available -for using Build and Analyze.

    +

    Xcode is available as a free download from Apple on the Mac +App Store, with instructions +available for using the analyzer.

    -

    Using open source analyzer builds with Build and Analyze

    +

    Using open source analyzer builds with Xcode

    By default, Xcode uses the version of clang that came bundled with -it to provide the results for Build and Analyze. It is possible to change -Xcode's behavior to use an alternate version of clang for this purpose -while continuing to use the clang that came with Xcode for compiling -projects.

    +it to analyze your code. It is possible to change Xcode's behavior to use an +alternate version of clang for this purpose while continuing to use +the clang that came with Xcode for compiling projects.

    Why try open source builds?

    @@ -78,7 +80,7 @@ issues.

    Starting with analyzer build checker-234, analyzer builds contain a command line utility called set-xcode-analyzer that allows users to change what -copy of clang that Xcode uses for Build and Analyze:

    +copy of clang that Xcode uses for analysis:

     $ set-xcode-analyzer -h
@@ -93,8 +95,8 @@ Options:

    Operationally, set-xcode-analyzer edits Xcode's configuration files -(in /Developer) to point it to use the version of clang you -specify for static analysis. Within this model it provides you two basic modes:

    +to point it to use the version of clang you specify for static +analysis. Within this model it provides you two basic modes:

    • --use-xcode-clang: Switch Xcode (back) to using the clang that came bundled with it for static analysis.
      • @@ -104,14 +106,14 @@ specify for static analysis. Within this model it provides you two basic modes:

      Things to keep in mind

        -
      • You should quit Xcode prior to running set-xcode-analyzer.
        • -
      • You will need to run set-xcode-analyzer under sudo - in order to have write privileges to modify the Xcode configuration files.
        • +
      • You should quit Xcode prior to running set-xcode-analyzer.
      • You will need to run set-xcode-analyzer under +sudo in order to have write privileges to modify the Xcode +configuration files.

      Examples

      -

      Example 1: Telling Xcode to use checker-235 for Build and Analyze:

      +

      Example 1: Telling Xcode to use checker-235:

       $ pwd