clang  8.0.0svn
CheckerRegistry.h
Go to the documentation of this file.
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"
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".
83 public:
85 
86  /// Initialization functions perform any necessary setup for a checker.
87  /// They should include a call to CheckerManager::registerChecker.
89 
90  struct CheckerInfo {
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
Manages a set of available checkers for running a static analysis.
llvm::SetVector< const CheckerRegistry::CheckerInfo * > CheckerInfoSet
void printList(raw_ostream &out, const AnalyzerOptions &opts) const
CheckerRegistry(ArrayRef< std::string > plugins, DiagnosticsEngine &diags)
CheckerInfo(InitializationFunction Fn, StringRef Name, StringRef Desc, StringRef DocsUri)
Forward-declares and imports various common LLVM datatypes that clang wants to use unqualified...
Concrete class used by the front-end to report problems and issues.
Definition: Diagnostic.h:149
void validateCheckerOptions(const AnalyzerOptions &opts) const
Check if every option corresponds to a specific checker or package.
Defines version macros and version-related utility functions for Clang.
void addChecker(InitializationFunction Fn, StringRef FullName, StringRef Desc, StringRef DocsUri)
Adds a checker to the registry.
CHECKER * registerChecker(AT &&... Args)
Used to register checkers.
Dataflow Directional Tag Classes.
void(*)(CheckerManager &) InitializationFunction
Initialization functions perform any necessary setup for a checker.
std::vector< CheckerInfo > CheckerInfoList
void addChecker(StringRef FullName, StringRef Desc, StringRef DocsUri)
Adds a checker to the registry.
Stores options for the analyzer from the command line.
void printHelp(raw_ostream &out, size_t maxNameChars=30) const
Prints the name and description of all checkers in this registry.