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