clang  6.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"
34 #include "clang/Basic/Diagnostic.h"
36 #include "clang/Basic/LLVM.h"
37 #include "clang/Driver/Util.h"
40 #include "clang/Lex/ModuleLoader.h"
43 #include "llvm/ADT/StringMap.h"
44 #include "llvm/ADT/Twine.h"
45 #include "llvm/Option/Option.h"
46 #include <memory>
47 #include <string>
48 #include <vector>
49 
50 namespace clang {
51 
52 namespace driver {
53 class Compilation;
54 } // end namespace driver
55 
56 class CompilerInvocation;
57 class SourceManager;
58 class FrontendAction;
59 
60 namespace tooling {
61 
62 /// \brief Interface to process a clang::CompilerInvocation.
63 ///
64 /// If your tool is based on FrontendAction, you should be deriving from
65 /// FrontendActionFactory instead.
66 class ToolAction {
67 public:
68  virtual ~ToolAction();
69 
70  /// \brief Perform an action for an invocation.
71  virtual bool
72  runInvocation(std::shared_ptr<clang::CompilerInvocation> Invocation,
73  FileManager *Files,
74  std::shared_ptr<PCHContainerOperations> PCHContainerOps,
75  DiagnosticConsumer *DiagConsumer) = 0;
76 };
77 
78 /// \brief Interface to generate clang::FrontendActions.
79 ///
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.
85 public:
86  ~FrontendActionFactory() override;
87 
88  /// \brief Invokes the compiler with a FrontendAction created by create().
89  bool runInvocation(std::shared_ptr<clang::CompilerInvocation> Invocation,
90  FileManager *Files,
91  std::shared_ptr<PCHContainerOperations> PCHContainerOps,
92  DiagnosticConsumer *DiagConsumer) override;
93 
94  /// \brief Returns a new clang::FrontendAction.
95  ///
96  /// The caller takes ownership of the returned action.
97  virtual clang::FrontendAction *create() = 0;
98 };
99 
100 /// \brief Returns a new FrontendActionFactory for a given type.
101 ///
102 /// T must derive from clang::FrontendAction.
103 ///
104 /// Example:
105 /// FrontendActionFactory *Factory =
106 /// newFrontendActionFactory<clang::SyntaxOnlyAction>();
107 template <typename T>
108 std::unique_ptr<FrontendActionFactory> newFrontendActionFactory();
109 
110 /// \brief Callbacks called before and after each source file processed by a
111 /// FrontendAction created by the FrontedActionFactory returned by \c
112 /// newFrontendActionFactory.
114 public:
115  virtual ~SourceFileCallbacks() {}
116 
117  /// \brief Called before a source file is processed by a FrontEndAction.
118  /// \see clang::FrontendAction::BeginSourceFileAction
120  return true;
121  }
122 
123  /// \brief Called after a source file is processed by a FrontendAction.
124  /// \see clang::FrontendAction::EndSourceFileAction
125  virtual void handleEndSource() {}
126 };
127 
128 /// \brief Returns a new FrontendActionFactory for any type that provides an
129 /// implementation of newASTConsumer().
130 ///
131 /// FactoryT must implement: ASTConsumer *newASTConsumer().
132 ///
133 /// Example:
134 /// struct ProvidesASTConsumers {
135 /// clang::ASTConsumer *newASTConsumer();
136 /// } Factory;
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);
142 
143 /// \brief Runs (and deletes) the tool on 'Code' with the -fsyntax-only flag.
144 ///
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
149 /// clang modules.
150 ///
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>());
156 
157 /// The first part of the pair is the filename, the second part the
158 /// file-content.
159 typedef std::vector<std::pair<std::string, std::string>> FileContentMappings;
160 
161 /// \brief Runs (and deletes) the tool on 'Code' with the -fsyntax-only flag and
162 /// with additional other flags.
163 ///
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
171 /// clang modules.
172 ///
173 /// \return - True if 'ToolAction' was successfully executed.
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());
181 
182 /// \brief Builds an AST for 'Code'.
183 ///
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
187 /// clang modules.
188 ///
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>());
194 
195 /// \brief Builds an AST for 'Code' with additional flags.
196 ///
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
203 /// clang modules.
204 ///
205 /// \param Adjuster A function to filter the command line arguments as specified.
206 ///
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>(),
214 
215 /// \brief Utility to run a FrontendAction in a single clang invocation.
217 public:
218  /// \brief Create a tool invocation.
219  ///
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
226  /// ownership.
227  /// \param PCHContainerOps The PCHContainerOperations for loading and creating
228  /// clang modules.
229  ToolInvocation(std::vector<std::string> CommandLine, FrontendAction *FAction,
230  FileManager *Files,
231  std::shared_ptr<PCHContainerOperations> PCHContainerOps =
232  std::make_shared<PCHContainerOperations>());
233 
234  /// \brief Create a tool invocation.
235  ///
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
240  /// clang modules.
241  ToolInvocation(std::vector<std::string> CommandLine, ToolAction *Action,
242  FileManager *Files,
243  std::shared_ptr<PCHContainerOperations> PCHContainerOps);
244 
245  ~ToolInvocation();
246 
247  /// \brief Set a \c DiagnosticConsumer to use during parsing.
249  this->DiagConsumer = DiagConsumer;
250  }
251 
252  /// \brief Map a virtual file to be used while running the tool.
253  ///
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);
258 
259  /// \brief Run the clang invocation.
260  ///
261  /// \returns True if there were no errors during execution.
262  bool run();
263 
264  private:
265  void addFileMappingsTo(SourceManager &SourceManager);
266 
267  bool runInvocation(const char *BinaryName,
268  clang::driver::Compilation *Compilation,
269  std::shared_ptr<clang::CompilerInvocation> Invocation,
270  std::shared_ptr<PCHContainerOperations> PCHContainerOps);
271 
272  std::vector<std::string> CommandLine;
273  ToolAction *Action;
274  bool OwnsAction;
275  FileManager *Files;
276  std::shared_ptr<PCHContainerOperations> PCHContainerOps;
277  // Maps <file name> -> <file content>.
278  llvm::StringMap<StringRef> MappedFileContents;
279  DiagnosticConsumer *DiagConsumer;
280 };
281 
282 /// \brief Utility to run a FrontendAction over a set of files.
283 ///
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.
289 class ClangTool {
290  public:
291  /// \brief Constructs a clang tool to run over a list of files.
292  ///
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
298  /// clang modules.
299  ClangTool(const CompilationDatabase &Compilations,
300  ArrayRef<std::string> SourcePaths,
301  std::shared_ptr<PCHContainerOperations> PCHContainerOps =
302  std::make_shared<PCHContainerOperations>());
303 
304  ~ClangTool();
305 
306  /// \brief Set a \c DiagnosticConsumer to use during parsing.
308  this->DiagConsumer = DiagConsumer;
309  }
310 
311  /// \brief Map a virtual file to be used while running the tool.
312  ///
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);
316 
317  /// \brief Append a command line arguments adjuster to the adjuster chain.
318  ///
319  /// \param Adjuster An argument adjuster, which will be run on the output of
320  /// previous argument adjusters.
321  void appendArgumentsAdjuster(ArgumentsAdjuster Adjuster);
322 
323  /// \brief Clear the command line arguments adjuster chain.
324  void clearArgumentsAdjusters();
325 
326  /// Runs an action over all files specified in the command line.
327  ///
328  /// \param Action Tool action.
329  int run(ToolAction *Action);
330 
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);
334 
335  /// \brief Returns the file manager used in the tool.
336  ///
337  /// The file manager is shared between all translation units.
338  FileManager &getFiles() { return *Files; }
339 
340  llvm::ArrayRef<std::string> getSourcePaths() const { return SourcePaths; }
341 
342 private:
343  const CompilationDatabase &Compilations;
344  std::vector<std::string> SourcePaths;
345  std::shared_ptr<PCHContainerOperations> PCHContainerOps;
346 
350  // Contains a list of pairs (<file name>, <file content>).
351  std::vector< std::pair<StringRef, StringRef> > MappedFileContents;
352  llvm::StringSet<> SeenWorkingDirectories;
353 
354  ArgumentsAdjuster ArgsAdjuster;
355 
356  DiagnosticConsumer *DiagConsumer;
357 };
358 
359 template <typename T>
360 std::unique_ptr<FrontendActionFactory> newFrontendActionFactory() {
361  class SimpleFrontendActionFactory : public FrontendActionFactory {
362  public:
363  clang::FrontendAction *create() override { return new T; }
364  };
365 
366  return std::unique_ptr<FrontendActionFactory>(
367  new SimpleFrontendActionFactory);
368 }
369 
370 template <typename FactoryT>
371 inline std::unique_ptr<FrontendActionFactory> newFrontendActionFactory(
372  FactoryT *ConsumerFactory, SourceFileCallbacks *Callbacks) {
373  class FrontendActionFactoryAdapter : public FrontendActionFactory {
374  public:
375  explicit FrontendActionFactoryAdapter(FactoryT *ConsumerFactory,
376  SourceFileCallbacks *Callbacks)
377  : ConsumerFactory(ConsumerFactory), Callbacks(Callbacks) {}
378 
379  clang::FrontendAction *create() override {
380  return new ConsumerFactoryAdaptor(ConsumerFactory, Callbacks);
381  }
382 
383  private:
384  class ConsumerFactoryAdaptor : public clang::ASTFrontendAction {
385  public:
386  ConsumerFactoryAdaptor(FactoryT *ConsumerFactory,
387  SourceFileCallbacks *Callbacks)
388  : ConsumerFactory(ConsumerFactory), Callbacks(Callbacks) {}
389 
390  std::unique_ptr<clang::ASTConsumer>
391  CreateASTConsumer(clang::CompilerInstance &, StringRef) override {
392  return ConsumerFactory->newASTConsumer();
393  }
394 
395  protected:
396  bool BeginSourceFileAction(CompilerInstance &CI) override {
398  return false;
399  if (Callbacks)
400  return Callbacks->handleBeginSource(CI);
401  return true;
402  }
403  void EndSourceFileAction() override {
404  if (Callbacks)
405  Callbacks->handleEndSource();
407  }
408 
409  private:
410  FactoryT *ConsumerFactory;
411  SourceFileCallbacks *Callbacks;
412  };
413  FactoryT *ConsumerFactory;
414  SourceFileCallbacks *Callbacks;
415  };
416 
417  return std::unique_ptr<FrontendActionFactory>(
418  new FrontendActionFactoryAdapter(ConsumerFactory, Callbacks));
419 }
420 
421 /// \brief Returns the absolute path of \c File, by prepending it with
422 /// the current directory if \c File is not absolute.
423 ///
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.
428 ///
429 /// The difference to llvm::sys::fs::make_absolute is the canonicalization this
430 /// does by removing "./" and computing native paths.
431 ///
432 /// \param File Either an absolute or relative path.
433 std::string getAbsolutePath(StringRef File);
434 
435 /// \brief Changes CommandLine to contain implicit flags that would have been
436 /// defined had the compiler driver been invoked through the path InvokedAs.
437 ///
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.
441 ///
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).
445 ///
446 /// \pre `llvm::InitializeAllTargets()` has been called.
447 ///
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.
451 ///
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);
457 
458 /// \brief Creates a \c CompilerInvocation.
460  clang::DiagnosticsEngine *Diagnostics,
461  const llvm::opt::ArgStringList &CC1Args);
462 
463 } // end namespace tooling
464 } // end namespace clang
465 
466 #endif // LLVM_CLANG_TOOLING_TOOLING_H
Interface to process a clang::CompilerInvocation.
Definition: Tooling.h:66
void setDiagnosticConsumer(DiagnosticConsumer *DiagConsumer)
Set a DiagnosticConsumer to use during parsing.
Definition: Tooling.h:307
bool runToolOnCode(clang::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:107
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.
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:289
Abstract interface, implemented by clients of the front-end, which formats and prints fully processed...
Definition: Diagnostic.h:1397
ArgumentsAdjuster getClangStripDependencyFileAdjuster()
Gets an argument adjuster which removes dependency-file related command line arguments.
Interface to generate clang::FrontendActions.
Definition: Tooling.h:84
virtual void handleEndSource()
Called after a source file is processed by a FrontendAction.
Definition: Tooling.h:125
virtual bool handleBeginSource(CompilerInstance &CI)
Called before a source file is processed by a FrontEndAction.
Definition: Tooling.h:119
Callbacks called before and after each source file processed by a FrontendAction created by the Front...
Definition: Tooling.h:113
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:159
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:147
Defines the Diagnostic-related interfaces.
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:371
std::function< CommandLineArguments(const CommandLineArguments &, StringRef Filename)> ArgumentsAdjuster
A prototype of a command line adjuster.
FileManager & getFiles()
Returns the file manager used in the tool.
Definition: Tooling.h:338
const FunctionProtoType * T
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:163
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:178
void setDiagnosticConsumer(DiagnosticConsumer *DiagConsumer)
Set a DiagnosticConsumer to use during parsing.
Definition: Tooling.h:248
Interface for compilation databases.
CompilerInstance - Helper class for managing a single instance of the Clang compiler.
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:510
Abstract base class to use for AST consumer-based frontend actions.
Utility to run a FrontendAction in a single clang invocation.
Definition: Tooling.h:216
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.
llvm::ArrayRef< std::string > getSourcePaths() const
Definition: Tooling.h:340
Compilation - A set of tasks to perform for a single driver invocation.
Definition: Compilation.h:34
bool runToolOnCodeWithArgs(clang::FrontendAction *ToolAction, 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 >(), const FileContentMappings &VirtualMappedFiles=FileContentMappings())
Runs (and deletes) the tool on &#39;Code&#39; with the -fsyntax-only flag and with additional other flags...
Definition: Tooling.cpp:127
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:504
virtual bool BeginSourceFileAction(CompilerInstance &CI)
Callback at the start of processing a single input.
clang::CompilerInvocation * newInvocation(clang::DiagnosticsEngine *Diagnostics, const llvm::opt::ArgStringList &CC1Args)
Creates a CompilerInvocation.
Definition: Tooling.cpp:94
Defines the clang::FrontendAction interface and various convenience abstract classes (clang::ASTFront...
This class handles loading and caching of source files into memory.