add release notes, docs mention, and test example

clang-tools-extra/docs/ReleaseNotes.rst

 --------------------------
 
 - Added support for globbing in `NOLINT*` expressions, to simplify suppressing
   multiple warnings in the same line.
 
 - Added support for `NOLINTBEGIN` ... `NOLINTEND` comments to suppress
   Clang-Tidy warnings over multiple lines.
 
+- Added support for external plugin checks with `-load`.
+
 New checks
 ^^^^^^^^^^
 
 - New :doc:`abseil-cleanup-ctad
   <clang-tidy/checks/abseil-cleanup-ctad>` check.
 
   Suggests switching the initialization pattern of ``absl::Cleanup``
   instances from the factory function to class template argument

clang-tools-extra/docs/clang-tidy/Contributing.rst

 3. making replacements to a macro body/template definition may be fine for some
    macro expansions/template instantiations, but easily break some other
    expansions/instantiations.
 
 .. _lit: https://llvm.org/docs/CommandGuide/lit.html
 .. _FileCheck: https://llvm.org/docs/CommandGuide/FileCheck.html
 .. _test/clang-tidy/google-readability-casting.cpp: https://reviews.llvm.org/diffusion/L/browse/clang-tools-extra/trunk/test/clang-tidy/google-readability-casting.cpp
 
+Out-of-tree check plugins
+-------------------------
+
+If you want to develop this out-of-tree, the steps above are the largely same.
+External to the clang-tidy build system, put all of the new code into a single
+shared library. Build and link it against llvm, while allowing some symbols to
+be undefined during linking, almost exactly as you would define a clang plugin.
+
+Then we can run it by passing `-load` to `clang-tidy`, in addition to the name
+of our new checks.
+
+.. code-block:: console
+
+  $ clang-tidy --checks=-*,my-explicit-constructor -list-checks -load myplugin.so
+
 
 Running clang-tidy on LLVM
 --------------------------
 
 To test a check it's best to try it out on a larger code base. LLVM and Clang
 are the natural targets as you already have the source code around. The most
 convenient way to run :program:`clang-tidy` is with a compile command database;
 CMake can automatically generate one, for a description of how to enable it see

clang-tools-extra/docs/clang-tidy/index.rst

--line-filter=<string>         -
                                      JSON array of objects:
                                        [
                                          {"name":"file1.cpp","lines":[[1,3],[5,7]]},
                                          {"name":"file2.h"}
                                        ]
     --list-checks                  -
                                      List all enabled checks and exit. Use with
                                      -checks=* to list all available checks.
+    -load=<plugin>                 -
+                                     Load the dynamic object ``plugin``. This
+                                     object should register new static analyzer or clang-tidy passes. Once loaded, the object
+                                     will add new command line options to run
+                                     various analyses. To see the new complete
+                                     list of passes, use the
+                                     :option:`--list-checks` and
+                                     :option:`-load` options together.
     -p=<string>                    - Build path
     --quiet                        -
                                      Run clang-tidy in quiet mode. This suppresses
                                      printing statistics about ignored warnings and
                                      warnings treated as errors if the respective
                                      options are specified.
     --store-check-profile=<prefix> -
                                      By default reports are printed in tabulated

clang-tools-extra/test/CMakeLists.txt

 else ()
   set(LLVM_BUILD_MODE "%(build_mode)s")
 endif ()
 
 string(REPLACE ${CMAKE_CFG_INTDIR} ${LLVM_BUILD_MODE} CLANG_TOOLS_DIR ${LLVM_RUNTIME_OUTPUT_INTDIR})
 
 llvm_canonicalize_cmake_booleans(
   CLANG_TIDY_ENABLE_STATIC_ANALYZER
+  LLVM_ENABLE_PLUGINS
   )
 
 configure_lit_site_cfg(
   ${CMAKE_CURRENT_SOURCE_DIR}/lit.site.cfg.py.in
   ${CMAKE_CURRENT_BINARY_DIR}/lit.site.cfg.py
   MAIN_CONFIG
   ${CMAKE_CURRENT_SOURCE_DIR}/lit.cfg.py
   )
add_lit_testsuite(check-clang-tools "Running the Clang extra tools' regression tests"
   ARGS ${CLANG_TOOLS_TEST_EXTRA_ARGS}
   )
 
 set_target_properties(check-clang-tools PROPERTIES FOLDER "Clang extra tools' tests")
 
 add_lit_testsuites(CLANG-EXTRA ${CMAKE_CURRENT_SOURCE_DIR}
   DEPENDS ${CLANG_TOOLS_TEST_DEPS}
   )
+
+llvm_add_library(
+    CTTestTidyModule
+    MODULE clang-tidy/CTTestTidyModule.cpp
+    PLUGIN_TOOL clang-tidy
+    DEPENDS clang-tidy-headers)
+
+target_include_directories(CTTestTidyModule PUBLIC BEFORE "${CLANG_TOOLS_SOURCE_DIR}")
+
+if(LLVM_ENABLE_PLUGINS AND (WIN32 OR CYGWIN))
+  set(LLVM_LINK_COMPONENTS
+    Support
+  )
+endif()

clang-tools-extra/test/clang-tidy/CTTestTidyModule.cpp

+// REQUIRES: plugins
+// RUN: clang-tidy -checks='-*,mytest' --list-checks -load %llvmshlibdir/CTTestTidyModule%pluginext | FileCheck %s
+// CHECK: Enabled checks:
+// CHECK-NEXT:    mytest
+
+#include "clang-tidy/ClangTidy.h"
+#include "clang-tidy/ClangTidyCheck.h"
+#include "clang-tidy/ClangTidyModule.h"
+#include "clang-tidy/ClangTidyModuleRegistry.h"
+#include "clang/AST/ASTContext.h"
+#include "clang/ASTMatchers/ASTMatchFinder.h"
+
+using namespace clang;
+using namespace clang::tidy;
+using namespace clang::ast_matchers;
+
+namespace {
+class MyTestCheck : public ClangTidyCheck {
+
+public:
+  MyTestCheck(StringRef Name, ClangTidyContext *Context)
+      : ClangTidyCheck(Name, Context) {}
+
+  //void registerMatchers(ast_matchers::MatchFinder *Finder) override;
+  //void check(const ast_matchers::MatchFinder::MatchResult &Result) override;
+
+private:
+};
+
+class CTTestModule : public ClangTidyModule {
+public:
+  void addCheckFactories(ClangTidyCheckFactories &CheckFactories) override {
+    CheckFactories.registerCheck<MyTestCheck>("mytest");
+  }
+};
+} // namespace
+
+namespace clang {
+namespace tidy {
+
+// Register the CTTestTidyModule using this statically initialized variable.
+static ClangTidyModuleRegistry::Add<::CTTestModule>
+    X("mytest-module", "Adds my checks.");
+
+// This anchor is used to force the linker to link in the generated object file
+// and thus register the CTTestModule.
+volatile int CTTestModuleAnchorSource = 0;
+
+} // namespace tidy
+} // namespace clang

clang-tools-extra/test/lit.cfg.py

config.substitutions.append(
     ('%run_clang_tidy',
      '%s %s' % (python_exec, run_clang_tidy)) )
 
 clangd_benchmarks_dir = os.path.join(os.path.dirname(config.clang_tools_dir),
                                      "tools", "clang", "tools", "extra",
                                      "clangd", "benchmarks")
 config.substitutions.append(('%clangd-benchmark-dir',
                              '%s' % (clangd_benchmarks_dir)))
+config.substitutions.append(('%llvmshlibdir', config.clang_libs_dir))
+config.substitutions.append(('%pluginext', config.llvm_plugin_ext))

clang-tools-extra/test/lit.site.cfg.py.in

 @LIT_SITE_CFG_IN_HEADER@
 
 import sys
 
 config.llvm_tools_dir = "@LLVM_TOOLS_DIR@"
 config.llvm_libs_dir = "@LLVM_LIBS_DIR@"
+config.llvm_plugin_ext = "@LLVM_PLUGIN_EXT@"
 config.lit_tools_dir = "@LLVM_LIT_TOOLS_DIR@"
 config.clang_tools_binary_dir = "@CLANG_TOOLS_BINARY_DIR@"
 config.clang_tools_dir = "@CLANG_TOOLS_DIR@"
 config.clang_libs_dir = "@SHLIBDIR@"
 config.python_executable = "@Python3_EXECUTABLE@"
 config.target_triple = "@TARGET_TRIPLE@"
 config.clang_tidy_staticanalyzer = @CLANG_TIDY_ENABLE_STATIC_ANALYZER@
+config.has_plugins = @LLVM_ENABLE_PLUGINS@
 
 # Support substitution of the tools and libs dirs with user parameters. This is
 # used when we can't determine the tool dir at configuration time.
 try:
     config.clang_tools_dir = config.clang_tools_dir % lit_config.params
     config.llvm_tools_dir = config.llvm_tools_dir % lit_config.params
     config.llvm_libs_dir = config.llvm_libs_dir % lit_config.params
 except KeyError: