clang  7.0.0svn
Tooling.h
Go to the documentation of this file.
1 //===- Tooling.h - Framework for standalone Clang tools ---------*- C++ -*-===//
2 //
3 // The LLVM Compiler Infrastructure
4 //
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
7 //
8 //===----------------------------------------------------------------------===//
9 //
10 // This file implements functions to run clang tools standalone instead
11 // of running them as a plugin.
12 //
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.
16 //
17 // It is also possible to run a FrontendAction over a snippet of code by
18 // calling runToolOnCode, which is useful for unit testing.
19 //
20 // Applications that need more fine grained control over how to run
21 // multiple FrontendActions over code can use ToolInvocation.
22 //
23 // Example tools:
24 // - running clang -fsyntax-only over source code from an editor to get
25 // fast syntax checks
26 // - running match/replace tools over C++ code
27 //
28 //===----------------------------------------------------------------------===//
29 
30 #ifndef LLVM_CLANG_TOOLING_TOOLING_H
31 #define LLVM_CLANG_TOOLING_TOOLING_H
32 
33 #include "clang/AST/ASTConsumer.h"
35 #include "clang/Basic/LLVM.h"
40 #include "llvm/ADT/ArrayRef.h"
41 #include "llvm/ADT/IntrusiveRefCntPtr.h"
42 #include "llvm/ADT/StringMap.h"
43 #include "llvm/ADT/StringRef.h"
44 #include "llvm/ADT/StringSet.h"
45 #include "llvm/ADT/Twine.h"
46 #include "llvm/Option/Option.h"
47 #include <memory>
48 #include <string>
49 #include <utility>
50 #include <vector>
51 
52 namespace clang {
53 
54 class CompilerInstance;
55 class CompilerInvocation;
56 class DiagnosticConsumer;
57 class DiagnosticsEngine;
58 class SourceManager;
59 
60 namespace driver {
61 
62 class Compilation;
63 
64 } // namespace driver
65 
66 namespace tooling {
67 
68 class CompilationDatabase;
69 
70 /// Interface to process a clang::CompilerInvocation.
71 ///
72 /// If your tool is based on FrontendAction, you should be deriving from
73 /// FrontendActionFactory instead.
74 class ToolAction {
75 public:
76  virtual ~ToolAction();
77 
78  /// Perform an action for an invocation.
79  virtual bool
80  runInvocation(std::shared_ptr<CompilerInvocation> Invocation,
81  FileManager *Files,
82  std::shared_ptr<PCHContainerOperations> PCHContainerOps,
83  DiagnosticConsumer *DiagConsumer) = 0;
84 };
85 
86 /// Interface to generate clang::FrontendActions.
87 ///
88 /// Having a factory interface allows, for example, a new FrontendAction to be
89 /// created for each translation unit processed by ClangTool. This class is
90 /// also a ToolAction which uses the FrontendActions created by create() to
91 /// process each translation unit.
93 public:
94  ~FrontendActionFactory() override;
95 
96  /// Invokes the compiler with a FrontendAction created by create().
97  bool runInvocation(std::shared_ptr<CompilerInvocation> Invocation,
98  FileManager *Files,
99  std::shared_ptr<PCHContainerOperations> PCHContainerOps,
100  DiagnosticConsumer *DiagConsumer) override;
101 
102  /// Returns a new clang::FrontendAction.
103  ///
104  /// The caller takes ownership of the returned action.
105  virtual FrontendAction *create() = 0;
106 };
107 
108 /// Returns a new FrontendActionFactory for a given type.
109 ///
110 /// T must derive from clang::FrontendAction.
111 ///
112 /// Example:
113 /// FrontendActionFactory *Factory =
114 /// newFrontendActionFactory<clang::SyntaxOnlyAction>();
115 template <typename T>
116 std::unique_ptr<FrontendActionFactory> newFrontendActionFactory();
117 
118 /// Callbacks called before and after each source file processed by a
119 /// FrontendAction created by the FrontedActionFactory returned by \c
120 /// newFrontendActionFactory.
122 public:
123  virtual ~SourceFileCallbacks() = default;
124 
125  /// Called before a source file is processed by a FrontEndAction.
126  /// \see clang::FrontendAction::BeginSourceFileAction
128  return true;
129  }
130 
131  /// Called after a source file is processed by a FrontendAction.
132  /// \see clang::FrontendAction::EndSourceFileAction
133  virtual void handleEndSource() {}
134 };
135 
136 /// Returns a new FrontendActionFactory for any type that provides an
137 /// implementation of newASTConsumer().
138 ///
139 /// FactoryT must implement: ASTConsumer *newASTConsumer().
140 ///
141 /// Example:
142 /// struct ProvidesASTConsumers {
143 /// clang::ASTConsumer *newASTConsumer();
144 /// } Factory;
145 /// std::unique_ptr<FrontendActionFactory> FactoryAdapter(
146 /// newFrontendActionFactory(&Factory));
147 template <typename FactoryT>
148 inline std::unique_ptr<FrontendActionFactory> newFrontendActionFactory(
149  FactoryT *ConsumerFactory, SourceFileCallbacks *Callbacks = nullptr);
150 
151 /// Runs (and deletes) the tool on 'Code' with the -fsyntax-only flag.
152 ///
153 /// \param ToolAction The action to run over the code.
154 /// \param Code C++ code.
155 /// \param FileName The file name which 'Code' will be mapped as.
156 /// \param PCHContainerOps The PCHContainerOperations for loading and creating
157 /// clang modules.
158 ///
159 /// \return - True if 'ToolAction' was successfully executed.
160 bool runToolOnCode(FrontendAction *ToolAction, const Twine &Code,
161  const Twine &FileName = "input.cc",
162  std::shared_ptr<PCHContainerOperations> PCHContainerOps =
163  std::make_shared<PCHContainerOperations>());
164 
165 /// The first part of the pair is the filename, the second part the
166 /// file-content.
167 using FileContentMappings = std::vector<std::pair<std::string, std::string>>;
168 
169 /// Runs (and deletes) the tool on 'Code' with the -fsyntax-only flag and
170 /// with additional other flags.
171 ///
172 /// \param ToolAction The action to run over the code.
173 /// \param Code C++ code.
174 /// \param Args Additional flags to pass on.
175 /// \param FileName The file name which 'Code' will be mapped as.
176 /// \param ToolName The name of the binary running the tool. Standard library
177 /// header paths will be resolved relative to this.
178 /// \param PCHContainerOps The PCHContainerOperations for loading and creating
179 /// clang modules.
180 ///
181 /// \return - True if 'ToolAction' was successfully executed.
183  FrontendAction *ToolAction, const Twine &Code,
184  const std::vector<std::string> &Args, const Twine &FileName = "input.cc",
185  const Twine &ToolName = "clang-tool",
186  std::shared_ptr<PCHContainerOperations> PCHContainerOps =
187  std::make_shared<PCHContainerOperations>(),
188  const FileContentMappings &VirtualMappedFiles = FileContentMappings());
189 
190 // Similar to the overload except this takes a VFS.
192  FrontendAction *ToolAction, const Twine &Code,
194  const std::vector<std::string> &Args, const Twine &FileName = "input.cc",
195  const Twine &ToolName = "clang-tool",
196  std::shared_ptr<PCHContainerOperations> PCHContainerOps =
197  std::make_shared<PCHContainerOperations>());
198 
199 /// Builds an AST for 'Code'.
200 ///
201 /// \param Code C++ code.
202 /// \param FileName The file name which 'Code' will be mapped as.
203 /// \param PCHContainerOps The PCHContainerOperations for loading and creating
204 /// clang modules.
205 ///
206 /// \return The resulting AST or null if an error occurred.
207 std::unique_ptr<ASTUnit>
208 buildASTFromCode(const Twine &Code, const Twine &FileName = "input.cc",
209  std::shared_ptr<PCHContainerOperations> PCHContainerOps =
210  std::make_shared<PCHContainerOperations>());
211 
212 /// Builds an AST for 'Code' with additional flags.
213 ///
214 /// \param Code C++ code.
215 /// \param Args Additional flags to pass on.
216 /// \param FileName The file name which 'Code' will be mapped as.
217 /// \param ToolName The name of the binary running the tool. Standard library
218 /// header paths will be resolved relative to this.
219 /// \param PCHContainerOps The PCHContainerOperations for loading and creating
220 /// clang modules.
221 ///
222 /// \param Adjuster A function to filter the command line arguments as specified.
223 ///
224 /// \return The resulting AST or null if an error occurred.
225 std::unique_ptr<ASTUnit> buildASTFromCodeWithArgs(
226  const Twine &Code, const std::vector<std::string> &Args,
227  const Twine &FileName = "input.cc", const Twine &ToolName = "clang-tool",
228  std::shared_ptr<PCHContainerOperations> PCHContainerOps =
229  std::make_shared<PCHContainerOperations>(),
231 
232 /// Utility to run a FrontendAction in a single clang invocation.
234 public:
235  /// Create a tool invocation.
236  ///
237  /// \param CommandLine The command line arguments to clang. Note that clang
238  /// uses its binary name (CommandLine[0]) to locate its builtin headers.
239  /// Callers have to ensure that they are installed in a compatible location
240  /// (see clang driver implementation) or mapped in via mapVirtualFile.
241  /// \param FAction The action to be executed. Class takes ownership.
242  /// \param Files The FileManager used for the execution. Class does not take
243  /// ownership.
244  /// \param PCHContainerOps The PCHContainerOperations for loading and creating
245  /// clang modules.
246  ToolInvocation(std::vector<std::string> CommandLine, FrontendAction *FAction,
247  FileManager *Files,
248  std::shared_ptr<PCHContainerOperations> PCHContainerOps =
249  std::make_shared<PCHContainerOperations>());
250 
251  /// Create a tool invocation.
252  ///
253  /// \param CommandLine The command line arguments to clang.
254  /// \param Action The action to be executed.
255  /// \param Files The FileManager used for the execution.
256  /// \param PCHContainerOps The PCHContainerOperations for loading and creating
257  /// clang modules.
258  ToolInvocation(std::vector<std::string> CommandLine, ToolAction *Action,
259  FileManager *Files,
260  std::shared_ptr<PCHContainerOperations> PCHContainerOps);
261 
262  ~ToolInvocation();
263 
264  /// Set a \c DiagnosticConsumer to use during parsing.
266  this->DiagConsumer = DiagConsumer;
267  }
268 
269  /// Map a virtual file to be used while running the tool.
270  ///
271  /// \param FilePath The path at which the content will be mapped.
272  /// \param Content A null terminated buffer of the file's content.
273  // FIXME: remove this when all users have migrated!
274  void mapVirtualFile(StringRef FilePath, StringRef Content);
275 
276  /// Run the clang invocation.
277  ///
278  /// \returns True if there were no errors during execution.
279  bool run();
280 
281  private:
282  void addFileMappingsTo(SourceManager &SourceManager);
283 
284  bool runInvocation(const char *BinaryName,
285  driver::Compilation *Compilation,
286  std::shared_ptr<CompilerInvocation> Invocation,
287  std::shared_ptr<PCHContainerOperations> PCHContainerOps);
288 
289  std::vector<std::string> CommandLine;
290  ToolAction *Action;
291  bool OwnsAction;
292  FileManager *Files;
293  std::shared_ptr<PCHContainerOperations> PCHContainerOps;
294  // Maps <file name> -> <file content>.
295  llvm::StringMap<StringRef> MappedFileContents;
296  DiagnosticConsumer *DiagConsumer = nullptr;
297 };
298 
299 /// Utility to run a FrontendAction over a set of files.
300 ///
301 /// This class is written to be usable for command line utilities.
302 /// By default the class uses ClangSyntaxOnlyAdjuster to modify
303 /// command line arguments before the arguments are used to run
304 /// a frontend action. One could install an additional command line
305 /// arguments adjuster by calling the appendArgumentsAdjuster() method.
306 class ClangTool {
307 public:
308  /// Constructs a clang tool to run over a list of files.
309  ///
310  /// \param Compilations The CompilationDatabase which contains the compile
311  /// command lines for the given source paths.
312  /// \param SourcePaths The source files to run over. If a source files is
313  /// not found in Compilations, it is skipped.
314  /// \param PCHContainerOps The PCHContainerOperations for loading and creating
315  /// clang modules.
316  /// \param BaseFS VFS used for all underlying file accesses when running the
317  /// tool.
318  ClangTool(const CompilationDatabase &Compilations,
319  ArrayRef<std::string> SourcePaths,
320  std::shared_ptr<PCHContainerOperations> PCHContainerOps =
321  std::make_shared<PCHContainerOperations>(),
324 
325  ~ClangTool();
326 
327  /// Set a \c DiagnosticConsumer to use during parsing.
329  this->DiagConsumer = DiagConsumer;
330  }
331 
332  /// Map a virtual file to be used while running the tool.
333  ///
334  /// \param FilePath The path at which the content will be mapped.
335  /// \param Content A null terminated buffer of the file's content.
336  void mapVirtualFile(StringRef FilePath, StringRef Content);
337 
338  /// Append a command line arguments adjuster to the adjuster chain.
339  ///
340  /// \param Adjuster An argument adjuster, which will be run on the output of
341  /// previous argument adjusters.
342  void appendArgumentsAdjuster(ArgumentsAdjuster Adjuster);
343 
344  /// Clear the command line arguments adjuster chain.
345  void clearArgumentsAdjusters();
346 
347  /// Runs an action over all files specified in the command line.
348  ///
349  /// \param Action Tool action.
350  ///
351  /// \returns 0 on success; 1 if any error occurred; 2 if there is no error but
352  /// some files are skipped due to missing compile commands.
353  int run(ToolAction *Action);
354 
355  /// Create an AST for each file specified in the command line and
356  /// append them to ASTs.
357  int buildASTs(std::vector<std::unique_ptr<ASTUnit>> &ASTs);
358 
359  /// Returns the file manager used in the tool.
360  ///
361  /// The file manager is shared between all translation units.
362  FileManager &getFiles() { return *Files; }
363 
364  llvm::ArrayRef<std::string> getSourcePaths() const { return SourcePaths; }
365 
366 private:
367  const CompilationDatabase &Compilations;
368  std::vector<std::string> SourcePaths;
369  std::shared_ptr<PCHContainerOperations> PCHContainerOps;
370 
374 
375  // Contains a list of pairs (<file name>, <file content>).
376  std::vector<std::pair<StringRef, StringRef>> MappedFileContents;
377 
378  llvm::StringSet<> SeenWorkingDirectories;
379 
380  ArgumentsAdjuster ArgsAdjuster;
381 
382  DiagnosticConsumer *DiagConsumer = nullptr;
383 };
384 
385 template <typename T>
386 std::unique_ptr<FrontendActionFactory> newFrontendActionFactory() {
387  class SimpleFrontendActionFactory : public FrontendActionFactory {
388  public:
389  FrontendAction *create() override { return new T; }
390  };
391 
392  return std::unique_ptr<FrontendActionFactory>(
393  new SimpleFrontendActionFactory);
394 }
395 
396 template <typename FactoryT>
397 inline std::unique_ptr<FrontendActionFactory> newFrontendActionFactory(
398  FactoryT *ConsumerFactory, SourceFileCallbacks *Callbacks) {
399  class FrontendActionFactoryAdapter : public FrontendActionFactory {
400  public:
401  explicit FrontendActionFactoryAdapter(FactoryT *ConsumerFactory,
402  SourceFileCallbacks *Callbacks)
403  : ConsumerFactory(ConsumerFactory), Callbacks(Callbacks) {}
404 
405  FrontendAction *create() override {
406  return new ConsumerFactoryAdaptor(ConsumerFactory, Callbacks);
407  }
408 
409  private:
410  class ConsumerFactoryAdaptor : public ASTFrontendAction {
411  public:
412  ConsumerFactoryAdaptor(FactoryT *ConsumerFactory,
413  SourceFileCallbacks *Callbacks)
414  : ConsumerFactory(ConsumerFactory), Callbacks(Callbacks) {}
415 
416  std::unique_ptr<ASTConsumer>
417  CreateASTConsumer(CompilerInstance &, StringRef) override {
418  return ConsumerFactory->newASTConsumer();
419  }
420 
421  protected:
422  bool BeginSourceFileAction(CompilerInstance &CI) override {
424  return false;
425  if (Callbacks)
426  return Callbacks->handleBeginSource(CI);
427  return true;
428  }
429 
430  void EndSourceFileAction() override {
431  if (Callbacks)
432  Callbacks->handleEndSource();
434  }
435 
436  private:
437  FactoryT *ConsumerFactory;
438  SourceFileCallbacks *Callbacks;
439  };
440  FactoryT *ConsumerFactory;
441  SourceFileCallbacks *Callbacks;
442  };
443 
444  return std::unique_ptr<FrontendActionFactory>(
445  new FrontendActionFactoryAdapter(ConsumerFactory, Callbacks));
446 }
447 
448 /// Returns the absolute path of \c File, by prepending it with
449 /// the current directory if \c File is not absolute.
450 ///
451 /// Otherwise returns \c File.
452 /// If 'File' starts with "./", the returned path will not contain the "./".
453 /// Otherwise, the returned path will contain the literal path-concatenation of
454 /// the current directory and \c File.
455 ///
456 /// The difference to llvm::sys::fs::make_absolute is the canonicalization this
457 /// does by removing "./" and computing native paths.
458 ///
459 /// \param File Either an absolute or relative path.
460 std::string getAbsolutePath(StringRef File);
461 
462 /// Changes CommandLine to contain implicit flags that would have been
463 /// defined had the compiler driver been invoked through the path InvokedAs.
464 ///
465 /// For example, when called with \c InvokedAs set to `i686-linux-android-g++`,
466 /// the arguments '-target', 'i686-linux-android`, `--driver-mode=g++` will
467 /// be inserted after the first argument in \c CommandLine.
468 ///
469 /// This function will not add new `-target` or `--driver-mode` flags if they
470 /// are already present in `CommandLine` (even if they have different settings
471 /// than would have been inserted).
472 ///
473 /// \pre `llvm::InitializeAllTargets()` has been called.
474 ///
475 /// \param CommandLine the command line used to invoke the compiler driver or
476 /// Clang tool, including the path to the executable as \c CommandLine[0].
477 /// \param InvokedAs the path to the driver used to infer implicit flags.
478 ///
479 /// \note This will not set \c CommandLine[0] to \c InvokedAs. The tooling
480 /// infrastructure expects that CommandLine[0] is a tool path relative to which
481 /// the builtin headers can be found.
482 void addTargetAndModeForProgramName(std::vector<std::string> &CommandLine,
483  StringRef InvokedAs);
484 
485 /// Creates a \c CompilerInvocation.
487  const llvm::opt::ArgStringList &CC1Args);
488 
489 } // namespace tooling
490 
491 } // namespace clang
492 
493 #endif // LLVM_CLANG_TOOLING_TOOLING_H
Interface to process a clang::CompilerInvocation.
Definition: Tooling.h:74
void setDiagnosticConsumer(DiagnosticConsumer *DiagConsumer)
Set a DiagnosticConsumer to use during parsing.
Definition: Tooling.h:328
Implements support for file system lookup, file system caching, and directory search management...
Definition: FileManager.h:116
Defines the clang::FileManager interface and associated types.
IntrusiveRefCntPtr< FileSystem > getRealFileSystem()
Gets an vfs::FileSystem for the &#39;real&#39; file system, as seen by the operating system.
Abstract base class for actions which can be performed by the frontend.
Utility to run a FrontendAction over a set of files.
Definition: Tooling.h:306
Abstract interface, implemented by clients of the front-end, which formats and prints fully processed...
Definition: Diagnostic.h:1487
ArgumentsAdjuster getClangStripDependencyFileAdjuster()
Gets an argument adjuster which removes dependency-file related command line arguments.
Interface to generate clang::FrontendActions.
Definition: Tooling.h:92
virtual void handleEndSource()
Called after a source file is processed by a FrontendAction.
Definition: Tooling.h:133
virtual bool handleBeginSource(CompilerInstance &CI)
Called before a source file is processed by a FrontEndAction.
Definition: Tooling.h:127
Callbacks called before and after each source file processed by a FrontendAction created by the Front...
Definition: Tooling.h:121
Forward-declares and imports various common LLVM datatypes that clang wants to use unqualified...
Concrete class used by the front-end to report problems and issues.
Definition: Diagnostic.h:149
std::unique_ptr< FrontendActionFactory > newFrontendActionFactory(FactoryT *ConsumerFactory, SourceFileCallbacks *Callbacks=nullptr)
Returns a new FrontendActionFactory for any type that provides an implementation of newASTConsumer()...
Definition: Tooling.h:397
FileManager & getFiles()
Returns the file manager used in the tool.
Definition: Tooling.h:362
const FunctionProtoType * T
std::function< CommandLineArguments(const CommandLineArguments &, StringRef Filename)> ArgumentsAdjuster
A prototype of a command line adjuster.
std::string getAbsolutePath(StringRef File)
Returns the absolute path of File, by prepending it with the current directory if File is not absolut...
Definition: Tooling.cpp:202
virtual void EndSourceFileAction()
Callback at the end of processing a single input.
void addTargetAndModeForProgramName(std::vector< std::string > &CommandLine, StringRef InvokedAs)
Changes CommandLine to contain implicit flags that would have been defined had the compiler driver be...
Definition: Tooling.cpp:217
void setDiagnosticConsumer(DiagnosticConsumer *DiagConsumer)
Set a DiagnosticConsumer to use during parsing.
Definition: Tooling.h:265
Interface for compilation databases.
CompilerInstance - Helper class for managing a single instance of the Clang compiler.
bool runToolOnCodeWithArgs(FrontendAction *ToolAction, const Twine &Code, llvm::IntrusiveRefCntPtr< vfs::FileSystem > VFS, const std::vector< std::string > &Args, const Twine &FileName="input.cc", const Twine &ToolName="clang-tool", std::shared_ptr< PCHContainerOperations > PCHContainerOps=std::make_shared< PCHContainerOperations >())
Definition: Tooling.cpp:156
std::unique_ptr< ASTUnit > buildASTFromCodeWithArgs(const Twine &Code, const std::vector< std::string > &Args, const Twine &FileName="input.cc", const Twine &ToolName="clang-tool", std::shared_ptr< PCHContainerOperations > PCHContainerOps=std::make_shared< PCHContainerOperations >(), ArgumentsAdjuster Adjuster=getClangStripDependencyFileAdjuster())
Builds an AST for &#39;Code&#39; with additional flags.
Definition: Tooling.cpp:550
Abstract base class to use for AST consumer-based frontend actions.
Utility to run a FrontendAction in a single clang invocation.
Definition: Tooling.h:233
Dataflow Directional Tag Classes.
std::unique_ptr< DiagnosticConsumer > create(StringRef OutputFile, DiagnosticOptions *Diags, bool MergeChildRecords=false)
Returns a DiagnosticConsumer that serializes diagnostics to a bitcode file.
Helper class for holding the data necessary to invoke the compiler.
Defines the virtual file system interface vfs::FileSystem.
llvm::ArrayRef< std::string > getSourcePaths() const
Definition: Tooling.h:364
CompilerInvocation * newInvocation(DiagnosticsEngine *Diagnostics, const llvm::opt::ArgStringList &CC1Args)
Creates a CompilerInvocation.
Definition: Tooling.cpp:118
Compilation - A set of tasks to perform for a single driver invocation.
Definition: Compilation.h:46
std::unique_ptr< ASTUnit > buildASTFromCode(const Twine &Code, const Twine &FileName="input.cc", std::shared_ptr< PCHContainerOperations > PCHContainerOps=std::make_shared< PCHContainerOperations >())
Builds an AST for &#39;Code&#39;.
Definition: Tooling.cpp:544
virtual bool BeginSourceFileAction(CompilerInstance &CI)
Callback at the start of processing a single input.
Defines the clang::FrontendAction interface and various convenience abstract classes (clang::ASTFront...
bool runToolOnCode(FrontendAction *ToolAction, const Twine &Code, const Twine &FileName="input.cc", std::shared_ptr< PCHContainerOperations > PCHContainerOps=std::make_shared< PCHContainerOperations >())
Runs (and deletes) the tool on &#39;Code&#39; with the -fsyntax-only flag.
Definition: Tooling.cpp:130
This class handles loading and caching of source files into memory.
std::vector< std::pair< std::string, std::string > > FileContentMappings
The first part of the pair is the filename, the second part the file-content.
Definition: Tooling.h:167