contrib/llvm/tools/clang/include/clang/Tooling/Tooling.h

   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/Frontend/PCHContainerOperations.h"
  35 #include "clang/Basic/Diagnostic.h"
  36 #include "clang/Basic/FileManager.h"
  37 #include "clang/Basic/LLVM.h"
  38 #include "clang/Driver/Util.h"
  39 #include "clang/Frontend/FrontendAction.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"
  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(clang::CompilerInvocation *Invocation, FileManager *Files,
  73                 std::shared_ptr<PCHContainerOperations> PCHContainerOps,
  74                 DiagnosticConsumer *DiagConsumer) = 0;
  75 };
  76
  77 /// \brief Interface to generate clang::FrontendActions.
  78 ///
  79 /// Having a factory interface allows, for example, a new FrontendAction to be
  80 /// created for each translation unit processed by ClangTool.  This class is
  81 /// also a ToolAction which uses the FrontendActions created by create() to
  82 /// process each translation unit.
  83 class FrontendActionFactory : public ToolAction {
  84 public:
  85   ~FrontendActionFactory() override;
  86
  87   /// \brief Invokes the compiler with a FrontendAction created by create().
  88   bool runInvocation(clang::CompilerInvocation *Invocation, FileManager *Files,
  89                      std::shared_ptr<PCHContainerOperations> PCHContainerOps,
  90                      DiagnosticConsumer *DiagConsumer) override;
  91
  92   /// \brief Returns a new clang::FrontendAction.
  93   ///
  94   /// The caller takes ownership of the returned action.
  95   virtual clang::FrontendAction *create() = 0;
  96 };
  97
  98 /// \brief Returns a new FrontendActionFactory for a given type.
  99 ///
 100 /// T must derive from clang::FrontendAction.
 101 ///
 102 /// Example:
 103 /// FrontendActionFactory *Factory =
 104 ///   newFrontendActionFactory<clang::SyntaxOnlyAction>();
 105 template <typename T>
 106 std::unique_ptr<FrontendActionFactory> newFrontendActionFactory();
 107
 108 /// \brief Callbacks called before and after each source file processed by a
 109 /// FrontendAction created by the FrontedActionFactory returned by \c
 110 /// newFrontendActionFactory.
 111 class SourceFileCallbacks {
 112 public:
 113   virtual ~SourceFileCallbacks() {}
 114
 115   /// \brief Called before a source file is processed by a FrontEndAction.
 116   /// \see clang::FrontendAction::BeginSourceFileAction
 117   virtual bool handleBeginSource(CompilerInstance &CI, StringRef Filename) {
 118     return true;
 119   }
 120
 121   /// \brief Called after a source file is processed by a FrontendAction.
 122   /// \see clang::FrontendAction::EndSourceFileAction
 123   virtual void handleEndSource() {}
 124 };
 125
 126 /// \brief Returns a new FrontendActionFactory for any type that provides an
 127 /// implementation of newASTConsumer().
 128 ///
 129 /// FactoryT must implement: ASTConsumer *newASTConsumer().
 130 ///
 131 /// Example:
 132 /// struct ProvidesASTConsumers {
 133 ///   clang::ASTConsumer *newASTConsumer();
 134 /// } Factory;
 135 /// std::unique_ptr<FrontendActionFactory> FactoryAdapter(
 136 ///   newFrontendActionFactory(&Factory));
 137 template <typename FactoryT>
 138 inline std::unique_ptr<FrontendActionFactory> newFrontendActionFactory(
 139     FactoryT *ConsumerFactory, SourceFileCallbacks *Callbacks = nullptr);
 140
 141 /// \brief Runs (and deletes) the tool on 'Code' with the -fsyntax-only flag.
 142 ///
 143 /// \param ToolAction The action to run over the code.
 144 /// \param Code C++ code.
 145 /// \param FileName The file name which 'Code' will be mapped as.
 146 /// \param PCHContainerOps  The PCHContainerOperations for loading and creating
 147 ///                         clang modules.
 148 ///
 149 /// \return - True if 'ToolAction' was successfully executed.
 150 bool runToolOnCode(clang::FrontendAction *ToolAction, const Twine &Code,
 151                    const Twine &FileName = "input.cc",
 152                    std::shared_ptr<PCHContainerOperations> PCHContainerOps =
 153                        std::make_shared<PCHContainerOperations>());
 154
 155 /// The first part of the pair is the filename, the second part the
 156 /// file-content.
 157 typedef std::vector<std::pair<std::string, std::string>> FileContentMappings;
 158
 159 /// \brief Runs (and deletes) the tool on 'Code' with the -fsyntax-only flag and
 160 ///        with additional other flags.
 161 ///
 162 /// \param ToolAction The action to run over the code.
 163 /// \param Code C++ code.
 164 /// \param Args Additional flags to pass on.
 165 /// \param FileName The file name which 'Code' will be mapped as.
 166 /// \param PCHContainerOps   The PCHContainerOperations for loading and creating
 167 ///                          clang modules.
 168 ///
 169 /// \return - True if 'ToolAction' was successfully executed.
 170 bool runToolOnCodeWithArgs(
 171     clang::FrontendAction *ToolAction, const Twine &Code,
 172     const std::vector<std::string> &Args, const Twine &FileName = "input.cc",
 173     std::shared_ptr<PCHContainerOperations> PCHContainerOps =
 174         std::make_shared<PCHContainerOperations>(),
 175     const FileContentMappings &VirtualMappedFiles = FileContentMappings());
 176
 177 /// \brief Builds an AST for 'Code'.
 178 ///
 179 /// \param Code C++ code.
 180 /// \param FileName The file name which 'Code' will be mapped as.
 181 /// \param PCHContainerOps The PCHContainerOperations for loading and creating
 182 /// clang modules.
 183 ///
 184 /// \return The resulting AST or null if an error occurred.
 185 std::unique_ptr<ASTUnit>
 186 buildASTFromCode(const Twine &Code, const Twine &FileName = "input.cc",
 187                  std::shared_ptr<PCHContainerOperations> PCHContainerOps =
 188                      std::make_shared<PCHContainerOperations>());
 189
 190 /// \brief Builds an AST for 'Code' with additional flags.
 191 ///
 192 /// \param Code C++ code.
 193 /// \param Args Additional flags to pass on.
 194 /// \param FileName The file name which 'Code' will be mapped as.
 195 /// \param PCHContainerOps The PCHContainerOperations for loading and creating
 196 /// clang modules.
 197 ///
 198 /// \return The resulting AST or null if an error occurred.
 199 std::unique_ptr<ASTUnit> buildASTFromCodeWithArgs(
 200     const Twine &Code, const std::vector<std::string> &Args,
 201     const Twine &FileName = "input.cc",
 202     std::shared_ptr<PCHContainerOperations> PCHContainerOps =
 203         std::make_shared<PCHContainerOperations>());
 204
 205 /// \brief Utility to run a FrontendAction in a single clang invocation.
 206 class ToolInvocation {
 207 public:
 208   /// \brief Create a tool invocation.
 209   ///
 210   /// \param CommandLine The command line arguments to clang. Note that clang
 211   /// uses its binary name (CommandLine[0]) to locate its builtin headers.
 212   /// Callers have to ensure that they are installed in a compatible location
 213   /// (see clang driver implementation) or mapped in via mapVirtualFile.
 214   /// \param FAction The action to be executed. Class takes ownership.
 215   /// \param Files The FileManager used for the execution. Class does not take
 216   /// ownership.
 217   /// \param PCHContainerOps The PCHContainerOperations for loading and creating
 218   /// clang modules.
 219   ToolInvocation(std::vector<std::string> CommandLine, FrontendAction *FAction,
 220                  FileManager *Files,
 221                  std::shared_ptr<PCHContainerOperations> PCHContainerOps =
 222                      std::make_shared<PCHContainerOperations>());
 223
 224   /// \brief Create a tool invocation.
 225   ///
 226   /// \param CommandLine The command line arguments to clang.
 227   /// \param Action The action to be executed.
 228   /// \param Files The FileManager used for the execution.
 229   /// \param PCHContainerOps The PCHContainerOperations for loading and creating
 230   /// clang modules.
 231   ToolInvocation(std::vector<std::string> CommandLine, ToolAction *Action,
 232                  FileManager *Files,
 233                  std::shared_ptr<PCHContainerOperations> PCHContainerOps);
 234
 235   ~ToolInvocation();
 236
 237   /// \brief Set a \c DiagnosticConsumer to use during parsing.
 238   void setDiagnosticConsumer(DiagnosticConsumer *DiagConsumer) {
 239     this->DiagConsumer = DiagConsumer;
 240   }
 241
 242   /// \brief Map a virtual file to be used while running the tool.
 243   ///
 244   /// \param FilePath The path at which the content will be mapped.
 245   /// \param Content A null terminated buffer of the file's content.
 246   void mapVirtualFile(StringRef FilePath, StringRef Content);
 247
 248   /// \brief Run the clang invocation.
 249   ///
 250   /// \returns True if there were no errors during execution.
 251   bool run();
 252
 253  private:
 254   void addFileMappingsTo(SourceManager &SourceManager);
 255
 256   bool runInvocation(const char *BinaryName,
 257                      clang::driver::Compilation *Compilation,
 258                      clang::CompilerInvocation *Invocation,
 259                      std::shared_ptr<PCHContainerOperations> PCHContainerOps);
 260
 261   std::vector<std::string> CommandLine;
 262   ToolAction *Action;
 263   bool OwnsAction;
 264   FileManager *Files;
 265   std::shared_ptr<PCHContainerOperations> PCHContainerOps;
 266   // Maps <file name> -> <file content>.
 267   llvm::StringMap<StringRef> MappedFileContents;
 268   DiagnosticConsumer *DiagConsumer;
 269 };
 270
 271 /// \brief Utility to run a FrontendAction over a set of files.
 272 ///
 273 /// This class is written to be usable for command line utilities.
 274 /// By default the class uses ClangSyntaxOnlyAdjuster to modify
 275 /// command line arguments before the arguments are used to run
 276 /// a frontend action. One could install an additional command line
 277 /// arguments adjuster by calling the appendArgumentsAdjuster() method.
 278 class ClangTool {
 279  public:
 280   /// \brief Constructs a clang tool to run over a list of files.
 281   ///
 282   /// \param Compilations The CompilationDatabase which contains the compile
 283   ///        command lines for the given source paths.
 284   /// \param SourcePaths The source files to run over. If a source files is
 285   ///        not found in Compilations, it is skipped.
 286   /// \param PCHContainerOps The PCHContainerOperations for loading and creating
 287   /// clang modules.
 288   ClangTool(const CompilationDatabase &Compilations,
 289             ArrayRef<std::string> SourcePaths,
 290             std::shared_ptr<PCHContainerOperations> PCHContainerOps =
 291                 std::make_shared<PCHContainerOperations>());
 292
 293   ~ClangTool();
 294
 295   /// \brief Set a \c DiagnosticConsumer to use during parsing.
 296   void setDiagnosticConsumer(DiagnosticConsumer *DiagConsumer) {
 297     this->DiagConsumer = DiagConsumer;
 298   }
 299
 300   /// \brief Map a virtual file to be used while running the tool.
 301   ///
 302   /// \param FilePath The path at which the content will be mapped.
 303   /// \param Content A null terminated buffer of the file's content.
 304   void mapVirtualFile(StringRef FilePath, StringRef Content);
 305
 306   /// \brief Append a command line arguments adjuster to the adjuster chain.
 307   ///
 308   /// \param Adjuster An argument adjuster, which will be run on the output of
 309   ///        previous argument adjusters.
 310   void appendArgumentsAdjuster(ArgumentsAdjuster Adjuster);
 311
 312   /// \brief Clear the command line arguments adjuster chain.
 313   void clearArgumentsAdjusters();
 314
 315   /// Runs an action over all files specified in the command line.
 316   ///
 317   /// \param Action Tool action.
 318   int run(ToolAction *Action);
 319
 320   /// \brief Create an AST for each file specified in the command line and
 321   /// append them to ASTs.
 322   int buildASTs(std::vector<std::unique_ptr<ASTUnit>> &ASTs);
 323
 324   /// \brief Returns the file manager used in the tool.
 325   ///
 326   /// The file manager is shared between all translation units.
 327   FileManager &getFiles() { return *Files; }
 328
 329  private:
 330   const CompilationDatabase &Compilations;
 331   std::vector<std::string> SourcePaths;
 332   std::shared_ptr<PCHContainerOperations> PCHContainerOps;
 333
 334   llvm::IntrusiveRefCntPtr<FileManager> Files;
 335   // Contains a list of pairs (<file name>, <file content>).
 336   std::vector< std::pair<StringRef, StringRef> > MappedFileContents;
 337
 338   ArgumentsAdjuster ArgsAdjuster;
 339
 340   DiagnosticConsumer *DiagConsumer;
 341 };
 342
 343 template <typename T>
 344 std::unique_ptr<FrontendActionFactory> newFrontendActionFactory() {
 345   class SimpleFrontendActionFactory : public FrontendActionFactory {
 346   public:
 347     clang::FrontendAction *create() override { return new T; }
 348   };
 349
 350   return std::unique_ptr<FrontendActionFactory>(
 351       new SimpleFrontendActionFactory);
 352 }
 353
 354 template <typename FactoryT>
 355 inline std::unique_ptr<FrontendActionFactory> newFrontendActionFactory(
 356     FactoryT *ConsumerFactory, SourceFileCallbacks *Callbacks) {
 357   class FrontendActionFactoryAdapter : public FrontendActionFactory {
 358   public:
 359     explicit FrontendActionFactoryAdapter(FactoryT *ConsumerFactory,
 360                                           SourceFileCallbacks *Callbacks)
 361       : ConsumerFactory(ConsumerFactory), Callbacks(Callbacks) {}
 362
 363     clang::FrontendAction *create() override {
 364       return new ConsumerFactoryAdaptor(ConsumerFactory, Callbacks);
 365     }
 366
 367   private:
 368     class ConsumerFactoryAdaptor : public clang::ASTFrontendAction {
 369     public:
 370       ConsumerFactoryAdaptor(FactoryT *ConsumerFactory,
 371                              SourceFileCallbacks *Callbacks)
 372         : ConsumerFactory(ConsumerFactory), Callbacks(Callbacks) {}
 373
 374       std::unique_ptr<clang::ASTConsumer>
 375       CreateASTConsumer(clang::CompilerInstance &, StringRef) override {
 376         return ConsumerFactory->newASTConsumer();
 377       }
 378
 379     protected:
 380       bool BeginSourceFileAction(CompilerInstance &CI,
 381                                  StringRef Filename) override {
 382         if (!clang::ASTFrontendAction::BeginSourceFileAction(CI, Filename))
 383           return false;
 384         if (Callbacks)
 385           return Callbacks->handleBeginSource(CI, Filename);
 386         return true;
 387       }
 388       void EndSourceFileAction() override {
 389         if (Callbacks)
 390           Callbacks->handleEndSource();
 391         clang::ASTFrontendAction::EndSourceFileAction();
 392       }
 393
 394     private:
 395       FactoryT *ConsumerFactory;
 396       SourceFileCallbacks *Callbacks;
 397     };
 398     FactoryT *ConsumerFactory;
 399     SourceFileCallbacks *Callbacks;
 400   };
 401
 402   return std::unique_ptr<FrontendActionFactory>(
 403       new FrontendActionFactoryAdapter(ConsumerFactory, Callbacks));
 404 }
 405
 406 /// \brief Returns the absolute path of \c File, by prepending it with
 407 /// the current directory if \c File is not absolute.
 408 ///
 409 /// Otherwise returns \c File.
 410 /// If 'File' starts with "./", the returned path will not contain the "./".
 411 /// Otherwise, the returned path will contain the literal path-concatenation of
 412 /// the current directory and \c File.
 413 ///
 414 /// The difference to llvm::sys::fs::make_absolute is the canonicalization this
 415 /// does by removing "./" and computing native paths.
 416 ///
 417 /// \param File Either an absolute or relative path.
 418 std::string getAbsolutePath(StringRef File);
 419
 420 /// \brief Creates a \c CompilerInvocation.
 421 clang::CompilerInvocation *newInvocation(
 422     clang::DiagnosticsEngine *Diagnostics,
 423     const llvm::opt::ArgStringList &CC1Args);
 424
 425 } // end namespace tooling
 426 } // end namespace clang
 427
 428 #endif // LLVM_CLANG_TOOLING_TOOLING_H