1 //===--- Execution.h - Executing clang frontend actions -*- C++ ---------*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 // This file defines framework for executing clang frontend actions.
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
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.
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.
26 //===----------------------------------------------------------------------===//
28 #ifndef LLVM_CLANG_TOOLING_EXECUTION_H
29 #define LLVM_CLANG_TOOLING_EXECUTION_H
31 #include "clang/Tooling/CommonOptionsParser.h"
32 #include "clang/Tooling/Tooling.h"
33 #include "llvm/Support/Error.h"
34 #include "llvm/Support/Registry.h"
39 /// \brief An abstraction for the result of a tool execution. For example, the
40 /// underlying result can be in-memory or on-disk.
42 /// Results should be string key-value pairs. For example, a refactoring tool
43 /// can use source location as key and a replacement in YAML format as value.
46 virtual ~ToolResults() = default;
47 virtual void addResult(StringRef Key, StringRef Value) = 0;
48 virtual std::vector<std::pair<std::string, std::string>> AllKVResults() = 0;
49 virtual void forEachResult(
50 llvm::function_ref<void(StringRef Key, StringRef Value)> Callback) = 0;
53 class InMemoryToolResults : public ToolResults {
55 void addResult(StringRef Key, StringRef Value) override;
56 std::vector<std::pair<std::string, std::string>> AllKVResults() override;
57 void forEachResult(llvm::function_ref<void(StringRef Key, StringRef Value)>
61 std::vector<std::pair<std::string, std::string>> KVResults;
64 /// \brief The context of an execution, including the information about
65 /// compilation and results.
66 class ExecutionContext {
68 virtual ~ExecutionContext() {}
70 /// \brief Initializes a context. This does not take ownership of `Results`.
71 explicit ExecutionContext(ToolResults *Results) : Results(Results) {}
73 /// \brief Adds a KV pair to the result container of this execution.
74 void reportResult(StringRef Key, StringRef Value);
76 // Returns the source control system's revision number if applicable.
77 // Otherwise returns an empty string.
78 virtual std::string getRevision() { return ""; }
80 // Returns the corpus being analyzed, e.g. "llvm" for the LLVM codebase, if
82 virtual std::string getCorpus() { return ""; }
84 // Returns the currently processed compilation unit if available.
85 virtual std::string getCurrentCompilationUnit() { return ""; }
91 /// \brief Interface for executing clang frontend actions.
93 /// This can be extended to support running tool actions in different
94 /// execution mode, e.g. on a specific set of TUs or many TUs in parallel.
96 /// New executors can be registered as ToolExecutorPlugins via the
97 /// `ToolExecutorPluginRegistry`. CLI tools can use
98 /// `createExecutorFromCommandLineArgs` to create a specific registered
99 /// executor according to the command-line arguments.
102 virtual ~ToolExecutor() {}
104 /// \brief Returns the name of a specific executor.
105 virtual StringRef getExecutorName() const = 0;
107 /// \brief Executes each action with a corresponding arguments adjuster.
109 execute(llvm::ArrayRef<
110 std::pair<std::unique_ptr<FrontendActionFactory>, ArgumentsAdjuster>>
113 /// \brief Convenient functions for the above `execute`.
114 llvm::Error execute(std::unique_ptr<FrontendActionFactory> Action);
115 /// Executes an action with an argument adjuster.
116 llvm::Error execute(std::unique_ptr<FrontendActionFactory> Action,
117 ArgumentsAdjuster Adjuster);
119 /// \brief Returns a reference to the execution context.
121 /// This should be passed to tool callbacks, and tool callbacks should report
122 /// results via the returned context.
123 virtual ExecutionContext *getExecutionContext() = 0;
125 /// \brief Returns a reference to the result container.
127 /// NOTE: This should only be used after the execution finishes. Tool
128 /// callbacks should report results via `ExecutionContext` instead.
129 virtual ToolResults *getToolResults() = 0;
131 /// \brief Map a virtual file to be used while running the tool.
133 /// \param FilePath The path at which the content will be mapped.
134 /// \param Content A buffer of the file's content.
135 virtual void mapVirtualFile(StringRef FilePath, StringRef Content) = 0;
138 /// \brief Interface for factories that create specific executors. This is also
139 /// used as a plugin to be registered into ToolExecutorPluginRegistry.
140 class ToolExecutorPlugin {
142 virtual ~ToolExecutorPlugin() {}
144 /// \brief Create an `ToolExecutor`.
146 /// `OptionsParser` can be consumed (e.g. moved) if the creation succeeds.
147 virtual llvm::Expected<std::unique_ptr<ToolExecutor>>
148 create(CommonOptionsParser &OptionsParser) = 0;
151 /// \brief This creates a ToolExecutor that is in the global registry based on
152 /// commandline arguments.
154 /// This picks the right executor based on the `--executor` option. This parses
155 /// the commandline arguments with `CommonOptionsParser`, so caller does not
156 /// need to parse again.
158 /// By default, this creates a `StandaloneToolExecutor` ("standalone") if
159 /// `--executor` is not provided.
160 llvm::Expected<std::unique_ptr<ToolExecutor>>
161 createExecutorFromCommandLineArgs(int &argc, const char **argv,
162 llvm::cl::OptionCategory &Category,
163 const char *Overview = nullptr);
166 llvm::Expected<std::unique_ptr<ToolExecutor>>
167 createExecutorFromCommandLineArgsImpl(int &argc, const char **argv,
168 llvm::cl::OptionCategory &Category,
169 const char *Overview = nullptr);
170 } // end namespace internal
172 } // end namespace tooling
173 } // end namespace clang
175 #endif // LLVM_CLANG_TOOLING_EXECUTION_H