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
66namespace clang {
67class DiagnosticsEngine;
68class AnalyzerOptions;
69
70namespace ento {
71
72class 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".
80class CheckerRegistry {
81public:
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
90    CheckerInfo(InitializationFunction fn, StringRef name, StringRef desc)
91    : Initialize(fn), FullName(name), Desc(desc) {}
92  };
93
94  typedef std::vector<CheckerInfo> CheckerInfoList;
95
96private:
97  template <typename T>
98  static void initializeManager(CheckerManager &mgr) {
99    mgr.registerChecker<T>();
100  }
101
102public:
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>
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
132private:
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