[cfe-commits] r137805 - in /cfe/trunk/include/clang/StaticAnalyzer/Core: CheckerOptInfo.h CheckerRegistry.h
Jordy Rose
jediknil at belkadan.com
Tue Aug 16 19:15:41 PDT 2011
Author: jrose
Date: Tue Aug 16 21:15:41 2011
New Revision: 137805
URL: http://llvm.org/viewvc/llvm-project?rev=137805&view=rev
Log:
[analyzer] Add some documentation for the new analyzer plugin infrastructure.
Modified:
cfe/trunk/include/clang/StaticAnalyzer/Core/CheckerOptInfo.h
cfe/trunk/include/clang/StaticAnalyzer/Core/CheckerRegistry.h
Modified: cfe/trunk/include/clang/StaticAnalyzer/Core/CheckerOptInfo.h
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/include/clang/StaticAnalyzer/Core/CheckerOptInfo.h?rev=137805&r1=137804&r2=137805&view=diff
==============================================================================
--- cfe/trunk/include/clang/StaticAnalyzer/Core/CheckerOptInfo.h (original)
+++ cfe/trunk/include/clang/StaticAnalyzer/Core/CheckerOptInfo.h Tue Aug 16 21:15:41 2011
@@ -15,6 +15,10 @@
namespace clang {
namespace ento {
+/// Represents a request to include or exclude a checker or package from a
+/// specific analysis run.
+///
+/// \sa CheckerRegistry::initializeManager
class CheckerOptInfo {
StringRef Name;
bool Enable;
Modified: cfe/trunk/include/clang/StaticAnalyzer/Core/CheckerRegistry.h
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/include/clang/StaticAnalyzer/Core/CheckerRegistry.h?rev=137805&r1=137804&r2=137805&view=diff
==============================================================================
--- cfe/trunk/include/clang/StaticAnalyzer/Core/CheckerRegistry.h (original)
+++ cfe/trunk/include/clang/StaticAnalyzer/Core/CheckerRegistry.h Tue Aug 16 21:15:41 2011
@@ -14,6 +14,47 @@
#include "clang/Basic/LLVM.h"
#include <vector>
+// FIXME: move this information to an HTML file in docs/.
+// At the very least, a checker plugin is a dynamic library that exports
+// clang_analyzerAPIVersionString. This should be defined as follows:
+//
+// extern "C"
+// const char clang_analyzerAPIVersionString[] =
+// CLANG_ANALYZER_API_VERSION_STRING;
+//
+// This is used to check whether the current version of the analyzer is known to
+// be incompatible with a plugin. Plugins with incompatible version strings,
+// or without a version string at all, will not be loaded.
+//
+// To add a custom checker to the analyzer, the plugin must also define the
+// function clang_registerCheckers. For example:
+//
+// extern "C"
+// void clang_registerCheckers (CheckerRegistry ®istry) {
+// registry.addChecker<MainCallChecker>("example.MainCallChecker",
+// "Disallows calls to functions called main");
+// }
+//
+// The first method argument is the full name of the checker, including its
+// enclosing package. By convention, the registered name of a checker is the
+// name of the associated class (the template argument).
+// The second method argument is a short human-readable description of the
+// checker.
+//
+// The clang_registerCheckers function may add any number of checkers to the
+// registry. If any checkers require additional initialization, use the three-
+// argument form of CheckerRegistry::addChecker.
+//
+// To load a checker plugin, specify the full path to the dynamic library as
+// the argument to the -load option in the cc1 frontend. You can then enable
+// your custom checker using the -analyzer-checker:
+//
+// clang -cc1 -load </path/to/plugin.dylib> -analyze
+// -analyzer-checker=<example.MainCallChecker>
+//
+// For a complete working example, see examples/analyzer-plugin.
+
+
namespace clang {
namespace ento {
@@ -28,8 +69,16 @@
class CheckerOptInfo;
+/// Manages a set of available checkers for running a static analysis.
+/// The checkers are organized into packages by full name, where including
+/// a package will recursively include all subpackages and checkers within it.
+/// For example, the checker "core.builtin.NoReturnFunctionChecker" will be
+/// included if initializeManager() is called with an option of "core",
+/// "core.builtin", or the full name "core.builtin.NoReturnFunctionChecker".
class CheckerRegistry {
public:
+ /// Initialization functions perform any necessary setup for a checker.
+ /// They should include a call to CheckerManager::registerChecker.
typedef void (*InitializationFunction)(CheckerManager &);
struct CheckerInfo {
InitializationFunction Initialize;
@@ -49,16 +98,27 @@
}
public:
+ /// Adds a checker to the registry. Use this non-templated overload when your
+ /// checker requires custom initialization.
void addChecker(InitializationFunction fn, StringRef fullName,
StringRef desc);
+ /// Adds a checker to the registry. Use this templated overload when your
+ /// checker does not require any custom initialization.
template <class T>
void addChecker(StringRef fullName, StringRef desc) {
addChecker(&initializeManager<T>, fullName, desc);
}
+ /// Initializes a CheckerManager by calling the initialization functions for
+ /// all checkers specified by the given CheckerOptInfo list. The order of this
+ /// list is significant; later options can be used to reverse earlier ones.
+ /// This can be used to exclude certain checkers in an included package.
void initializeManager(CheckerManager &mgr,
SmallVectorImpl<CheckerOptInfo> &opts) const;
+
+ /// Prints the name and description of all checkers in this registry.
+ /// This output is not intended to be machine-parseable.
void printHelp(raw_ostream &out, size_t maxNameChars = 30) const ;
private:
More information about the cfe-commits
mailing list