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 ®istry) { 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 CheckerInfoCheckerInfo96 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> initializeManager(CheckerManager & mgr)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> addChecker(StringRef FullName,StringRef Desc,StringRef DocsUri)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 154