contrib/llvm/tools/clang/include/clang/StaticAnalyzer/Core/CheckerRegistry.h

   1 //===--- CheckerRegistry.h - Maintains all available checkers ---*- C++ -*-===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file is distributed under the University of Illinois Open Source
   6 // License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9
  10 #ifndef LLVM_CLANG_STATICANALYZER_CORE_CHECKERREGISTRY_H
  11 #define LLVM_CLANG_STATICANALYZER_CORE_CHECKERREGISTRY_H
  12
  13 #include "clang/Basic/LLVM.h"
  14 #include "clang/StaticAnalyzer/Core/CheckerManager.h"
  15 #include <vector>
  16
  17 // FIXME: move this information to an HTML file in docs/.
  18 // At the very least, a checker plugin is a dynamic library that exports
  19 // clang_analyzerAPIVersionString. This should be defined as follows:
  20 //
  21 //   extern "C"
  22 //   const char clang_analyzerAPIVersionString[] =
  23 //     CLANG_ANALYZER_API_VERSION_STRING;
  24 //
  25 // This is used to check whether the current version of the analyzer is known to
  26 // be incompatible with a plugin. Plugins with incompatible version strings,
  27 // or without a version string at all, will not be loaded.
  28 //
  29 // To add a custom checker to the analyzer, the plugin must also define the
  30 // function clang_registerCheckers. For example:
  31 //
  32 //    extern "C"
  33 //    void clang_registerCheckers (CheckerRegistry &registry) {
  34 //      registry.addChecker<MainCallChecker>("example.MainCallChecker",
  35 //        "Disallows calls to functions called main");
  36 //    }
  37 //
  38 // The first method argument is the full name of the checker, including its
  39 // enclosing package. By convention, the registered name of a checker is the
  40 // name of the associated class (the template argument).
  41 // The second method argument is a short human-readable description of the
  42 // checker.
  43 //
  44 // The clang_registerCheckers function may add any number of checkers to the
  45 // registry. If any checkers require additional initialization, use the three-
  46 // argument form of CheckerRegistry::addChecker.
  47 //
  48 // To load a checker plugin, specify the full path to the dynamic library as
  49 // the argument to the -load option in the cc1 frontend. You can then enable
  50 // your custom checker using the -analyzer-checker:
  51 //
  52 //   clang -cc1 -load </path/to/plugin.dylib> -analyze
  53 //     -analyzer-checker=<example.MainCallChecker>
  54 //
  55 // For a complete working example, see examples/analyzer-plugin.
  56
  57
  58 namespace clang {
  59 namespace ento {
  60
  61 #ifndef CLANG_ANALYZER_API_VERSION_STRING
  62 // FIXME: The Clang version string is not particularly granular;
  63 // the analyzer infrastructure can change a lot between releases.
  64 // Unfortunately, this string has to be statically embedded in each plugin,
  65 // so we can't just use the functions defined in Version.h.
  66 #include "clang/Basic/Version.h"
  67 #define CLANG_ANALYZER_API_VERSION_STRING CLANG_VERSION_STRING
  68 #endif
  69
  70 class CheckerOptInfo;
  71
  72 /// Manages a set of available checkers for running a static analysis.
  73 /// The checkers are organized into packages by full name, where including
  74 /// a package will recursively include all subpackages and checkers within it.
  75 /// For example, the checker "core.builtin.NoReturnFunctionChecker" will be
  76 /// included if initializeManager() is called with an option of "core",
  77 /// "core.builtin", or the full name "core.builtin.NoReturnFunctionChecker".
  78 class CheckerRegistry {
  79 public:
  80   /// Initialization functions perform any necessary setup for a checker.
  81   /// They should include a call to CheckerManager::registerChecker.
  82   typedef void (*InitializationFunction)(CheckerManager &);
  83   struct CheckerInfo {
  84     InitializationFunction Initialize;
  85     StringRef FullName;
  86     StringRef Desc;
  87
  88     CheckerInfo(InitializationFunction fn, StringRef name, StringRef desc)
  89     : Initialize(fn), FullName(name), Desc(desc) {}
  90   };
  91
  92   typedef std::vector<CheckerInfo> CheckerInfoList;
  93
  94 private:
  95   template <typename T>
  96   static void initializeManager(CheckerManager &mgr) {
  97     mgr.registerChecker<T>();
  98   }
  99
 100 public:
 101   /// Adds a checker to the registry. Use this non-templated overload when your
 102   /// checker requires custom initialization.
 103   void addChecker(InitializationFunction fn, StringRef fullName,
 104                   StringRef desc);
 105
 106   /// Adds a checker to the registry. Use this templated overload when your
 107   /// checker does not require any custom initialization.
 108   template <class T>
 109   void addChecker(StringRef fullName, StringRef desc) {
 110     // Avoid MSVC's Compiler Error C2276:
 111     // http://msdn.microsoft.com/en-us/library/850cstw1(v=VS.80).aspx
 112     addChecker(&CheckerRegistry::initializeManager<T>, fullName, desc);
 113   }
 114
 115   /// Initializes a CheckerManager by calling the initialization functions for
 116   /// all checkers specified by the given CheckerOptInfo list. The order of this
 117   /// list is significant; later options can be used to reverse earlier ones.
 118   /// This can be used to exclude certain checkers in an included package.
 119   void initializeManager(CheckerManager &mgr,
 120                          SmallVectorImpl<CheckerOptInfo> &opts) const;
 121
 122   /// Prints the name and description of all checkers in this registry.
 123   /// This output is not intended to be machine-parseable.
 124   void printHelp(raw_ostream &out, size_t maxNameChars = 30) const ;
 125
 126 private:
 127   mutable CheckerInfoList Checkers;
 128   mutable llvm::StringMap<size_t> Packages;
 129 };
 130
 131 } // end namespace ento
 132 } // end namespace clang
 133
 134 #endif