1226586Sdim//===--- CheckerRegistry.h - Maintains all available checkers ---*- C++ -*-===// 2226586Sdim// 3226586Sdim// The LLVM Compiler Infrastructure 4226586Sdim// 5226586Sdim// This file is distributed under the University of Illinois Open Source 6226586Sdim// License. See LICENSE.TXT for details. 7226586Sdim// 8226586Sdim//===----------------------------------------------------------------------===// 9226586Sdim 10226586Sdim#ifndef LLVM_CLANG_STATICANALYZER_CORE_CHECKERREGISTRY_H 11226586Sdim#define LLVM_CLANG_STATICANALYZER_CORE_CHECKERREGISTRY_H 12226586Sdim 13252723Sdim#include "clang/Basic/LLVM.h" 14226586Sdim#include "clang/StaticAnalyzer/Core/CheckerManager.h" 15226586Sdim#include <vector> 16226586Sdim 17226586Sdim// FIXME: move this information to an HTML file in docs/. 18226586Sdim// At the very least, a checker plugin is a dynamic library that exports 19226586Sdim// clang_analyzerAPIVersionString. This should be defined as follows: 20226586Sdim// 21226586Sdim// extern "C" 22226586Sdim// const char clang_analyzerAPIVersionString[] = 23226586Sdim// CLANG_ANALYZER_API_VERSION_STRING; 24226586Sdim// 25226586Sdim// This is used to check whether the current version of the analyzer is known to 26226586Sdim// be incompatible with a plugin. Plugins with incompatible version strings, 27226586Sdim// or without a version string at all, will not be loaded. 28226586Sdim// 29226586Sdim// To add a custom checker to the analyzer, the plugin must also define the 30226586Sdim// function clang_registerCheckers. For example: 31226586Sdim// 32226586Sdim// extern "C" 33226586Sdim// void clang_registerCheckers (CheckerRegistry ®istry) { 34226586Sdim// registry.addChecker<MainCallChecker>("example.MainCallChecker", 35226586Sdim// "Disallows calls to functions called main"); 36226586Sdim// } 37226586Sdim// 38226586Sdim// The first method argument is the full name of the checker, including its 39226586Sdim// enclosing package. By convention, the registered name of a checker is the 40226586Sdim// name of the associated class (the template argument). 41226586Sdim// The second method argument is a short human-readable description of the 42226586Sdim// checker. 43226586Sdim// 44226586Sdim// The clang_registerCheckers function may add any number of checkers to the 45226586Sdim// registry. If any checkers require additional initialization, use the three- 46226586Sdim// argument form of CheckerRegistry::addChecker. 47226586Sdim// 48226586Sdim// To load a checker plugin, specify the full path to the dynamic library as 49226586Sdim// the argument to the -load option in the cc1 frontend. You can then enable 50226586Sdim// your custom checker using the -analyzer-checker: 51226586Sdim// 52226586Sdim// clang -cc1 -load </path/to/plugin.dylib> -analyze 53226586Sdim// -analyzer-checker=<example.MainCallChecker> 54226586Sdim// 55226586Sdim// For a complete working example, see examples/analyzer-plugin. 56226586Sdim 57226586Sdim#ifndef CLANG_ANALYZER_API_VERSION_STRING 58226586Sdim// FIXME: The Clang version string is not particularly granular; 59226586Sdim// the analyzer infrastructure can change a lot between releases. 60226586Sdim// Unfortunately, this string has to be statically embedded in each plugin, 61226586Sdim// so we can't just use the functions defined in Version.h. 62226586Sdim#include "clang/Basic/Version.h" 63226586Sdim#define CLANG_ANALYZER_API_VERSION_STRING CLANG_VERSION_STRING 64226586Sdim#endif 65226586Sdim 66263509Sdimnamespace clang { 67263509Sdimnamespace ento { 68263509Sdim 69226586Sdimclass CheckerOptInfo; 70226586Sdim 71226586Sdim/// Manages a set of available checkers for running a static analysis. 72226586Sdim/// The checkers are organized into packages by full name, where including 73226586Sdim/// a package will recursively include all subpackages and checkers within it. 74226586Sdim/// For example, the checker "core.builtin.NoReturnFunctionChecker" will be 75226586Sdim/// included if initializeManager() is called with an option of "core", 76226586Sdim/// "core.builtin", or the full name "core.builtin.NoReturnFunctionChecker". 77226586Sdimclass CheckerRegistry { 78226586Sdimpublic: 79226586Sdim /// Initialization functions perform any necessary setup for a checker. 80226586Sdim /// They should include a call to CheckerManager::registerChecker. 81226586Sdim typedef void (*InitializationFunction)(CheckerManager &); 82226586Sdim struct CheckerInfo { 83226586Sdim InitializationFunction Initialize; 84226586Sdim StringRef FullName; 85226586Sdim StringRef Desc; 86226586Sdim 87226586Sdim CheckerInfo(InitializationFunction fn, StringRef name, StringRef desc) 88226586Sdim : Initialize(fn), FullName(name), Desc(desc) {} 89226586Sdim }; 90226586Sdim 91226586Sdim typedef std::vector<CheckerInfo> CheckerInfoList; 92226586Sdim 93226586Sdimprivate: 94226586Sdim template <typename T> 95226586Sdim static void initializeManager(CheckerManager &mgr) { 96226586Sdim mgr.registerChecker<T>(); 97226586Sdim } 98226586Sdim 99226586Sdimpublic: 100226586Sdim /// Adds a checker to the registry. Use this non-templated overload when your 101226586Sdim /// checker requires custom initialization. 102226586Sdim void addChecker(InitializationFunction fn, StringRef fullName, 103226586Sdim StringRef desc); 104226586Sdim 105226586Sdim /// Adds a checker to the registry. Use this templated overload when your 106226586Sdim /// checker does not require any custom initialization. 107226586Sdim template <class T> 108226586Sdim void addChecker(StringRef fullName, StringRef desc) { 109235633Sdim // Avoid MSVC's Compiler Error C2276: 110235633Sdim // http://msdn.microsoft.com/en-us/library/850cstw1(v=VS.80).aspx 111235633Sdim addChecker(&CheckerRegistry::initializeManager<T>, fullName, desc); 112226586Sdim } 113226586Sdim 114226586Sdim /// Initializes a CheckerManager by calling the initialization functions for 115226586Sdim /// all checkers specified by the given CheckerOptInfo list. The order of this 116226586Sdim /// list is significant; later options can be used to reverse earlier ones. 117226586Sdim /// This can be used to exclude certain checkers in an included package. 118226586Sdim void initializeManager(CheckerManager &mgr, 119226586Sdim SmallVectorImpl<CheckerOptInfo> &opts) const; 120226586Sdim 121226586Sdim /// Prints the name and description of all checkers in this registry. 122226586Sdim /// This output is not intended to be machine-parseable. 123226586Sdim void printHelp(raw_ostream &out, size_t maxNameChars = 30) const ; 124226586Sdim 125226586Sdimprivate: 126226586Sdim mutable CheckerInfoList Checkers; 127226586Sdim mutable llvm::StringMap<size_t> Packages; 128226586Sdim}; 129226586Sdim 130226586Sdim} // end namespace ento 131226586Sdim} // end namespace clang 132226586Sdim 133226586Sdim#endif 134