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