Coverage Report

Created: 2020-12-01 06:44

/Users/buildslave/jenkins/workspace/coverage/llvm-project/clang/include/clang/Tooling/Execution.h
Line
Count
Source
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
30
#include "clang/Tooling/CommonOptionsParser.h"
31
#include "clang/Tooling/Tooling.h"
32
#include "llvm/Support/Error.h"
33
#include "llvm/Support/Registry.h"
34
#include "llvm/Support/StringSaver.h"
35
36
namespace clang {
37
namespace tooling {
38
39
extern 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.
46
class ToolResults {
47
public:
48
9
  virtual ~ToolResults() = default;
49
  virtual void addResult(StringRef Key, StringRef Value) = 0;
50
  virtual std::vector<std::pair<llvm::StringRef, llvm::StringRef>>
51
  AllKVResults() = 0;
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.
59
class InMemoryToolResults : public ToolResults {
60
public:
61
7
  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
68
private:
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.
77
class ExecutionContext {
78
public:
79
7
  virtual ~ExecutionContext() {}
80
81
  /// Initializes a context. This does not take ownership of `Results`.
82
7
  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
102
  virtual std::string getRevision() { return ""; }
90
91
  // Returns the corpus being analyzed, e.g. "llvm" for the LLVM codebase, if
92
  // applicable.
93
104
  virtual std::string getCorpus() { return ""; }
94
95
  // Returns the currently processed compilation unit if available.
96
101
  virtual std::string getCurrentCompilationUnit() { return ""; }
97
98
private:
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.
111
class ToolExecutor {
112
public:
113
8
  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
120
  execute(llvm::ArrayRef<
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.
134
  virtual ExecutionContext *getExecutionContext() = 0;
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.
140
  virtual ToolResults *getToolResults() = 0;
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.
151
class ToolExecutorPlugin {
152
public:
153
3
  virtual ~ToolExecutorPlugin() {}
154
155
  /// Create an `ToolExecutor`.
156
  ///
157
  /// `OptionsParser` can be consumed (e.g. moved) if the creation succeeds.
158
  virtual llvm::Expected<std::unique_ptr<ToolExecutor>>
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.
171
llvm::Expected<std::unique_ptr<ToolExecutor>>
172
createExecutorFromCommandLineArgs(int &argc, const char **argv,
173
                                  llvm::cl::OptionCategory &Category,
174
                                  const char *Overview = nullptr);
175
176
namespace internal {
177
llvm::Expected<std::unique_ptr<ToolExecutor>>
178
createExecutorFromCommandLineArgsImpl(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