108b86531ade68727c56918f162816075b87c864aJordy Rose//===--- CheckerRegistry.h - Maintains all available checkers ---*- C++ -*-===//
208b86531ade68727c56918f162816075b87c864aJordy Rose//
308b86531ade68727c56918f162816075b87c864aJordy Rose//                     The LLVM Compiler Infrastructure
408b86531ade68727c56918f162816075b87c864aJordy Rose//
508b86531ade68727c56918f162816075b87c864aJordy Rose// This file is distributed under the University of Illinois Open Source
608b86531ade68727c56918f162816075b87c864aJordy Rose// License. See LICENSE.TXT for details.
708b86531ade68727c56918f162816075b87c864aJordy Rose//
808b86531ade68727c56918f162816075b87c864aJordy Rose//===----------------------------------------------------------------------===//
908b86531ade68727c56918f162816075b87c864aJordy Rose
1008b86531ade68727c56918f162816075b87c864aJordy Rose#ifndef LLVM_CLANG_STATICANALYZER_CORE_CHECKERREGISTRY_H
1108b86531ade68727c56918f162816075b87c864aJordy Rose#define LLVM_CLANG_STATICANALYZER_CORE_CHECKERREGISTRY_H
1208b86531ade68727c56918f162816075b87c864aJordy Rose
1308b86531ade68727c56918f162816075b87c864aJordy Rose#include "clang/Basic/LLVM.h"
1430a2e16f6c27f888dd11eba6bbbae1e980078fcbChandler Carruth#include "clang/StaticAnalyzer/Core/CheckerManager.h"
1508b86531ade68727c56918f162816075b87c864aJordy Rose#include <vector>
1608b86531ade68727c56918f162816075b87c864aJordy Rose
178e240498dfd4355849bcec943e97799f7f75d93dJordy Rose// FIXME: move this information to an HTML file in docs/.
188e240498dfd4355849bcec943e97799f7f75d93dJordy Rose// At the very least, a checker plugin is a dynamic library that exports
198e240498dfd4355849bcec943e97799f7f75d93dJordy Rose// clang_analyzerAPIVersionString. This should be defined as follows:
208e240498dfd4355849bcec943e97799f7f75d93dJordy Rose//
218e240498dfd4355849bcec943e97799f7f75d93dJordy Rose//   extern "C"
228e240498dfd4355849bcec943e97799f7f75d93dJordy Rose//   const char clang_analyzerAPIVersionString[] =
238e240498dfd4355849bcec943e97799f7f75d93dJordy Rose//     CLANG_ANALYZER_API_VERSION_STRING;
248e240498dfd4355849bcec943e97799f7f75d93dJordy Rose//
258e240498dfd4355849bcec943e97799f7f75d93dJordy Rose// This is used to check whether the current version of the analyzer is known to
268e240498dfd4355849bcec943e97799f7f75d93dJordy Rose// be incompatible with a plugin. Plugins with incompatible version strings,
278e240498dfd4355849bcec943e97799f7f75d93dJordy Rose// or without a version string at all, will not be loaded.
288e240498dfd4355849bcec943e97799f7f75d93dJordy Rose//
298e240498dfd4355849bcec943e97799f7f75d93dJordy Rose// To add a custom checker to the analyzer, the plugin must also define the
308e240498dfd4355849bcec943e97799f7f75d93dJordy Rose// function clang_registerCheckers. For example:
318e240498dfd4355849bcec943e97799f7f75d93dJordy Rose//
328e240498dfd4355849bcec943e97799f7f75d93dJordy Rose//    extern "C"
338e240498dfd4355849bcec943e97799f7f75d93dJordy Rose//    void clang_registerCheckers (CheckerRegistry &registry) {
348e240498dfd4355849bcec943e97799f7f75d93dJordy Rose//      registry.addChecker<MainCallChecker>("example.MainCallChecker",
358e240498dfd4355849bcec943e97799f7f75d93dJordy Rose//        "Disallows calls to functions called main");
368e240498dfd4355849bcec943e97799f7f75d93dJordy Rose//    }
378e240498dfd4355849bcec943e97799f7f75d93dJordy Rose//
388e240498dfd4355849bcec943e97799f7f75d93dJordy Rose// The first method argument is the full name of the checker, including its
398e240498dfd4355849bcec943e97799f7f75d93dJordy Rose// enclosing package. By convention, the registered name of a checker is the
408e240498dfd4355849bcec943e97799f7f75d93dJordy Rose// name of the associated class (the template argument).
418e240498dfd4355849bcec943e97799f7f75d93dJordy Rose// The second method argument is a short human-readable description of the
428e240498dfd4355849bcec943e97799f7f75d93dJordy Rose// checker.
438e240498dfd4355849bcec943e97799f7f75d93dJordy Rose//
448e240498dfd4355849bcec943e97799f7f75d93dJordy Rose// The clang_registerCheckers function may add any number of checkers to the
458e240498dfd4355849bcec943e97799f7f75d93dJordy Rose// registry. If any checkers require additional initialization, use the three-
468e240498dfd4355849bcec943e97799f7f75d93dJordy Rose// argument form of CheckerRegistry::addChecker.
478e240498dfd4355849bcec943e97799f7f75d93dJordy Rose//
488e240498dfd4355849bcec943e97799f7f75d93dJordy Rose// To load a checker plugin, specify the full path to the dynamic library as
498e240498dfd4355849bcec943e97799f7f75d93dJordy Rose// the argument to the -load option in the cc1 frontend. You can then enable
508e240498dfd4355849bcec943e97799f7f75d93dJordy Rose// your custom checker using the -analyzer-checker:
518e240498dfd4355849bcec943e97799f7f75d93dJordy Rose//
528e240498dfd4355849bcec943e97799f7f75d93dJordy Rose//   clang -cc1 -load </path/to/plugin.dylib> -analyze
538e240498dfd4355849bcec943e97799f7f75d93dJordy Rose//     -analyzer-checker=<example.MainCallChecker>
548e240498dfd4355849bcec943e97799f7f75d93dJordy Rose//
558e240498dfd4355849bcec943e97799f7f75d93dJordy Rose// For a complete working example, see examples/analyzer-plugin.
568e240498dfd4355849bcec943e97799f7f75d93dJordy Rose
5777a33a71701b59affb5337d9e2b57d69bc095c7dJordy Rose#ifndef CLANG_ANALYZER_API_VERSION_STRING
5877a33a71701b59affb5337d9e2b57d69bc095c7dJordy Rose// FIXME: The Clang version string is not particularly granular;
5977a33a71701b59affb5337d9e2b57d69bc095c7dJordy Rose// the analyzer infrastructure can change a lot between releases.
6077a33a71701b59affb5337d9e2b57d69bc095c7dJordy Rose// Unfortunately, this string has to be statically embedded in each plugin,
6177a33a71701b59affb5337d9e2b57d69bc095c7dJordy Rose// so we can't just use the functions defined in Version.h.
6277a33a71701b59affb5337d9e2b57d69bc095c7dJordy Rose#include "clang/Basic/Version.h"
6377a33a71701b59affb5337d9e2b57d69bc095c7dJordy Rose#define CLANG_ANALYZER_API_VERSION_STRING CLANG_VERSION_STRING
6477a33a71701b59affb5337d9e2b57d69bc095c7dJordy Rose#endif
6577a33a71701b59affb5337d9e2b57d69bc095c7dJordy Rose
66642a4dbc220854927e2e390d11312f1e46a9ae63Jordan Rosenamespace clang {
67642a4dbc220854927e2e390d11312f1e46a9ae63Jordan Rosenamespace ento {
68642a4dbc220854927e2e390d11312f1e46a9ae63Jordan Rose
6908b86531ade68727c56918f162816075b87c864aJordy Roseclass CheckerOptInfo;
7008b86531ade68727c56918f162816075b87c864aJordy Rose
718e240498dfd4355849bcec943e97799f7f75d93dJordy Rose/// Manages a set of available checkers for running a static analysis.
728e240498dfd4355849bcec943e97799f7f75d93dJordy Rose/// The checkers are organized into packages by full name, where including
738e240498dfd4355849bcec943e97799f7f75d93dJordy Rose/// a package will recursively include all subpackages and checkers within it.
748e240498dfd4355849bcec943e97799f7f75d93dJordy Rose/// For example, the checker "core.builtin.NoReturnFunctionChecker" will be
758e240498dfd4355849bcec943e97799f7f75d93dJordy Rose/// included if initializeManager() is called with an option of "core",
768e240498dfd4355849bcec943e97799f7f75d93dJordy Rose/// "core.builtin", or the full name "core.builtin.NoReturnFunctionChecker".
7708b86531ade68727c56918f162816075b87c864aJordy Roseclass CheckerRegistry {
7808b86531ade68727c56918f162816075b87c864aJordy Rosepublic:
798e240498dfd4355849bcec943e97799f7f75d93dJordy Rose  /// Initialization functions perform any necessary setup for a checker.
808e240498dfd4355849bcec943e97799f7f75d93dJordy Rose  /// They should include a call to CheckerManager::registerChecker.
8108b86531ade68727c56918f162816075b87c864aJordy Rose  typedef void (*InitializationFunction)(CheckerManager &);
8208b86531ade68727c56918f162816075b87c864aJordy Rose  struct CheckerInfo {
8308b86531ade68727c56918f162816075b87c864aJordy Rose    InitializationFunction Initialize;
8408b86531ade68727c56918f162816075b87c864aJordy Rose    StringRef FullName;
8508b86531ade68727c56918f162816075b87c864aJordy Rose    StringRef Desc;
8608b86531ade68727c56918f162816075b87c864aJordy Rose
8708b86531ade68727c56918f162816075b87c864aJordy Rose    CheckerInfo(InitializationFunction fn, StringRef name, StringRef desc)
8808b86531ade68727c56918f162816075b87c864aJordy Rose    : Initialize(fn), FullName(name), Desc(desc) {}
8908b86531ade68727c56918f162816075b87c864aJordy Rose  };
9008b86531ade68727c56918f162816075b87c864aJordy Rose
9108b86531ade68727c56918f162816075b87c864aJordy Rose  typedef std::vector<CheckerInfo> CheckerInfoList;
9208b86531ade68727c56918f162816075b87c864aJordy Rose
9308b86531ade68727c56918f162816075b87c864aJordy Roseprivate:
9408b86531ade68727c56918f162816075b87c864aJordy Rose  template <typename T>
9508b86531ade68727c56918f162816075b87c864aJordy Rose  static void initializeManager(CheckerManager &mgr) {
9608b86531ade68727c56918f162816075b87c864aJordy Rose    mgr.registerChecker<T>();
9708b86531ade68727c56918f162816075b87c864aJordy Rose  }
9808b86531ade68727c56918f162816075b87c864aJordy Rose
9908b86531ade68727c56918f162816075b87c864aJordy Rosepublic:
1008e240498dfd4355849bcec943e97799f7f75d93dJordy Rose  /// Adds a checker to the registry. Use this non-templated overload when your
1018e240498dfd4355849bcec943e97799f7f75d93dJordy Rose  /// checker requires custom initialization.
10208b86531ade68727c56918f162816075b87c864aJordy Rose  void addChecker(InitializationFunction fn, StringRef fullName,
10308b86531ade68727c56918f162816075b87c864aJordy Rose                  StringRef desc);
10408b86531ade68727c56918f162816075b87c864aJordy Rose
1058e240498dfd4355849bcec943e97799f7f75d93dJordy Rose  /// Adds a checker to the registry. Use this templated overload when your
1068e240498dfd4355849bcec943e97799f7f75d93dJordy Rose  /// checker does not require any custom initialization.
10708b86531ade68727c56918f162816075b87c864aJordy Rose  template <class T>
10808b86531ade68727c56918f162816075b87c864aJordy Rose  void addChecker(StringRef fullName, StringRef desc) {
10963d7ed8470e528da56ac4b2deae6a31ec3bd44fcDylan Noblesmith    // Avoid MSVC's Compiler Error C2276:
11063d7ed8470e528da56ac4b2deae6a31ec3bd44fcDylan Noblesmith    // http://msdn.microsoft.com/en-us/library/850cstw1(v=VS.80).aspx
11163d7ed8470e528da56ac4b2deae6a31ec3bd44fcDylan Noblesmith    addChecker(&CheckerRegistry::initializeManager<T>, fullName, desc);
11208b86531ade68727c56918f162816075b87c864aJordy Rose  }
11308b86531ade68727c56918f162816075b87c864aJordy Rose
1148e240498dfd4355849bcec943e97799f7f75d93dJordy Rose  /// Initializes a CheckerManager by calling the initialization functions for
1158e240498dfd4355849bcec943e97799f7f75d93dJordy Rose  /// all checkers specified by the given CheckerOptInfo list. The order of this
1168e240498dfd4355849bcec943e97799f7f75d93dJordy Rose  /// list is significant; later options can be used to reverse earlier ones.
1178e240498dfd4355849bcec943e97799f7f75d93dJordy Rose  /// This can be used to exclude certain checkers in an included package.
11808b86531ade68727c56918f162816075b87c864aJordy Rose  void initializeManager(CheckerManager &mgr,
11908b86531ade68727c56918f162816075b87c864aJordy Rose                         SmallVectorImpl<CheckerOptInfo> &opts) const;
1208e240498dfd4355849bcec943e97799f7f75d93dJordy Rose
1218e240498dfd4355849bcec943e97799f7f75d93dJordy Rose  /// Prints the name and description of all checkers in this registry.
1228e240498dfd4355849bcec943e97799f7f75d93dJordy Rose  /// This output is not intended to be machine-parseable.
12308b86531ade68727c56918f162816075b87c864aJordy Rose  void printHelp(raw_ostream &out, size_t maxNameChars = 30) const ;
12408b86531ade68727c56918f162816075b87c864aJordy Rose
12508b86531ade68727c56918f162816075b87c864aJordy Roseprivate:
12608b86531ade68727c56918f162816075b87c864aJordy Rose  mutable CheckerInfoList Checkers;
12708b86531ade68727c56918f162816075b87c864aJordy Rose  mutable llvm::StringMap<size_t> Packages;
12808b86531ade68727c56918f162816075b87c864aJordy Rose};
12908b86531ade68727c56918f162816075b87c864aJordy Rose
13008b86531ade68727c56918f162816075b87c864aJordy Rose} // end namespace ento
13108b86531ade68727c56918f162816075b87c864aJordy Rose} // end namespace clang
13208b86531ade68727c56918f162816075b87c864aJordy Rose
13308b86531ade68727c56918f162816075b87c864aJordy Rose#endif
134