1 //===- CheckerRegistry.h - Maintains all available checkers -----*- C++ -*-===// 2 // 3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. 4 // See https://llvm.org/LICENSE.txt for license information. 5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 6 // 7 //===----------------------------------------------------------------------===// 8 // 9 // Contains the logic for parsing the TableGen file Checkers.td, and parsing the 10 // specific invocation of the analyzer (which checker/package is enabled, values 11 // of their options, etc). This is in the frontend library because checker 12 // registry functions are called from here but are defined in the dependent 13 // library libStaticAnalyzerCheckers, but the actual data structure that holds 14 // the parsed information is in the Core library. 15 // 16 //===----------------------------------------------------------------------===// 17 18 #ifndef LLVM_CLANG_STATICANALYZER_FRONTEND_CHECKERREGISTRY_H 19 #define LLVM_CLANG_STATICANALYZER_FRONTEND_CHECKERREGISTRY_H 20 21 #include "clang/Basic/LLVM.h" 22 #include "clang/StaticAnalyzer/Core/CheckerRegistryData.h" 23 #include "llvm/ADT/StringRef.h" 24 25 // FIXME: move this information to an HTML file in docs/. 26 // At the very least, a checker plugin is a dynamic library that exports 27 // clang_analyzerAPIVersionString. This should be defined as follows: 28 // 29 // extern "C" 30 // const char clang_analyzerAPIVersionString[] = 31 // CLANG_ANALYZER_API_VERSION_STRING; 32 // 33 // This is used to check whether the current version of the analyzer is known to 34 // be incompatible with a plugin. Plugins with incompatible version strings, 35 // or without a version string at all, will not be loaded. 36 // 37 // To add a custom checker to the analyzer, the plugin must also define the 38 // function clang_registerCheckers. For example: 39 // 40 // extern "C" 41 // void clang_registerCheckers (CheckerRegistry ®istry) { 42 // registry.addChecker<MainCallChecker>("example.MainCallChecker", 43 // "Disallows calls to functions called main"); 44 // } 45 // 46 // The first method argument is the full name of the checker, including its 47 // enclosing package. By convention, the registered name of a checker is the 48 // name of the associated class (the template argument). 49 // The second method argument is a short human-readable description of the 50 // checker. 51 // 52 // The clang_registerCheckers function may add any number of checkers to the 53 // registry. If any checkers require additional initialization, use the three- 54 // argument form of CheckerRegistry::addChecker. 55 // 56 // To load a checker plugin, specify the full path to the dynamic library as 57 // the argument to the -load option in the cc1 frontend. You can then enable 58 // your custom checker using the -analyzer-checker: 59 // 60 // clang -cc1 -load </path/to/plugin.dylib> -analyze 61 // -analyzer-checker=<example.MainCallChecker> 62 // 63 // For a complete working example, see examples/analyzer-plugin. 64 65 #ifndef CLANG_ANALYZER_API_VERSION_STRING 66 // FIXME: The Clang version string is not particularly granular; 67 // the analyzer infrastructure can change a lot between releases. 68 // Unfortunately, this string has to be statically embedded in each plugin, 69 // so we can't just use the functions defined in Version.h. 70 #include "clang/Basic/Version.h" 71 #define CLANG_ANALYZER_API_VERSION_STRING CLANG_VERSION_STRING 72 #endif 73 74 namespace clang { 75 76 class AnalyzerOptions; 77 class DiagnosticsEngine; 78 79 namespace ento { 80 81 class CheckerManager; 82 83 /// Manages a set of available checkers for running a static analysis. 84 /// The checkers are organized into packages by full name, where including 85 /// a package will recursively include all subpackages and checkers within it. 86 /// For example, the checker "core.builtin.NoReturnFunctionChecker" will be 87 /// included if initializeManager() is called with an option of "core", 88 /// "core.builtin", or the full name "core.builtin.NoReturnFunctionChecker". 89 class CheckerRegistry { 90 public: 91 CheckerRegistry(CheckerRegistryData &Data, ArrayRef<std::string> Plugins, 92 DiagnosticsEngine &Diags, AnalyzerOptions &AnOpts, 93 ArrayRef<std::function<void(CheckerRegistry &)>> 94 CheckerRegistrationFns = {}); 95 96 /// Collects all enabled checkers in the field EnabledCheckers. It preserves 97 /// the order of insertion, as dependencies have to be enabled before the 98 /// checkers that depend on them. 99 void initializeRegistry(const CheckerManager &Mgr); 100 101 102 private: 103 /// Default initialization function for checkers -- since CheckerManager 104 /// includes this header, we need to make it a template parameter, and since 105 /// the checker must be a template parameter as well, we can't put this in the 106 /// cpp file. initializeManager(MGR & mgr)107 template <typename MGR, typename T> static void initializeManager(MGR &mgr) { 108 mgr.template registerChecker<T>(); 109 } 110 returnTrue(const CheckerManager & mgr)111 template <typename T> static bool returnTrue(const CheckerManager &mgr) { 112 return true; 113 } 114 115 public: 116 /// Adds a checker to the registry. Use this non-templated overload when your 117 /// checker requires custom initialization. 118 void addChecker(RegisterCheckerFn Fn, ShouldRegisterFunction sfn, 119 StringRef FullName, StringRef Desc, StringRef DocsUri, 120 bool IsHidden); 121 122 /// Adds a checker to the registry. Use this templated overload when your 123 /// checker does not require any custom initialization. 124 /// This function isn't really needed and probably causes more headaches than 125 /// the tiny convenience that it provides, but external plugins might use it, 126 /// and there isn't a strong incentive to remove it. 127 template <class T> 128 void addChecker(StringRef FullName, StringRef Desc, StringRef DocsUri, 129 bool IsHidden = false) { 130 // Avoid MSVC's Compiler Error C2276: 131 // http://msdn.microsoft.com/en-us/library/850cstw1(v=VS.80).aspx 132 addChecker(&CheckerRegistry::initializeManager<CheckerManager, T>, 133 &CheckerRegistry::returnTrue<T>, FullName, Desc, DocsUri, 134 IsHidden); 135 } 136 137 /// Makes the checker with the full name \p fullName depend on the checker 138 /// called \p dependency. 139 void addDependency(StringRef FullName, StringRef Dependency); 140 141 /// Makes the checker with the full name \p fullName weak depend on the 142 /// checker called \p dependency. 143 void addWeakDependency(StringRef FullName, StringRef Dependency); 144 145 /// Registers an option to a given checker. A checker option will always have 146 /// the following format: 147 /// CheckerFullName:OptionName=Value 148 /// And can be specified from the command line like this: 149 /// -analyzer-config CheckerFullName:OptionName=Value 150 /// 151 /// Options for unknown checkers, or unknown options for a given checker, or 152 /// invalid value types for that given option are reported as an error in 153 /// non-compatibility mode. 154 void addCheckerOption(StringRef OptionType, StringRef CheckerFullName, 155 StringRef OptionName, StringRef DefaultValStr, 156 StringRef Description, StringRef DevelopmentStatus, 157 bool IsHidden = false); 158 159 /// Adds a package to the registry. 160 void addPackage(StringRef FullName); 161 162 /// Registers an option to a given package. A package option will always have 163 /// the following format: 164 /// PackageFullName:OptionName=Value 165 /// And can be specified from the command line like this: 166 /// -analyzer-config PackageFullName:OptionName=Value 167 /// 168 /// Options for unknown packages, or unknown options for a given package, or 169 /// invalid value types for that given option are reported as an error in 170 /// non-compatibility mode. 171 void addPackageOption(StringRef OptionType, StringRef PackageFullName, 172 StringRef OptionName, StringRef DefaultValStr, 173 StringRef Description, StringRef DevelopmentStatus, 174 bool IsHidden = false); 175 176 // FIXME: This *really* should be added to the frontend flag descriptions. 177 /// Initializes a CheckerManager by calling the initialization functions for 178 /// all checkers specified by the given CheckerOptInfo list. The order of this 179 /// list is significant; later options can be used to reverse earlier ones. 180 /// This can be used to exclude certain checkers in an included package. 181 void initializeManager(CheckerManager &CheckerMgr) const; 182 183 /// Check if every option corresponds to a specific checker or package. 184 void validateCheckerOptions() const; 185 186 private: 187 template <bool IsWeak> void resolveDependencies(); 188 void resolveCheckerAndPackageOptions(); 189 190 CheckerRegistryData &Data; 191 192 DiagnosticsEngine &Diags; 193 AnalyzerOptions &AnOpts; 194 }; 195 196 } // namespace ento 197 } // namespace clang 198 199 #endif // LLVM_CLANG_STATICANALYZER_FRONTEND_CHECKERREGISTRY_H 200