• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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 #ifndef CLANG_ANALYZER_API_VERSION_STRING
58 // FIXME: The Clang version string is not particularly granular;
59 // the analyzer infrastructure can change a lot between releases.
60 // Unfortunately, this string has to be statically embedded in each plugin,
61 // so we can't just use the functions defined in Version.h.
62 #include "clang/Basic/Version.h"
63 #define CLANG_ANALYZER_API_VERSION_STRING CLANG_VERSION_STRING
64 #endif
65 
66 namespace clang {
67 class DiagnosticsEngine;
68 class AnalyzerOptions;
69 
70 namespace ento {
71 
72 class CheckerOptInfo;
73 
74 /// Manages a set of available checkers for running a static analysis.
75 /// The checkers are organized into packages by full name, where including
76 /// a package will recursively include all subpackages and checkers within it.
77 /// For example, the checker "core.builtin.NoReturnFunctionChecker" will be
78 /// included if initializeManager() is called with an option of "core",
79 /// "core.builtin", or the full name "core.builtin.NoReturnFunctionChecker".
80 class CheckerRegistry {
81 public:
82   /// Initialization functions perform any necessary setup for a checker.
83   /// They should include a call to CheckerManager::registerChecker.
84   typedef void (*InitializationFunction)(CheckerManager &);
85   struct CheckerInfo {
86     InitializationFunction Initialize;
87     StringRef FullName;
88     StringRef Desc;
89 
CheckerInfoCheckerInfo90     CheckerInfo(InitializationFunction fn, StringRef name, StringRef desc)
91     : Initialize(fn), FullName(name), Desc(desc) {}
92   };
93 
94   typedef std::vector<CheckerInfo> CheckerInfoList;
95 
96 private:
97   template <typename T>
initializeManager(CheckerManager & mgr)98   static void initializeManager(CheckerManager &mgr) {
99     mgr.registerChecker<T>();
100   }
101 
102 public:
103   /// Adds a checker to the registry. Use this non-templated overload when your
104   /// checker requires custom initialization.
105   void addChecker(InitializationFunction fn, StringRef fullName,
106                   StringRef desc);
107 
108   /// Adds a checker to the registry. Use this templated overload when your
109   /// checker does not require any custom initialization.
110   template <class T>
addChecker(StringRef fullName,StringRef desc)111   void addChecker(StringRef fullName, StringRef desc) {
112     // Avoid MSVC's Compiler Error C2276:
113     // http://msdn.microsoft.com/en-us/library/850cstw1(v=VS.80).aspx
114     addChecker(&CheckerRegistry::initializeManager<T>, fullName, desc);
115   }
116 
117   /// Initializes a CheckerManager by calling the initialization functions for
118   /// all checkers specified by the given CheckerOptInfo list. The order of this
119   /// list is significant; later options can be used to reverse earlier ones.
120   /// This can be used to exclude certain checkers in an included package.
121   void initializeManager(CheckerManager &mgr,
122                          SmallVectorImpl<CheckerOptInfo> &opts) const;
123 
124   /// Check if every option corresponds to a specific checker or package.
125   void validateCheckerOptions(const AnalyzerOptions &opts,
126                               DiagnosticsEngine &diags) const;
127 
128   /// Prints the name and description of all checkers in this registry.
129   /// This output is not intended to be machine-parseable.
130   void printHelp(raw_ostream &out, size_t maxNameChars = 30) const ;
131 
132 private:
133   mutable CheckerInfoList Checkers;
134   mutable llvm::StringMap<size_t> Packages;
135 };
136 
137 } // end namespace ento
138 } // end namespace clang
139 
140 #endif
141