clang 19.0.0git
FrontendAction.h
Go to the documentation of this file.
1//===-- FrontendAction.h - Generic Frontend Action Interface ----*- 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/// \file
10/// Defines the clang::FrontendAction interface and various convenience
11/// abstract classes (clang::ASTFrontendAction, clang::PluginASTAction,
12/// clang::PreprocessorFrontendAction, and clang::WrapperFrontendAction)
13/// derived from it.
14///
15//===----------------------------------------------------------------------===//
16
17#ifndef LLVM_CLANG_FRONTEND_FRONTENDACTION_H
18#define LLVM_CLANG_FRONTEND_FRONTENDACTION_H
19
21#include "clang/Basic/LLVM.h"
25#include "llvm/ADT/StringRef.h"
26#include "llvm/Support/Error.h"
27#include <memory>
28#include <string>
29#include <vector>
30
31namespace clang {
32class ASTMergeAction;
33class CompilerInstance;
34
35/// Abstract base class for actions which can be performed by the frontend.
37 FrontendInputFile CurrentInput;
38 std::unique_ptr<ASTUnit> CurrentASTUnit;
39 CompilerInstance *Instance;
40 friend class ASTMergeAction;
42
43private:
44 std::unique_ptr<ASTConsumer> CreateWrappedASTConsumer(CompilerInstance &CI,
45 StringRef InFile);
46
47protected:
48 /// @name Implementation Action Interface
49 /// @{
50
51 /// Prepare to execute the action on the given CompilerInstance.
52 ///
53 /// This is called before executing the action on any inputs, and can modify
54 /// the configuration as needed (including adjusting the input list).
55 virtual bool PrepareToExecuteAction(CompilerInstance &CI) { return true; }
56
57 /// Create the AST consumer object for this action, if supported.
58 ///
59 /// This routine is called as part of BeginSourceFile(), which will
60 /// fail if the AST consumer cannot be created. This will not be called if the
61 /// action has indicated that it only uses the preprocessor.
62 ///
63 /// \param CI - The current compiler instance, provided as a convenience, see
64 /// getCompilerInstance().
65 ///
66 /// \param InFile - The current input file, provided as a convenience, see
67 /// getCurrentFile().
68 ///
69 /// \return The new AST consumer, or null on failure.
70 virtual std::unique_ptr<ASTConsumer> CreateASTConsumer(CompilerInstance &CI,
71 StringRef InFile) = 0;
72
73 /// Callback before starting processing a single input, giving the
74 /// opportunity to modify the CompilerInvocation or do some other action
75 /// before BeginSourceFileAction is called.
76 ///
77 /// \return True on success; on failure BeginSourceFileAction(),
78 /// ExecuteAction() and EndSourceFileAction() will not be called.
79 virtual bool BeginInvocation(CompilerInstance &CI) { return true; }
80
81 /// Callback at the start of processing a single input.
82 ///
83 /// \return True on success; on failure ExecutionAction() and
84 /// EndSourceFileAction() will not be called.
86 return true;
87 }
88
89 /// Callback to run the program action, using the initialized
90 /// compiler instance.
91 ///
92 /// This is guaranteed to only be called between BeginSourceFileAction()
93 /// and EndSourceFileAction().
94 virtual void ExecuteAction() = 0;
95
96 /// Callback at the end of processing a single input.
97 ///
98 /// This is guaranteed to only be called following a successful call to
99 /// BeginSourceFileAction (and BeginSourceFile).
100 virtual void EndSourceFileAction() {}
101
102 /// Callback at the end of processing a single input, to determine
103 /// if the output files should be erased or not.
104 ///
105 /// By default it returns true if a compiler error occurred.
106 /// This is guaranteed to only be called following a successful call to
107 /// BeginSourceFileAction (and BeginSourceFile).
108 virtual bool shouldEraseOutputFiles();
109
110 /// @}
111
112public:
114 virtual ~FrontendAction();
115
116 /// @name Compiler Instance Access
117 /// @{
118
120 assert(Instance && "Compiler instance not registered!");
121 return *Instance;
122 }
123
125
126 /// @}
127 /// @name Current File Information
128 /// @{
129
130 bool isCurrentFileAST() const {
131 assert(!CurrentInput.isEmpty() && "No current file!");
132 return (bool)CurrentASTUnit;
133 }
134
136 return CurrentInput;
137 }
138
139 StringRef getCurrentFile() const {
140 assert(!CurrentInput.isEmpty() && "No current file!");
141 return CurrentInput.getFile();
142 }
143
144 StringRef getCurrentFileOrBufferName() const {
145 assert(!CurrentInput.isEmpty() && "No current file!");
146 return CurrentInput.isFile()
147 ? CurrentInput.getFile()
148 : CurrentInput.getBuffer().getBufferIdentifier();
149 }
150
152 assert(!CurrentInput.isEmpty() && "No current file!");
153 return CurrentInput.getKind();
154 }
155
157 assert(CurrentASTUnit && "No current AST unit!");
158 return *CurrentASTUnit;
159 }
160
161 Module *getCurrentModule() const;
162
163 std::unique_ptr<ASTUnit> takeCurrentASTUnit() {
164 return std::move(CurrentASTUnit);
165 }
166
167 void setCurrentInput(const FrontendInputFile &CurrentInput,
168 std::unique_ptr<ASTUnit> AST = nullptr);
169
170 /// @}
171 /// @name Supported Modes
172 /// @{
173
174 /// Is this action invoked on a model file?
175 ///
176 /// Model files are incomplete translation units that relies on type
177 /// information from another translation unit. Check ParseModelFileAction for
178 /// details.
179 virtual bool isModelParsingAction() const { return false; }
180
181 /// Does this action only use the preprocessor?
182 ///
183 /// If so no AST context will be created and this action will be invalid
184 /// with AST file inputs.
185 virtual bool usesPreprocessorOnly() const = 0;
186
187 /// For AST-based actions, the kind of translation unit we're handling.
189
190 /// Does this action support use with PCH?
191 virtual bool hasPCHSupport() const { return true; }
192
193 /// Does this action support use with AST files?
194 virtual bool hasASTFileSupport() const { return true; }
195
196 /// Does this action support use with IR files?
197 virtual bool hasIRSupport() const { return false; }
198
199 /// Does this action support use with code completion?
200 virtual bool hasCodeCompletionSupport() const { return false; }
201
202 /// @}
203 /// @name Public Action Interface
204 /// @{
205
206 /// Prepare the action to execute on the given compiler instance.
208 return PrepareToExecuteAction(CI);
209 }
210
211 /// Prepare the action for processing the input file \p Input.
212 ///
213 /// This is run after the options and frontend have been initialized,
214 /// but prior to executing any per-file processing.
215 ///
216 /// \param CI - The compiler instance this action is being run from. The
217 /// action may store and use this object up until the matching EndSourceFile
218 /// action.
219 ///
220 /// \param Input - The input filename and kind. Some input kinds are handled
221 /// specially, for example AST inputs, since the AST file itself contains
222 /// several objects which would normally be owned by the
223 /// CompilerInstance. When processing AST input files, these objects should
224 /// generally not be initialized in the CompilerInstance -- they will
225 /// automatically be shared with the AST file in between
226 /// BeginSourceFile() and EndSourceFile().
227 ///
228 /// \return True on success; on failure the compilation of this file should
229 /// be aborted and neither Execute() nor EndSourceFile() should be called.
230 bool BeginSourceFile(CompilerInstance &CI, const FrontendInputFile &Input);
231
232 /// Set the source manager's main input file, and run the action.
233 llvm::Error Execute();
234
235 /// Perform any per-file post processing, deallocate per-file
236 /// objects, and run statistics and output file cleanup code.
237 virtual void EndSourceFile();
238
239 /// @}
240};
241
242/// Abstract base class to use for AST consumer-based frontend actions.
244protected:
245 /// Implement the ExecuteAction interface by running Sema on
246 /// the already-initialized AST consumer.
247 ///
248 /// This will also take care of instantiating a code completion consumer if
249 /// the user requested it and the action supports it.
250 void ExecuteAction() override;
251
252public:
254 bool usesPreprocessorOnly() const override { return false; }
255};
256
258 virtual void anchor();
259public:
260 std::unique_ptr<ASTConsumer> CreateASTConsumer(CompilerInstance &CI,
261 StringRef InFile) override = 0;
262
263 /// Parse the given plugin command line arguments.
264 ///
265 /// \param CI - The compiler instance, for use in reporting diagnostics.
266 /// \return True if the parsing succeeded; otherwise the plugin will be
267 /// destroyed and no action run. The plugin is responsible for using the
268 /// CompilerInstance's Diagnostic object to report errors.
269 virtual bool ParseArgs(const CompilerInstance &CI,
270 const std::vector<std::string> &arg) = 0;
271
273 CmdlineBeforeMainAction, ///< Execute the action before the main action if
274 ///< on the command line
275 CmdlineAfterMainAction, ///< Execute the action after the main action if on
276 ///< the command line
277 ReplaceAction, ///< Replace the main action
278 AddBeforeMainAction, ///< Execute the action before the main action
279 AddAfterMainAction ///< Execute the action after the main action
280 };
281 /// Get the action type for this plugin
282 ///
283 /// \return The action type. By default we use CmdlineAfterMainAction.
285};
286
287/// Abstract base class to use for preprocessor-based frontend actions.
289protected:
290 /// Provide a default implementation which returns aborts;
291 /// this method should never be called by FrontendAction clients.
292 std::unique_ptr<ASTConsumer> CreateASTConsumer(CompilerInstance &CI,
293 StringRef InFile) override;
294
295public:
296 bool usesPreprocessorOnly() const override { return true; }
297};
298
299/// A frontend action which simply wraps some other runtime-specified
300/// frontend action.
301///
302/// Deriving from this class allows an action to inject custom logic around
303/// some existing action's behavior. It implements every virtual method in
304/// the FrontendAction interface by forwarding to the wrapped action.
306protected:
307 std::unique_ptr<FrontendAction> WrappedAction;
308
309 bool PrepareToExecuteAction(CompilerInstance &CI) override;
310 std::unique_ptr<ASTConsumer> CreateASTConsumer(CompilerInstance &CI,
311 StringRef InFile) override;
312 bool BeginInvocation(CompilerInstance &CI) override;
313 bool BeginSourceFileAction(CompilerInstance &CI) override;
314 void ExecuteAction() override;
315 void EndSourceFile() override;
316 void EndSourceFileAction() override;
317 bool shouldEraseOutputFiles() override;
318
319public:
320 /// Construct a WrapperFrontendAction from an existing action, taking
321 /// ownership of it.
322 WrapperFrontendAction(std::unique_ptr<FrontendAction> WrappedAction);
323
324 bool usesPreprocessorOnly() const override;
326 bool hasPCHSupport() const override;
327 bool hasASTFileSupport() const override;
328 bool hasIRSupport() const override;
329 bool hasCodeCompletionSupport() const override;
330};
331
332} // end namespace clang
333
334#endif
Forward-declares and imports various common LLVM datatypes that clang wants to use unqualified.
Defines the clang::LangOptions interface.
Abstract base class to use for AST consumer-based frontend actions.
void ExecuteAction() override
Implement the ExecuteAction interface by running Sema on the already-initialized AST consumer.
bool usesPreprocessorOnly() const override
Does this action only use the preprocessor?
Frontend action adaptor that merges ASTs together.
Utility class for loading a ASTContext from an AST file.
Definition: ASTUnit.h:89
CompilerInstance - Helper class for managing a single instance of the Clang compiler.
Abstract base class for actions which can be performed by the frontend.
const FrontendInputFile & getCurrentInput() const
InputKind getCurrentFileKind() const
virtual void EndSourceFile()
Perform any per-file post processing, deallocate per-file objects, and run statistics and output file...
virtual bool shouldEraseOutputFiles()
Callback at the end of processing a single input, to determine if the output files should be erased o...
virtual bool hasIRSupport() const
Does this action support use with IR files?
virtual void EndSourceFileAction()
Callback at the end of processing a single input.
bool PrepareToExecute(CompilerInstance &CI)
Prepare the action to execute on the given compiler instance.
virtual std::unique_ptr< ASTConsumer > CreateASTConsumer(CompilerInstance &CI, StringRef InFile)=0
Create the AST consumer object for this action, if supported.
ASTUnit & getCurrentASTUnit() const
CompilerInstance & getCompilerInstance() const
virtual bool PrepareToExecuteAction(CompilerInstance &CI)
Prepare to execute the action on the given CompilerInstance.
llvm::Error Execute()
Set the source manager's main input file, and run the action.
virtual bool hasASTFileSupport() const
Does this action support use with AST files?
Module * getCurrentModule() const
void setCurrentInput(const FrontendInputFile &CurrentInput, std::unique_ptr< ASTUnit > AST=nullptr)
StringRef getCurrentFile() const
std::unique_ptr< ASTUnit > takeCurrentASTUnit()
virtual bool BeginSourceFileAction(CompilerInstance &CI)
Callback at the start of processing a single input.
virtual void ExecuteAction()=0
Callback to run the program action, using the initialized compiler instance.
void setCompilerInstance(CompilerInstance *Value)
virtual TranslationUnitKind getTranslationUnitKind()
For AST-based actions, the kind of translation unit we're handling.
bool BeginSourceFile(CompilerInstance &CI, const FrontendInputFile &Input)
Prepare the action for processing the input file Input.
virtual bool hasCodeCompletionSupport() const
Does this action support use with code completion?
StringRef getCurrentFileOrBufferName() const
virtual bool isModelParsingAction() const
Is this action invoked on a model file?
bool isCurrentFileAST() const
virtual bool usesPreprocessorOnly() const =0
Does this action only use the preprocessor?
friend class WrapperFrontendAction
virtual bool BeginInvocation(CompilerInstance &CI)
Callback before starting processing a single input, giving the opportunity to modify the CompilerInvo...
virtual bool hasPCHSupport() const
Does this action support use with PCH?
An input file for the front end.
llvm::MemoryBufferRef getBuffer() const
InputKind getKind() const
StringRef getFile() const
The kind of a file that we've been handed as an input.
Describes a module or submodule.
Definition: Module.h:105
std::unique_ptr< ASTConsumer > CreateASTConsumer(CompilerInstance &CI, StringRef InFile) override=0
Create the AST consumer object for this action, if supported.
virtual bool ParseArgs(const CompilerInstance &CI, const std::vector< std::string > &arg)=0
Parse the given plugin command line arguments.
@ AddAfterMainAction
Execute the action after the main action.
@ ReplaceAction
Replace the main action.
@ AddBeforeMainAction
Execute the action before the main action.
@ CmdlineBeforeMainAction
Execute the action before the main action if on the command line.
@ CmdlineAfterMainAction
Execute the action after the main action if on the command line.
virtual ActionType getActionType()
Get the action type for this plugin.
Abstract base class to use for preprocessor-based frontend actions.
std::unique_ptr< ASTConsumer > CreateASTConsumer(CompilerInstance &CI, StringRef InFile) override
Provide a default implementation which returns aborts; this method should never be called by Frontend...
bool usesPreprocessorOnly() const override
Does this action only use the preprocessor?
A frontend action which simply wraps some other runtime-specified frontend action.
bool BeginSourceFileAction(CompilerInstance &CI) override
Callback at the start of processing a single input.
bool hasIRSupport() const override
Does this action support use with IR files?
bool PrepareToExecuteAction(CompilerInstance &CI) override
Prepare to execute the action on the given CompilerInstance.
bool hasASTFileSupport() const override
Does this action support use with AST files?
bool usesPreprocessorOnly() const override
Does this action only use the preprocessor?
void ExecuteAction() override
Callback to run the program action, using the initialized compiler instance.
bool hasCodeCompletionSupport() const override
Does this action support use with code completion?
bool shouldEraseOutputFiles() override
Callback at the end of processing a single input, to determine if the output files should be erased o...
TranslationUnitKind getTranslationUnitKind() override
For AST-based actions, the kind of translation unit we're handling.
void EndSourceFileAction() override
Callback at the end of processing a single input.
bool BeginInvocation(CompilerInstance &CI) override
Callback before starting processing a single input, giving the opportunity to modify the CompilerInvo...
bool hasPCHSupport() const override
Does this action support use with PCH?
std::unique_ptr< ASTConsumer > CreateASTConsumer(CompilerInstance &CI, StringRef InFile) override
Create the AST consumer object for this action, if supported.
std::unique_ptr< FrontendAction > WrappedAction
void EndSourceFile() override
Perform any per-file post processing, deallocate per-file objects, and run statistics and output file...
The JSON file list parser is used to communicate input to InstallAPI.
TranslationUnitKind
Describes the kind of translation unit being processed.
Definition: LangOptions.h:987
@ TU_Complete
The translation unit is a complete translation unit.
Definition: LangOptions.h:989