contrib/llvm/tools/clang/include/clang/Tooling/Execution.h

   1 //===--- Execution.h - Executing clang frontend actions -*- 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 //  This file defines framework for executing clang frontend actions.
  11 //
  12 //  The framework can be extended to support different execution plans including
  13 //  standalone execution on the given TUs or parallel execution on all TUs in
  14 //  the codebase.
  15 //
  16 //  In order to enable multiprocessing execution, tool actions are expected to
  17 //  output result into the ToolResults provided by the executor. The
  18 //  `ToolResults` is an interface that abstracts how results are stored e.g.
  19 //  in-memory for standalone execution or on-disk for large-scale execution.
  20 //
  21 //  New executors can be registered as ToolExecutorPlugins via the
  22 //  `ToolExecutorPluginRegistry`. CLI tools can use
  23 //  `createExecutorFromCommandLineArgs` to create a specific registered executor
  24 //  according to the command-line arguments.
  25 //
  26 //===----------------------------------------------------------------------===//
  27
  28 #ifndef LLVM_CLANG_TOOLING_EXECUTION_H
  29 #define LLVM_CLANG_TOOLING_EXECUTION_H
  30
  31 #include "clang/Tooling/CommonOptionsParser.h"
  32 #include "clang/Tooling/Tooling.h"
  33 #include "llvm/Support/Error.h"
  34 #include "llvm/Support/Registry.h"
  35 #include "llvm/Support/StringSaver.h"
  36
  37 namespace clang {
  38 namespace tooling {
  39
  40 /// An abstraction for the result of a tool execution. For example, the
  41 /// underlying result can be in-memory or on-disk.
  42 ///
  43 /// Results should be string key-value pairs. For example, a refactoring tool
  44 /// can use source location as key and a replacement in YAML format as value.
  45 class ToolResults {
  46 public:
  47   virtual ~ToolResults() = default;
  48   virtual void addResult(StringRef Key, StringRef Value) = 0;
  49   virtual std::vector<std::pair<llvm::StringRef, llvm::StringRef>>
  50   AllKVResults() = 0;
  51   virtual void forEachResult(
  52       llvm::function_ref<void(StringRef Key, StringRef Value)> Callback) = 0;
  53 };
  54
  55 /// Stores the key-value results in memory. It maintains the lifetime of
  56 /// the result. Clang tools using this class are expected to generate a small
  57 /// set of different results, or a large set of duplicated results.
  58 class InMemoryToolResults : public ToolResults {
  59 public:
  60   InMemoryToolResults() : Strings(Arena) {}
  61   void addResult(StringRef Key, StringRef Value) override;
  62   std::vector<std::pair<llvm::StringRef, llvm::StringRef>>
  63   AllKVResults() override;
  64   void forEachResult(llvm::function_ref<void(StringRef Key, StringRef Value)>
  65                          Callback) override;
  66
  67 private:
  68   llvm::BumpPtrAllocator Arena;
  69   llvm::UniqueStringSaver Strings;
  70
  71   std::vector<std::pair<llvm::StringRef, llvm::StringRef>> KVResults;
  72 };
  73
  74 /// The context of an execution, including the information about
  75 /// compilation and results.
  76 class ExecutionContext {
  77 public:
  78   virtual ~ExecutionContext() {}
  79
  80   /// Initializes a context. This does not take ownership of `Results`.
  81   explicit ExecutionContext(ToolResults *Results) : Results(Results) {}
  82
  83   /// Adds a KV pair to the result container of this execution.
  84   void reportResult(StringRef Key, StringRef Value);
  85
  86   // Returns the source control system's revision number if applicable.
  87   // Otherwise returns an empty string.
  88   virtual std::string getRevision() { return ""; }
  89
  90   // Returns the corpus being analyzed, e.g. "llvm" for the LLVM codebase, if
  91   // applicable.
  92   virtual std::string getCorpus() { return ""; }
  93
  94   // Returns the currently processed compilation unit if available.
  95   virtual std::string getCurrentCompilationUnit() { return ""; }
  96
  97 private:
  98   ToolResults *Results;
  99 };
 100
 101 /// Interface for executing clang frontend actions.
 102 ///
 103 /// This can be extended to support running tool actions in different
 104 /// execution mode, e.g. on a specific set of TUs or many TUs in parallel.
 105 ///
 106 ///  New executors can be registered as ToolExecutorPlugins via the
 107 ///  `ToolExecutorPluginRegistry`. CLI tools can use
 108 ///  `createExecutorFromCommandLineArgs` to create a specific registered
 109 ///  executor according to the command-line arguments.
 110 class ToolExecutor {
 111 public:
 112   virtual ~ToolExecutor() {}
 113
 114   /// Returns the name of a specific executor.
 115   virtual StringRef getExecutorName() const = 0;
 116
 117   /// Executes each action with a corresponding arguments adjuster.
 118   virtual llvm::Error
 119   execute(llvm::ArrayRef<
 120           std::pair<std::unique_ptr<FrontendActionFactory>, ArgumentsAdjuster>>
 121               Actions) = 0;
 122
 123   /// Convenient functions for the above `execute`.
 124   llvm::Error execute(std::unique_ptr<FrontendActionFactory> Action);
 125   /// Executes an action with an argument adjuster.
 126   llvm::Error execute(std::unique_ptr<FrontendActionFactory> Action,
 127                       ArgumentsAdjuster Adjuster);
 128
 129   /// Returns a reference to the execution context.
 130   ///
 131   /// This should be passed to tool callbacks, and tool callbacks should report
 132   /// results via the returned context.
 133   virtual ExecutionContext *getExecutionContext() = 0;
 134
 135   /// Returns a reference to the result container.
 136   ///
 137   /// NOTE: This should only be used after the execution finishes. Tool
 138   /// callbacks should report results via `ExecutionContext` instead.
 139   virtual ToolResults *getToolResults() = 0;
 140
 141   /// Map a virtual file to be used while running the tool.
 142   ///
 143   /// \param FilePath The path at which the content will be mapped.
 144   /// \param Content A buffer of the file's content.
 145   virtual void mapVirtualFile(StringRef FilePath, StringRef Content) = 0;
 146 };
 147
 148 /// Interface for factories that create specific executors. This is also
 149 /// used as a plugin to be registered into ToolExecutorPluginRegistry.
 150 class ToolExecutorPlugin {
 151 public:
 152   virtual ~ToolExecutorPlugin() {}
 153
 154   /// Create an `ToolExecutor`.
 155   ///
 156   /// `OptionsParser` can be consumed (e.g. moved) if the creation succeeds.
 157   virtual llvm::Expected<std::unique_ptr<ToolExecutor>>
 158   create(CommonOptionsParser &OptionsParser) = 0;
 159 };
 160
 161 /// This creates a ToolExecutor that is in the global registry based on
 162 /// commandline arguments.
 163 ///
 164 /// This picks the right executor based on the `--executor` option. This parses
 165 /// the commandline arguments with `CommonOptionsParser`, so caller does not
 166 /// need to parse again.
 167 ///
 168 /// By default, this creates a `StandaloneToolExecutor` ("standalone") if
 169 /// `--executor` is not provided.
 170 llvm::Expected<std::unique_ptr<ToolExecutor>>
 171 createExecutorFromCommandLineArgs(int &argc, const char **argv,
 172                                   llvm::cl::OptionCategory &Category,
 173                                   const char *Overview = nullptr);
 174
 175 namespace internal {
 176 llvm::Expected<std::unique_ptr<ToolExecutor>>
 177 createExecutorFromCommandLineArgsImpl(int &argc, const char **argv,
 178                                       llvm::cl::OptionCategory &Category,
 179                                       const char *Overview = nullptr);
 180 } // end namespace internal
 181
 182 } // end namespace tooling
 183 } // end namespace clang
 184
 185 #endif // LLVM_CLANG_TOOLING_EXECUTION_H