1 //===--- Tooling.h - Framework for standalone Clang tools -------*- 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 implements functions to run clang tools standalone instead
11 // of running them as a plugin.
13 // A ClangTool is initialized with a CompilationDatabase and a set of files
14 // to run over. The tool will then run a user-specified FrontendAction over
15 // all TUs in which the given files are compiled.
17 // It is also possible to run a FrontendAction over a snippet of code by
18 // calling runToolOnCode, which is useful for unit testing.
20 // Applications that need more fine grained control over how to run
21 // multiple FrontendActions over code can use ToolInvocation.
24 // - running clang -fsyntax-only over source code from an editor to get
26 // - running match/replace tools over C++ code
28 //===----------------------------------------------------------------------===//
30 #ifndef LLVM_CLANG_TOOLING_TOOLING_H
31 #define LLVM_CLANG_TOOLING_TOOLING_H
33 #include "clang/AST/ASTConsumer.h"
34 #include "clang/Basic/Diagnostic.h"
35 #include "clang/Basic/FileManager.h"
36 #include "clang/Basic/LLVM.h"
37 #include "clang/Driver/Util.h"
38 #include "clang/Frontend/FrontendAction.h"
39 #include "clang/Frontend/PCHContainerOperations.h"
40 #include "clang/Lex/ModuleLoader.h"
41 #include "clang/Tooling/ArgumentsAdjusters.h"
42 #include "clang/Tooling/CompilationDatabase.h"
43 #include "llvm/ADT/StringMap.h"
44 #include "llvm/ADT/Twine.h"
45 #include "llvm/Option/Option.h"
54 } // end namespace driver
56 class CompilerInvocation;
62 /// \brief Interface to process a clang::CompilerInvocation.
64 /// If your tool is based on FrontendAction, you should be deriving from
65 /// FrontendActionFactory instead.
68 virtual ~ToolAction();
70 /// \brief Perform an action for an invocation.
72 runInvocation(std::shared_ptr<clang::CompilerInvocation> Invocation,
74 std::shared_ptr<PCHContainerOperations> PCHContainerOps,
75 DiagnosticConsumer *DiagConsumer) = 0;
78 /// \brief Interface to generate clang::FrontendActions.
80 /// Having a factory interface allows, for example, a new FrontendAction to be
81 /// created for each translation unit processed by ClangTool. This class is
82 /// also a ToolAction which uses the FrontendActions created by create() to
83 /// process each translation unit.
84 class FrontendActionFactory : public ToolAction {
86 ~FrontendActionFactory() override;
88 /// \brief Invokes the compiler with a FrontendAction created by create().
89 bool runInvocation(std::shared_ptr<clang::CompilerInvocation> Invocation,
91 std::shared_ptr<PCHContainerOperations> PCHContainerOps,
92 DiagnosticConsumer *DiagConsumer) override;
94 /// \brief Returns a new clang::FrontendAction.
96 /// The caller takes ownership of the returned action.
97 virtual clang::FrontendAction *create() = 0;
100 /// \brief Returns a new FrontendActionFactory for a given type.
102 /// T must derive from clang::FrontendAction.
105 /// FrontendActionFactory *Factory =
106 /// newFrontendActionFactory<clang::SyntaxOnlyAction>();
107 template <typename T>
108 std::unique_ptr<FrontendActionFactory> newFrontendActionFactory();
110 /// \brief Callbacks called before and after each source file processed by a
111 /// FrontendAction created by the FrontedActionFactory returned by \c
112 /// newFrontendActionFactory.
113 class SourceFileCallbacks {
115 virtual ~SourceFileCallbacks() {}
117 /// \brief Called before a source file is processed by a FrontEndAction.
118 /// \see clang::FrontendAction::BeginSourceFileAction
119 virtual bool handleBeginSource(CompilerInstance &CI) {
123 /// \brief Called after a source file is processed by a FrontendAction.
124 /// \see clang::FrontendAction::EndSourceFileAction
125 virtual void handleEndSource() {}
128 /// \brief Returns a new FrontendActionFactory for any type that provides an
129 /// implementation of newASTConsumer().
131 /// FactoryT must implement: ASTConsumer *newASTConsumer().
134 /// struct ProvidesASTConsumers {
135 /// clang::ASTConsumer *newASTConsumer();
137 /// std::unique_ptr<FrontendActionFactory> FactoryAdapter(
138 /// newFrontendActionFactory(&Factory));
139 template <typename FactoryT>
140 inline std::unique_ptr<FrontendActionFactory> newFrontendActionFactory(
141 FactoryT *ConsumerFactory, SourceFileCallbacks *Callbacks = nullptr);
143 /// \brief Runs (and deletes) the tool on 'Code' with the -fsyntax-only flag.
145 /// \param ToolAction The action to run over the code.
146 /// \param Code C++ code.
147 /// \param FileName The file name which 'Code' will be mapped as.
148 /// \param PCHContainerOps The PCHContainerOperations for loading and creating
151 /// \return - True if 'ToolAction' was successfully executed.
152 bool runToolOnCode(clang::FrontendAction *ToolAction, const Twine &Code,
153 const Twine &FileName = "input.cc",
154 std::shared_ptr<PCHContainerOperations> PCHContainerOps =
155 std::make_shared<PCHContainerOperations>());
157 /// The first part of the pair is the filename, the second part the
159 typedef std::vector<std::pair<std::string, std::string>> FileContentMappings;
161 /// \brief Runs (and deletes) the tool on 'Code' with the -fsyntax-only flag and
162 /// with additional other flags.
164 /// \param ToolAction The action to run over the code.
165 /// \param Code C++ code.
166 /// \param Args Additional flags to pass on.
167 /// \param FileName The file name which 'Code' will be mapped as.
168 /// \param ToolName The name of the binary running the tool. Standard library
169 /// header paths will be resolved relative to this.
170 /// \param PCHContainerOps The PCHContainerOperations for loading and creating
173 /// \return - True if 'ToolAction' was successfully executed.
174 bool runToolOnCodeWithArgs(
175 clang::FrontendAction *ToolAction, const Twine &Code,
176 const std::vector<std::string> &Args, const Twine &FileName = "input.cc",
177 const Twine &ToolName = "clang-tool",
178 std::shared_ptr<PCHContainerOperations> PCHContainerOps =
179 std::make_shared<PCHContainerOperations>(),
180 const FileContentMappings &VirtualMappedFiles = FileContentMappings());
182 /// \brief Builds an AST for 'Code'.
184 /// \param Code C++ code.
185 /// \param FileName The file name which 'Code' will be mapped as.
186 /// \param PCHContainerOps The PCHContainerOperations for loading and creating
189 /// \return The resulting AST or null if an error occurred.
190 std::unique_ptr<ASTUnit>
191 buildASTFromCode(const Twine &Code, const Twine &FileName = "input.cc",
192 std::shared_ptr<PCHContainerOperations> PCHContainerOps =
193 std::make_shared<PCHContainerOperations>());
195 /// \brief Builds an AST for 'Code' with additional flags.
197 /// \param Code C++ code.
198 /// \param Args Additional flags to pass on.
199 /// \param FileName The file name which 'Code' will be mapped as.
200 /// \param ToolName The name of the binary running the tool. Standard library
201 /// header paths will be resolved relative to this.
202 /// \param PCHContainerOps The PCHContainerOperations for loading and creating
205 /// \param Adjuster A function to filter the command line arguments as specified.
207 /// \return The resulting AST or null if an error occurred.
208 std::unique_ptr<ASTUnit> buildASTFromCodeWithArgs(
209 const Twine &Code, const std::vector<std::string> &Args,
210 const Twine &FileName = "input.cc", const Twine &ToolName = "clang-tool",
211 std::shared_ptr<PCHContainerOperations> PCHContainerOps =
212 std::make_shared<PCHContainerOperations>(),
213 ArgumentsAdjuster Adjuster = getClangStripDependencyFileAdjuster());
215 /// \brief Utility to run a FrontendAction in a single clang invocation.
216 class ToolInvocation {
218 /// \brief Create a tool invocation.
220 /// \param CommandLine The command line arguments to clang. Note that clang
221 /// uses its binary name (CommandLine[0]) to locate its builtin headers.
222 /// Callers have to ensure that they are installed in a compatible location
223 /// (see clang driver implementation) or mapped in via mapVirtualFile.
224 /// \param FAction The action to be executed. Class takes ownership.
225 /// \param Files The FileManager used for the execution. Class does not take
227 /// \param PCHContainerOps The PCHContainerOperations for loading and creating
229 ToolInvocation(std::vector<std::string> CommandLine, FrontendAction *FAction,
231 std::shared_ptr<PCHContainerOperations> PCHContainerOps =
232 std::make_shared<PCHContainerOperations>());
234 /// \brief Create a tool invocation.
236 /// \param CommandLine The command line arguments to clang.
237 /// \param Action The action to be executed.
238 /// \param Files The FileManager used for the execution.
239 /// \param PCHContainerOps The PCHContainerOperations for loading and creating
241 ToolInvocation(std::vector<std::string> CommandLine, ToolAction *Action,
243 std::shared_ptr<PCHContainerOperations> PCHContainerOps);
247 /// \brief Set a \c DiagnosticConsumer to use during parsing.
248 void setDiagnosticConsumer(DiagnosticConsumer *DiagConsumer) {
249 this->DiagConsumer = DiagConsumer;
252 /// \brief Map a virtual file to be used while running the tool.
254 /// \param FilePath The path at which the content will be mapped.
255 /// \param Content A null terminated buffer of the file's content.
256 // FIXME: remove this when all users have migrated!
257 void mapVirtualFile(StringRef FilePath, StringRef Content);
259 /// \brief Run the clang invocation.
261 /// \returns True if there were no errors during execution.
265 void addFileMappingsTo(SourceManager &SourceManager);
267 bool runInvocation(const char *BinaryName,
268 clang::driver::Compilation *Compilation,
269 std::shared_ptr<clang::CompilerInvocation> Invocation,
270 std::shared_ptr<PCHContainerOperations> PCHContainerOps);
272 std::vector<std::string> CommandLine;
276 std::shared_ptr<PCHContainerOperations> PCHContainerOps;
277 // Maps <file name> -> <file content>.
278 llvm::StringMap<StringRef> MappedFileContents;
279 DiagnosticConsumer *DiagConsumer;
282 /// \brief Utility to run a FrontendAction over a set of files.
284 /// This class is written to be usable for command line utilities.
285 /// By default the class uses ClangSyntaxOnlyAdjuster to modify
286 /// command line arguments before the arguments are used to run
287 /// a frontend action. One could install an additional command line
288 /// arguments adjuster by calling the appendArgumentsAdjuster() method.
291 /// \brief Constructs a clang tool to run over a list of files.
293 /// \param Compilations The CompilationDatabase which contains the compile
294 /// command lines for the given source paths.
295 /// \param SourcePaths The source files to run over. If a source files is
296 /// not found in Compilations, it is skipped.
297 /// \param PCHContainerOps The PCHContainerOperations for loading and creating
299 ClangTool(const CompilationDatabase &Compilations,
300 ArrayRef<std::string> SourcePaths,
301 std::shared_ptr<PCHContainerOperations> PCHContainerOps =
302 std::make_shared<PCHContainerOperations>());
306 /// \brief Set a \c DiagnosticConsumer to use during parsing.
307 void setDiagnosticConsumer(DiagnosticConsumer *DiagConsumer) {
308 this->DiagConsumer = DiagConsumer;
311 /// \brief Map a virtual file to be used while running the tool.
313 /// \param FilePath The path at which the content will be mapped.
314 /// \param Content A null terminated buffer of the file's content.
315 void mapVirtualFile(StringRef FilePath, StringRef Content);
317 /// \brief Append a command line arguments adjuster to the adjuster chain.
319 /// \param Adjuster An argument adjuster, which will be run on the output of
320 /// previous argument adjusters.
321 void appendArgumentsAdjuster(ArgumentsAdjuster Adjuster);
323 /// \brief Clear the command line arguments adjuster chain.
324 void clearArgumentsAdjusters();
326 /// Runs an action over all files specified in the command line.
328 /// \param Action Tool action.
329 int run(ToolAction *Action);
331 /// \brief Create an AST for each file specified in the command line and
332 /// append them to ASTs.
333 int buildASTs(std::vector<std::unique_ptr<ASTUnit>> &ASTs);
335 /// \brief Returns the file manager used in the tool.
337 /// The file manager is shared between all translation units.
338 FileManager &getFiles() { return *Files; }
340 llvm::ArrayRef<std::string> getSourcePaths() const { return SourcePaths; }
343 const CompilationDatabase &Compilations;
344 std::vector<std::string> SourcePaths;
345 std::shared_ptr<PCHContainerOperations> PCHContainerOps;
347 llvm::IntrusiveRefCntPtr<vfs::OverlayFileSystem> OverlayFileSystem;
348 llvm::IntrusiveRefCntPtr<vfs::InMemoryFileSystem> InMemoryFileSystem;
349 llvm::IntrusiveRefCntPtr<FileManager> Files;
350 // Contains a list of pairs (<file name>, <file content>).
351 std::vector< std::pair<StringRef, StringRef> > MappedFileContents;
352 llvm::StringSet<> SeenWorkingDirectories;
354 ArgumentsAdjuster ArgsAdjuster;
356 DiagnosticConsumer *DiagConsumer;
359 template <typename T>
360 std::unique_ptr<FrontendActionFactory> newFrontendActionFactory() {
361 class SimpleFrontendActionFactory : public FrontendActionFactory {
363 clang::FrontendAction *create() override { return new T; }
366 return std::unique_ptr<FrontendActionFactory>(
367 new SimpleFrontendActionFactory);
370 template <typename FactoryT>
371 inline std::unique_ptr<FrontendActionFactory> newFrontendActionFactory(
372 FactoryT *ConsumerFactory, SourceFileCallbacks *Callbacks) {
373 class FrontendActionFactoryAdapter : public FrontendActionFactory {
375 explicit FrontendActionFactoryAdapter(FactoryT *ConsumerFactory,
376 SourceFileCallbacks *Callbacks)
377 : ConsumerFactory(ConsumerFactory), Callbacks(Callbacks) {}
379 clang::FrontendAction *create() override {
380 return new ConsumerFactoryAdaptor(ConsumerFactory, Callbacks);
384 class ConsumerFactoryAdaptor : public clang::ASTFrontendAction {
386 ConsumerFactoryAdaptor(FactoryT *ConsumerFactory,
387 SourceFileCallbacks *Callbacks)
388 : ConsumerFactory(ConsumerFactory), Callbacks(Callbacks) {}
390 std::unique_ptr<clang::ASTConsumer>
391 CreateASTConsumer(clang::CompilerInstance &, StringRef) override {
392 return ConsumerFactory->newASTConsumer();
396 bool BeginSourceFileAction(CompilerInstance &CI) override {
397 if (!clang::ASTFrontendAction::BeginSourceFileAction(CI))
400 return Callbacks->handleBeginSource(CI);
403 void EndSourceFileAction() override {
405 Callbacks->handleEndSource();
406 clang::ASTFrontendAction::EndSourceFileAction();
410 FactoryT *ConsumerFactory;
411 SourceFileCallbacks *Callbacks;
413 FactoryT *ConsumerFactory;
414 SourceFileCallbacks *Callbacks;
417 return std::unique_ptr<FrontendActionFactory>(
418 new FrontendActionFactoryAdapter(ConsumerFactory, Callbacks));
421 /// \brief Returns the absolute path of \c File, by prepending it with
422 /// the current directory if \c File is not absolute.
424 /// Otherwise returns \c File.
425 /// If 'File' starts with "./", the returned path will not contain the "./".
426 /// Otherwise, the returned path will contain the literal path-concatenation of
427 /// the current directory and \c File.
429 /// The difference to llvm::sys::fs::make_absolute is the canonicalization this
430 /// does by removing "./" and computing native paths.
432 /// \param File Either an absolute or relative path.
433 std::string getAbsolutePath(StringRef File);
435 /// \brief Changes CommandLine to contain implicit flags that would have been
436 /// defined had the compiler driver been invoked through the path InvokedAs.
438 /// For example, when called with \c InvokedAs set to `i686-linux-android-g++`,
439 /// the arguments '-target', 'i686-linux-android`, `--driver-mode=g++` will
440 /// be inserted after the first argument in \c CommandLine.
442 /// This function will not add new `-target` or `--driver-mode` flags if they
443 /// are already present in `CommandLine` (even if they have different settings
444 /// than would have been inserted).
446 /// \pre `llvm::InitializeAllTargets()` has been called.
448 /// \param CommandLine the command line used to invoke the compiler driver or
449 /// Clang tool, including the path to the executable as \c CommandLine[0].
450 /// \param InvokedAs the path to the driver used to infer implicit flags.
452 /// \note This will not set \c CommandLine[0] to \c InvokedAs. The tooling
453 /// infrastructure expects that CommandLine[0] is a tool path relative to which
454 /// the builtin headers can be found.
455 void addTargetAndModeForProgramName(std::vector<std::string> &CommandLine,
456 StringRef InvokedAs);
458 /// \brief Creates a \c CompilerInvocation.
459 clang::CompilerInvocation *newInvocation(
460 clang::DiagnosticsEngine *Diagnostics,
461 const llvm::opt::ArgStringList &CC1Args);
463 } // end namespace tooling
464 } // end namespace clang
466 #endif // LLVM_CLANG_TOOLING_TOOLING_H