[clang-tidy] Add a flag to enable debug checkers

[lebedev.ri]

Summary

After D46159 was created by @pfultz2, and i initially thought it was already possible, i had the need to view the call graph.
I have almost wrote the clang-tidy check for that, but then i remembered of clang-analyzer-debug.ViewCallGraph.
Naturally, it did not work out-of-the-box, thus this patch.

[alexfh]

I don't think debug CSA checkers belong to clang-tidy. If one needs to dump CFG, they are probably doing quite involved stuff already, so going a step further and running clang -cc1 -analyze would not be difficult. The motivation for exposing alpha checkers (letting users test them and provide feedback) doesn't work for debug checkers.

[lebedev.ri]

In D46188#1091221, @alexfh wrote:

I don't think debug CSA checkers belong to clang-tidy. If one needs to dump CFG, they are probably doing quite involved stuff already, so going a step further and running clang -cc1 -analyze would not be difficult. The motivation for exposing alpha checkers (letting users test them and provide feedback) doesn't work for debug checkers.

There is word play here.
They are debug CSA checkers. But not all of them are debugging the CSA. Many of them are just utility checkers that could be just as easily a clang-tidy debug/utility checkers:

$ scan-build -h | grep "   debug."
   debug.AnalysisOrder             Print callbacks that are called during analysis in order       <- for CSA debugging
   debug.ConfigDumper              Dump config table                                              <- for CSA debugging
   debug.DumpCFG                   Display Control-Flow Graphs                                    <- 
   debug.DumpCallGraph             Display Call Graph                                             <- 
   debug.DumpCalls                 Print calls as they are traversed by the engine                <- for CSA debugging
   debug.DumpDominators            Print the dominance tree for a given CFG                       <- 
   debug.DumpLiveVars              Print results of live variable analysis                        <- 
   debug.DumpTraversal             Print branch conditions as they are traversed by the engine    <- for CSA debugging
   debug.ExprInspection            Check the analyzer's understanding of expressions              <- for CSA debugging
   debug.Stats                     Emit warnings with analyzer statistics                         <- for CSA debugging
   debug.TaintTest                 Mark tainted symbols as such.                                  <- for CSA debugging
   debug.ViewCFG                   View Control-Flow Graphs using GraphViz                        <- 
   debug.ViewCallGraph             View Call Graph using GraphViz                                 <- 
   debug.ViewExplodedGraph         View Exploded Graphs using GraphViz                            <- 

(CC people from D46187: @dcoughlin @george.karpenkov @NoQ)

[alexfh]

In D46188#1091237, @lebedev.ri wrote:

In D46188#1091221, @alexfh wrote:

I don't think debug CSA checkers belong to clang-tidy. If one needs to dump CFG, they are probably doing quite involved stuff already, so going a step further and running clang -cc1 -analyze would not be difficult. The motivation for exposing alpha checkers (letting users test them and provide feedback) doesn't work for debug checkers.

There is word play here.
They are debug CSA checkers. But not all of them are debugging the CSA. Many of them are just utility checkers that could be just as easily a clang-tidy debug/utility checkers:

I roughly understand what debug CSA checkers are. However, I don't see much value in exposing them in clang-tidy. While it may be valuable to look at the CFG dump when developing a clang-tidy check, for example, but this can be done using clang

$ clang -cc1 -help | grep cfg
 -cfg-add-implicit-dtors Add C++ implicit destructors to CFGs for all analyses
 -cfg-add-initializers   Add C++ initializers to CFGs for all analyses
 -cfg-dump               Display Control-Flow Graphs
 -cfg-view               View Control-Flow Graphs using GraphViz
 -unoptimized-cfg        Generate unoptimized CFGs for all analyses

All CSA debug checkers can also be invoked using clang -cc1 --analyze. The only thing clang-tidy could bring is a possibility to more easily run all these tools on a file from a project that is using a compilation database. However, that doesn't seem like a very valuable functionality, because 1. working on small artificial test cases (or test cases reduced from real code) is easier, 2. in a rare case when a file from a real project needs to be analyzed, it's possible to get compilation arguments and feed them to clang (e.g. using clang-tidy -extra-arg=-v file.cpp).

[lebedev.ri]

https://reviews.llvm.org/D46187#1098571
Sad, but ok.

clang-tidy/ClangTidy.cpp

if (!OptName.startswith(AnalyzerPrefix))
       continue;
     AnalyzerOptions->Config[OptName.substr(AnalyzerPrefix.size())] = Opt.second;
   }
 }
 
 typedef std::vector<std::pair<std::string, bool>> CheckersList;
 
 static CheckersList getCheckersControlList(ClangTidyContext &Context,
-                                           bool IncludeExperimental) {
+                                           bool IncludeExperimental,
+                                           bool IncludeDebug) {
   CheckersList List;
 
   const auto &RegisteredCheckers =
-      AnalyzerOptions::getRegisteredCheckers(IncludeExperimental);
+      AnalyzerOptions::getRegisteredCheckers(IncludeExperimental, IncludeDebug);
   bool AnalyzerChecksEnabled = false;
   for (StringRef CheckName : RegisteredCheckers) {
     std::string ClangTidyCheckName((AnalyzerCheckNamePrefix + CheckName).str());
     AnalyzerChecksEnabled |= Context.isCheckEnabled(ClangTidyCheckName);
   }
 
   if (!AnalyzerChecksEnabled)
     return List;
ClangTidyASTConsumerFactory::CreateASTConsumer(
 
   AnalyzerOptionsRef AnalyzerOptions = Compiler.getAnalyzerOpts();
   // FIXME: Remove this option once clang's cfg-temporary-dtors option defaults
   // to true.
   AnalyzerOptions->Config["cfg-temporary-dtors"] =
       Context.getOptions().AnalyzeTemporaryDtors ? "true" : "false";
 
   AnalyzerOptions->CheckersControlList =
-      getCheckersControlList(Context, *Context.getOptions().EnableAlphaChecks);
+      getCheckersControlList(Context, *Context.getOptions().EnableAlphaChecks,
+                             *Context.getOptions().EnableDebugChecks);
   if (!AnalyzerOptions->CheckersControlList.empty()) {
     setStaticAnalyzerCheckerOpts(Context.getOptions(), AnalyzerOptions);
     AnalyzerOptions->AnalysisStoreOpt = RegionStoreModel;
     AnalyzerOptions->AnalysisDiagOpt = PD_NONE;
     AnalyzerOptions->AnalyzeNestedBlocks = true;
     AnalyzerOptions->eagerlyAssumeBinOpBifurcation = true;
     std::unique_ptr<ento::AnalysisASTConsumer> AnalysisConsumer =
         ento::CreateAnalysisConsumer(Compiler);
     AnalysisConsumer->AddDiagnosticConsumer(
         new AnalyzerDiagnosticConsumer(Context));
     Consumers.push_back(std::move(AnalysisConsumer));
   }
   return llvm::make_unique<ClangTidyASTConsumer>(
       std::move(Consumers), std::move(Finder), std::move(Checks));
 }
 
 std::vector<std::string> ClangTidyASTConsumerFactory::getCheckNames() {
   std::vector<std::string> CheckNames;
   for (const auto &CheckFactory : *CheckFactories) {
     if (Context.isCheckEnabled(CheckFactory.first))
       CheckNames.push_back(CheckFactory.first);
   }
 
   for (const auto &AnalyzerCheck :
-       getCheckersControlList(Context, *Context.getOptions().EnableAlphaChecks))
+       getCheckersControlList(Context, *Context.getOptions().EnableAlphaChecks,
+                              *Context.getOptions().EnableDebugChecks))
     CheckNames.push_back(AnalyzerCheckNamePrefix + AnalyzerCheck.first);
 
   std::sort(CheckNames.begin(), CheckNames.end());
   return CheckNames;
 }
 
 ClangTidyOptions::OptionMap ClangTidyASTConsumerFactory::getCheckOptions() {
   ClangTidyOptions::OptionMap Options;

clang-tidy/ClangTidyOptions.h

struct ClangTidyOptions {
   llvm::Optional<bool> SystemHeaders;
 
   /// \brief Turns on temporary destructor-based analysis.
   llvm::Optional<bool> AnalyzeTemporaryDtors;
 
   /// \brief Turns on experimental alpha checkers from the static analyzer.
   llvm::Optional<bool> EnableAlphaChecks;
 
+  /// \brief Turns on debug checkers from the static analyzer.
+  llvm::Optional<bool> EnableDebugChecks;
+
   /// \brief Format code around applied fixes with clang-format using this
   /// style.
   ///
   /// Can be one of:
   ///   * 'none' - don't format code around applied fixes;
   ///   * 'llvm', 'google', 'mozilla' or other predefined clang-format style
   ///     names;
   ///   * 'file' - use the .clang-format file in the closest parent directory of

clang-tidy/ClangTidyOptions.cpp

template <> struct MappingTraits<ClangTidyOptions> {
   static void mapping(IO &IO, ClangTidyOptions &Options) {
     MappingNormalization<NOptionMap, ClangTidyOptions::OptionMap> NOpts(
         IO, Options.CheckOptions);
     IO.mapOptional("Checks", Options.Checks);
     IO.mapOptional("WarningsAsErrors", Options.WarningsAsErrors);
     IO.mapOptional("HeaderFilterRegex", Options.HeaderFilterRegex);
     IO.mapOptional("AnalyzeTemporaryDtors", Options.AnalyzeTemporaryDtors);
     IO.mapOptional("EnableAlphaChecks", Options.EnableAlphaChecks);
+    IO.mapOptional("EnableDebugChecks", Options.EnableDebugChecks);
     IO.mapOptional("FormatStyle", Options.FormatStyle);
     IO.mapOptional("User", Options.User);
     IO.mapOptional("CheckOptions", NOpts->Options);
     IO.mapOptional("ExtraArgs", Options.ExtraArgs);
     IO.mapOptional("ExtraArgsBefore", Options.ExtraArgsBefore);
   }
 };
 
 } // namespace yaml
 } // namespace llvm
 
 namespace clang {
 namespace tidy {
 
 ClangTidyOptions ClangTidyOptions::getDefaults() {
   ClangTidyOptions Options;
   Options.Checks = "";
   Options.WarningsAsErrors = "";
   Options.HeaderFilterRegex = "";
   Options.SystemHeaders = false;
   Options.AnalyzeTemporaryDtors = false;
   Options.EnableAlphaChecks = false;
+  Options.EnableDebugChecks = false;
   Options.FormatStyle = "none";
   Options.User = llvm::None;
   for (ClangTidyModuleRegistry::iterator I = ClangTidyModuleRegistry::begin(),
                                          E = ClangTidyModuleRegistry::end();
        I != E; ++I)
     Options = Options.mergeWith(I->instantiate()->getModuleOptions());
   return Options;
 }
ClangTidyOptions::mergeWith(const ClangTidyOptions &Other) const {
   ClangTidyOptions Result = *this;
 
   mergeCommaSeparatedLists(Result.Checks, Other.Checks);
   mergeCommaSeparatedLists(Result.WarningsAsErrors, Other.WarningsAsErrors);
   overrideValue(Result.HeaderFilterRegex, Other.HeaderFilterRegex);
   overrideValue(Result.SystemHeaders, Other.SystemHeaders);
   overrideValue(Result.AnalyzeTemporaryDtors, Other.AnalyzeTemporaryDtors);
   overrideValue(Result.EnableAlphaChecks, Other.EnableAlphaChecks);
+  overrideValue(Result.EnableDebugChecks, Other.EnableDebugChecks);
   overrideValue(Result.FormatStyle, Other.FormatStyle);
   overrideValue(Result.User, Other.User);
   mergeVectors(Result.ExtraArgs, Other.ExtraArgs);
   mergeVectors(Result.ExtraArgsBefore, Other.ExtraArgsBefore);
 
   for (const auto &KeyValue : Other.CheckOptions)
     Result.CheckOptions[KeyValue.first] = KeyValue.second;
 

clang-tidy/tool/ClangTidyMain.cpp

)"),
                                            cl::cat(ClangTidyCategory));
 
 /// This option Enables alpha checkers from the static analyzer, that are
 /// experimental. This option is set to false and not visible in help, because
 /// it is highly not recommended for users.
 static cl::opt<bool> EnableAlphaChecks("enable-alpha-checks", cl::init(false),
                                        cl::Hidden, cl::cat(ClangTidyCategory));
 
+/// This option Enables debug checkers from the static analyzer.
+/// This option is set to false and not visible in help, because they are not
+/// for general usage.
+static cl::opt<bool> EnableDebugChecks("enable-debug-checks", cl::init(false),
+                                       cl::Hidden, cl::cat(ClangTidyCategory));
+
 static cl::opt<std::string> ExportFixes("export-fixes", cl::desc(R"(
 YAML file to store suggested fixes in. The
 stored fixes can be applied to the input source
 code with clang-apply-replacements.
 )"),
                                         cl::value_desc("filename"),
                                         cl::cat(ClangTidyCategory));
 
static std::unique_ptr<ClangTidyOptionsProvider> createOptionsProvider(
 
   ClangTidyOptions DefaultOptions;
   DefaultOptions.Checks = DefaultChecks;
   DefaultOptions.WarningsAsErrors = "";
   DefaultOptions.HeaderFilterRegex = HeaderFilter;
   DefaultOptions.SystemHeaders = SystemHeaders;
   DefaultOptions.AnalyzeTemporaryDtors = AnalyzeTemporaryDtors;
   DefaultOptions.EnableAlphaChecks = EnableAlphaChecks;
+  DefaultOptions.EnableDebugChecks = EnableDebugChecks;
   DefaultOptions.FormatStyle = FormatStyle;
   DefaultOptions.User = llvm::sys::Process::GetEnv("USER");
   // USERNAME is used on Windows.
   if (!DefaultOptions.User)
     DefaultOptions.User = llvm::sys::Process::GetEnv("USERNAME");
 
   ClangTidyOptions OverrideOptions;
   if (Checks.getNumOccurrences() > 0)

docs/clang-tidy/index.rst

.. code-block:: console
 
   clang-tidy options:
 
     -analyze-temporary-dtors     -
                                    Enable temporary destructor-aware analysis in
                                    clang-analyzer- checks.
                                    This option overrides the value read from a
                                    .clang-tidy file.
+    -enable-alpha-checks         - This option is not visible in help.
+                                   It allows to enable clang analyzer Alpha checks.
+    -enable-debug-checks         - This option is not visible in help.
+                                   It allows to enable clang analyzer Debug checks.
     -checks=<string>             -
                                    Comma-separated list of globs with optional '-'
                                    prefix. Globs are processed in order of
                                    appearance in the list. Globs without '-'
                                    prefix add checks with matching names to the
                                    set, globs with the '-' prefix remove checks
                                    with matching names from the set of enabled
                                    checks. This option's value is appended to the

test/clang-tidy/enable-debug-checks.cpp

+// Check if '-enable-debug-checks' is visible for users
+// RUN: clang-tidy -help | not grep 'enable-debug-checks'
+
+// Check if '-enable-debug-checks' enables debug checks.
+// RUN: clang-tidy -checks=* -list-checks | not grep 'clang-analyzer-debug'
+// RUN: clang-tidy -checks=* -list-checks -enable-debug-checks | grep 'clang-analyzer-debug'