include/clang/Tooling/Tooling.h

   1 //===- Tooling.h - Framework for standalone Clang tools ---------*- 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 //  This file implements functions to run clang tools standalone instead
  10 //  of running them as a plugin.
  11 //
  12 //  A ClangTool is initialized with a CompilationDatabase and a set of files
  13 //  to run over. The tool will then run a user-specified FrontendAction over
  14 //  all TUs in which the given files are compiled.
  15 //
  16 //  It is also possible to run a FrontendAction over a snippet of code by
  17 //  calling runToolOnCode, which is useful for unit testing.
  18 //
  19 //  Applications that need more fine grained control over how to run
  20 //  multiple FrontendActions over code can use ToolInvocation.
  21 //
  22 //  Example tools:
  23 //  - running clang -fsyntax-only over source code from an editor to get
  24 //    fast syntax checks
  25 //  - running match/replace tools over C++ code
  26 //
  27 //===----------------------------------------------------------------------===//
  28
  29 #ifndef LLVM_CLANG_TOOLING_TOOLING_H
  30 #define LLVM_CLANG_TOOLING_TOOLING_H
  31
  32 #include "clang/AST/ASTConsumer.h"
  33 #include "clang/Basic/FileManager.h"
  34 #include "clang/Basic/LLVM.h"
  35 #include "clang/Frontend/FrontendAction.h"
  36 #include "clang/Frontend/PCHContainerOperations.h"
  37 #include "clang/Tooling/ArgumentsAdjusters.h"
  38 #include "llvm/ADT/ArrayRef.h"
  39 #include "llvm/ADT/IntrusiveRefCntPtr.h"
  40 #include "llvm/ADT/StringMap.h"
  41 #include "llvm/ADT/StringRef.h"
  42 #include "llvm/ADT/StringSet.h"
  43 #include "llvm/ADT/Twine.h"
  44 #include "llvm/Option/Option.h"
  45 #include "llvm/Support/VirtualFileSystem.h"
  46 #include <memory>
  47 #include <string>
  48 #include <utility>
  49 #include <vector>
  50
  51 namespace clang {
  52
  53 class CompilerInstance;
  54 class CompilerInvocation;
  55 class DiagnosticConsumer;
  56 class DiagnosticsEngine;
  57 class SourceManager;
  58
  59 namespace driver {
  60
  61 class Compilation;
  62
  63 } // namespace driver
  64
  65 namespace tooling {
  66
  67 class CompilationDatabase;
  68
  69 /// Interface to process a clang::CompilerInvocation.
  70 ///
  71 /// If your tool is based on FrontendAction, you should be deriving from
  72 /// FrontendActionFactory instead.
  73 class ToolAction {
  74 public:
  75   virtual ~ToolAction();
  76
  77   /// Perform an action for an invocation.
  78   virtual bool
  79   runInvocation(std::shared_ptr<CompilerInvocation> Invocation,
  80                 FileManager *Files,
  81                 std::shared_ptr<PCHContainerOperations> PCHContainerOps,
  82                 DiagnosticConsumer *DiagConsumer) = 0;
  83 };
  84
  85 /// Interface to generate clang::FrontendActions.
  86 ///
  87 /// Having a factory interface allows, for example, a new FrontendAction to be
  88 /// created for each translation unit processed by ClangTool.  This class is
  89 /// also a ToolAction which uses the FrontendActions created by create() to
  90 /// process each translation unit.
  91 class FrontendActionFactory : public ToolAction {
  92 public:
  93   ~FrontendActionFactory() override;
  94
  95   /// Invokes the compiler with a FrontendAction created by create().
  96   bool runInvocation(std::shared_ptr<CompilerInvocation> Invocation,
  97                      FileManager *Files,
  98                      std::shared_ptr<PCHContainerOperations> PCHContainerOps,
  99                      DiagnosticConsumer *DiagConsumer) override;
 100
 101   /// Returns a new clang::FrontendAction.
 102   virtual std::unique_ptr<FrontendAction> create() = 0;
 103 };
 104
 105 /// Returns a new FrontendActionFactory for a given type.
 106 ///
 107 /// T must derive from clang::FrontendAction.
 108 ///
 109 /// Example:
 110 /// FrontendActionFactory *Factory =
 111 ///   newFrontendActionFactory<clang::SyntaxOnlyAction>();
 112 template <typename T>
 113 std::unique_ptr<FrontendActionFactory> newFrontendActionFactory();
 114
 115 /// Callbacks called before and after each source file processed by a
 116 /// FrontendAction created by the FrontedActionFactory returned by \c
 117 /// newFrontendActionFactory.
 118 class SourceFileCallbacks {
 119 public:
 120   virtual ~SourceFileCallbacks() = default;
 121
 122   /// Called before a source file is processed by a FrontEndAction.
 123   /// \see clang::FrontendAction::BeginSourceFileAction
 124   virtual bool handleBeginSource(CompilerInstance &CI) {
 125     return true;
 126   }
 127
 128   /// Called after a source file is processed by a FrontendAction.
 129   /// \see clang::FrontendAction::EndSourceFileAction
 130   virtual void handleEndSource() {}
 131 };
 132
 133 /// Returns a new FrontendActionFactory for any type that provides an
 134 /// implementation of newASTConsumer().
 135 ///
 136 /// FactoryT must implement: ASTConsumer *newASTConsumer().
 137 ///
 138 /// Example:
 139 /// struct ProvidesASTConsumers {
 140 ///   clang::ASTConsumer *newASTConsumer();
 141 /// } Factory;
 142 /// std::unique_ptr<FrontendActionFactory> FactoryAdapter(
 143 ///   newFrontendActionFactory(&Factory));
 144 template <typename FactoryT>
 145 inline std::unique_ptr<FrontendActionFactory> newFrontendActionFactory(
 146     FactoryT *ConsumerFactory, SourceFileCallbacks *Callbacks = nullptr);
 147
 148 /// Runs (and deletes) the tool on 'Code' with the -fsyntax-only flag.
 149 ///
 150 /// \param ToolAction The action to run over the code.
 151 /// \param Code C++ code.
 152 /// \param FileName The file name which 'Code' will be mapped as.
 153 /// \param PCHContainerOps  The PCHContainerOperations for loading and creating
 154 ///                         clang modules.
 155 ///
 156 /// \return - True if 'ToolAction' was successfully executed.
 157 bool runToolOnCode(std::unique_ptr<FrontendAction> ToolAction, const Twine &Code,
 158                    const Twine &FileName = "input.cc",
 159                    std::shared_ptr<PCHContainerOperations> PCHContainerOps =
 160                        std::make_shared<PCHContainerOperations>());
 161
 162 /// The first part of the pair is the filename, the second part the
 163 /// file-content.
 164 using FileContentMappings = std::vector<std::pair<std::string, std::string>>;
 165
 166 /// Runs (and deletes) the tool on 'Code' with the -fsyntax-only flag and
 167 ///        with additional other flags.
 168 ///
 169 /// \param ToolAction The action to run over the code.
 170 /// \param Code C++ code.
 171 /// \param Args Additional flags to pass on.
 172 /// \param FileName The file name which 'Code' will be mapped as.
 173 /// \param ToolName The name of the binary running the tool. Standard library
 174 ///                 header paths will be resolved relative to this.
 175 /// \param PCHContainerOps   The PCHContainerOperations for loading and creating
 176 ///                          clang modules.
 177 ///
 178 /// \return - True if 'ToolAction' was successfully executed.
 179 bool runToolOnCodeWithArgs(
 180     std::unique_ptr<FrontendAction> ToolAction, const Twine &Code,
 181     const std::vector<std::string> &Args, const Twine &FileName = "input.cc",
 182     const Twine &ToolName = "clang-tool",
 183     std::shared_ptr<PCHContainerOperations> PCHContainerOps =
 184         std::make_shared<PCHContainerOperations>(),
 185     const FileContentMappings &VirtualMappedFiles = FileContentMappings());
 186
 187 // Similar to the overload except this takes a VFS.
 188 bool runToolOnCodeWithArgs(
 189     std::unique_ptr<FrontendAction> ToolAction, const Twine &Code,
 190     llvm::IntrusiveRefCntPtr<llvm::vfs::FileSystem> VFS,
 191     const std::vector<std::string> &Args, const Twine &FileName = "input.cc",
 192     const Twine &ToolName = "clang-tool",
 193     std::shared_ptr<PCHContainerOperations> PCHContainerOps =
 194         std::make_shared<PCHContainerOperations>());
 195
 196 /// Builds an AST for 'Code'.
 197 ///
 198 /// \param Code C++ code.
 199 /// \param FileName The file name which 'Code' will be mapped as.
 200 /// \param PCHContainerOps The PCHContainerOperations for loading and creating
 201 /// clang modules.
 202 ///
 203 /// \return The resulting AST or null if an error occurred.
 204 std::unique_ptr<ASTUnit>
 205 buildASTFromCode(StringRef Code, StringRef FileName = "input.cc",
 206                  std::shared_ptr<PCHContainerOperations> PCHContainerOps =
 207                      std::make_shared<PCHContainerOperations>());
 208
 209 /// Builds an AST for 'Code' with additional flags.
 210 ///
 211 /// \param Code C++ code.
 212 /// \param Args Additional flags to pass on.
 213 /// \param FileName The file name which 'Code' will be mapped as.
 214 /// \param ToolName The name of the binary running the tool. Standard library
 215 ///                 header paths will be resolved relative to this.
 216 /// \param PCHContainerOps The PCHContainerOperations for loading and creating
 217 /// clang modules.
 218 ///
 219 /// \param Adjuster A function to filter the command line arguments as specified.
 220 ///
 221 /// \return The resulting AST or null if an error occurred.
 222 std::unique_ptr<ASTUnit> buildASTFromCodeWithArgs(
 223     StringRef Code, const std::vector<std::string> &Args,
 224     StringRef FileName = "input.cc", StringRef ToolName = "clang-tool",
 225     std::shared_ptr<PCHContainerOperations> PCHContainerOps =
 226         std::make_shared<PCHContainerOperations>(),
 227     ArgumentsAdjuster Adjuster = getClangStripDependencyFileAdjuster());
 228
 229 /// Utility to run a FrontendAction in a single clang invocation.
 230 class ToolInvocation {
 231 public:
 232   /// Create a tool invocation.
 233   ///
 234   /// \param CommandLine The command line arguments to clang. Note that clang
 235   /// uses its binary name (CommandLine[0]) to locate its builtin headers.
 236   /// Callers have to ensure that they are installed in a compatible location
 237   /// (see clang driver implementation) or mapped in via mapVirtualFile.
 238   /// \param FAction The action to be executed.
 239   /// \param Files The FileManager used for the execution. Class does not take
 240   /// ownership.
 241   /// \param PCHContainerOps The PCHContainerOperations for loading and creating
 242   /// clang modules.
 243   ToolInvocation(std::vector<std::string> CommandLine,
 244                  std::unique_ptr<FrontendAction> FAction, FileManager *Files,
 245                  std::shared_ptr<PCHContainerOperations> PCHContainerOps =
 246                      std::make_shared<PCHContainerOperations>());
 247
 248   /// Create a tool invocation.
 249   ///
 250   /// \param CommandLine The command line arguments to clang.
 251   /// \param Action The action to be executed.
 252   /// \param Files The FileManager used for the execution.
 253   /// \param PCHContainerOps The PCHContainerOperations for loading and creating
 254   /// clang modules.
 255   ToolInvocation(std::vector<std::string> CommandLine, ToolAction *Action,
 256                  FileManager *Files,
 257                  std::shared_ptr<PCHContainerOperations> PCHContainerOps);
 258
 259   ~ToolInvocation();
 260
 261   /// Set a \c DiagnosticConsumer to use during parsing.
 262   void setDiagnosticConsumer(DiagnosticConsumer *DiagConsumer) {
 263     this->DiagConsumer = DiagConsumer;
 264   }
 265
 266   /// Map a virtual file to be used while running the tool.
 267   ///
 268   /// \param FilePath The path at which the content will be mapped.
 269   /// \param Content A null terminated buffer of the file's content.
 270   // FIXME: remove this when all users have migrated!
 271   void mapVirtualFile(StringRef FilePath, StringRef Content);
 272
 273   /// Run the clang invocation.
 274   ///
 275   /// \returns True if there were no errors during execution.
 276   bool run();
 277
 278  private:
 279   void addFileMappingsTo(SourceManager &SourceManager);
 280
 281   bool runInvocation(const char *BinaryName,
 282                      driver::Compilation *Compilation,
 283                      std::shared_ptr<CompilerInvocation> Invocation,
 284                      std::shared_ptr<PCHContainerOperations> PCHContainerOps);
 285
 286   std::vector<std::string> CommandLine;
 287   ToolAction *Action;
 288   bool OwnsAction;
 289   FileManager *Files;
 290   std::shared_ptr<PCHContainerOperations> PCHContainerOps;
 291   // Maps <file name> -> <file content>.
 292   llvm::StringMap<StringRef> MappedFileContents;
 293   DiagnosticConsumer *DiagConsumer = nullptr;
 294 };
 295
 296 /// Utility to run a FrontendAction over a set of files.
 297 ///
 298 /// This class is written to be usable for command line utilities.
 299 /// By default the class uses ClangSyntaxOnlyAdjuster to modify
 300 /// command line arguments before the arguments are used to run
 301 /// a frontend action. One could install an additional command line
 302 /// arguments adjuster by calling the appendArgumentsAdjuster() method.
 303 class ClangTool {
 304 public:
 305   /// Constructs a clang tool to run over a list of files.
 306   ///
 307   /// \param Compilations The CompilationDatabase which contains the compile
 308   ///        command lines for the given source paths.
 309   /// \param SourcePaths The source files to run over. If a source files is
 310   ///        not found in Compilations, it is skipped.
 311   /// \param PCHContainerOps The PCHContainerOperations for loading and creating
 312   /// clang modules.
 313   /// \param BaseFS VFS used for all underlying file accesses when running the
 314   /// tool.
 315   /// \param Files The file manager to use for underlying file operations when
 316   /// running the tool.
 317   ClangTool(const CompilationDatabase &Compilations,
 318             ArrayRef<std::string> SourcePaths,
 319             std::shared_ptr<PCHContainerOperations> PCHContainerOps =
 320                 std::make_shared<PCHContainerOperations>(),
 321             IntrusiveRefCntPtr<llvm::vfs::FileSystem> BaseFS =
 322                 llvm::vfs::getRealFileSystem(),
 323             IntrusiveRefCntPtr<FileManager> Files = nullptr);
 324
 325   ~ClangTool();
 326
 327   /// Set a \c DiagnosticConsumer to use during parsing.
 328   void setDiagnosticConsumer(DiagnosticConsumer *DiagConsumer) {
 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   /// Sets whether working directory should be restored after calling run(). By
 360   /// default, working directory is restored. However, it could be useful to
 361   /// turn this off when running on multiple threads to avoid the raciness.
 362   void setRestoreWorkingDir(bool RestoreCWD);
 363
 364   /// Sets whether an error message should be printed out if an action fails. By
 365   /// default, if an action fails, a message is printed out to stderr.
 366   void setPrintErrorMessage(bool PrintErrorMessage);
 367
 368   /// Returns the file manager used in the tool.
 369   ///
 370   /// The file manager is shared between all translation units.
 371   FileManager &getFiles() { return *Files; }
 372
 373   llvm::ArrayRef<std::string> getSourcePaths() const { return SourcePaths; }
 374
 375 private:
 376   const CompilationDatabase &Compilations;
 377   std::vector<std::string> SourcePaths;
 378   std::shared_ptr<PCHContainerOperations> PCHContainerOps;
 379
 380   llvm::IntrusiveRefCntPtr<llvm::vfs::OverlayFileSystem> OverlayFileSystem;
 381   llvm::IntrusiveRefCntPtr<llvm::vfs::InMemoryFileSystem> InMemoryFileSystem;
 382   llvm::IntrusiveRefCntPtr<FileManager> Files;
 383
 384   // Contains a list of pairs (<file name>, <file content>).
 385   std::vector<std::pair<StringRef, StringRef>> MappedFileContents;
 386
 387   llvm::StringSet<> SeenWorkingDirectories;
 388
 389   ArgumentsAdjuster ArgsAdjuster;
 390
 391   DiagnosticConsumer *DiagConsumer = nullptr;
 392
 393   bool RestoreCWD = true;
 394   bool PrintErrorMessage = true;
 395 };
 396
 397 template <typename T>
 398 std::unique_ptr<FrontendActionFactory> newFrontendActionFactory() {
 399   class SimpleFrontendActionFactory : public FrontendActionFactory {
 400   public:
 401     std::unique_ptr<FrontendAction> create() override {
 402       return std::make_unique<T>();
 403     }
 404   };
 405
 406   return std::unique_ptr<FrontendActionFactory>(
 407       new SimpleFrontendActionFactory);
 408 }
 409
 410 template <typename FactoryT>
 411 inline std::unique_ptr<FrontendActionFactory> newFrontendActionFactory(
 412     FactoryT *ConsumerFactory, SourceFileCallbacks *Callbacks) {
 413   class FrontendActionFactoryAdapter : public FrontendActionFactory {
 414   public:
 415     explicit FrontendActionFactoryAdapter(FactoryT *ConsumerFactory,
 416                                           SourceFileCallbacks *Callbacks)
 417         : ConsumerFactory(ConsumerFactory), Callbacks(Callbacks) {}
 418
 419     std::unique_ptr<FrontendAction> create() override {
 420       return std::make_unique<ConsumerFactoryAdaptor>(ConsumerFactory,
 421                                                       Callbacks);
 422     }
 423
 424   private:
 425     class ConsumerFactoryAdaptor : public ASTFrontendAction {
 426     public:
 427       ConsumerFactoryAdaptor(FactoryT *ConsumerFactory,
 428                              SourceFileCallbacks *Callbacks)
 429           : ConsumerFactory(ConsumerFactory), Callbacks(Callbacks) {}
 430
 431       std::unique_ptr<ASTConsumer>
 432       CreateASTConsumer(CompilerInstance &, StringRef) override {
 433         return ConsumerFactory->newASTConsumer();
 434       }
 435
 436     protected:
 437       bool BeginSourceFileAction(CompilerInstance &CI) override {
 438         if (!ASTFrontendAction::BeginSourceFileAction(CI))
 439           return false;
 440         if (Callbacks)
 441           return Callbacks->handleBeginSource(CI);
 442         return true;
 443       }
 444
 445       void EndSourceFileAction() override {
 446         if (Callbacks)
 447           Callbacks->handleEndSource();
 448         ASTFrontendAction::EndSourceFileAction();
 449       }
 450
 451     private:
 452       FactoryT *ConsumerFactory;
 453       SourceFileCallbacks *Callbacks;
 454     };
 455     FactoryT *ConsumerFactory;
 456     SourceFileCallbacks *Callbacks;
 457   };
 458
 459   return std::unique_ptr<FrontendActionFactory>(
 460       new FrontendActionFactoryAdapter(ConsumerFactory, Callbacks));
 461 }
 462
 463 /// Returns the absolute path of \c File, by prepending it with
 464 /// the current directory if \c File is not absolute.
 465 ///
 466 /// Otherwise returns \c File.
 467 /// If 'File' starts with "./", the returned path will not contain the "./".
 468 /// Otherwise, the returned path will contain the literal path-concatenation of
 469 /// the current directory and \c File.
 470 ///
 471 /// The difference to llvm::sys::fs::make_absolute is the canonicalization this
 472 /// does by removing "./" and computing native paths.
 473 ///
 474 /// \param File Either an absolute or relative path.
 475 std::string getAbsolutePath(StringRef File);
 476
 477 /// An overload of getAbsolutePath that works over the provided \p FS.
 478 llvm::Expected<std::string> getAbsolutePath(llvm::vfs::FileSystem &FS,
 479                                             StringRef File);
 480
 481 /// Changes CommandLine to contain implicit flags that would have been
 482 /// defined had the compiler driver been invoked through the path InvokedAs.
 483 ///
 484 /// For example, when called with \c InvokedAs set to `i686-linux-android-g++`,
 485 /// the arguments '-target', 'i686-linux-android`, `--driver-mode=g++` will
 486 /// be inserted after the first argument in \c CommandLine.
 487 ///
 488 /// This function will not add new `-target` or `--driver-mode` flags if they
 489 /// are already present in `CommandLine` (even if they have different settings
 490 /// than would have been inserted).
 491 ///
 492 /// \pre `llvm::InitializeAllTargets()` has been called.
 493 ///
 494 /// \param CommandLine the command line used to invoke the compiler driver or
 495 /// Clang tool, including the path to the executable as \c CommandLine[0].
 496 /// \param InvokedAs the path to the driver used to infer implicit flags.
 497 ///
 498 /// \note This will not set \c CommandLine[0] to \c InvokedAs. The tooling
 499 /// infrastructure expects that CommandLine[0] is a tool path relative to which
 500 /// the builtin headers can be found.
 501 void addTargetAndModeForProgramName(std::vector<std::string> &CommandLine,
 502                                     StringRef InvokedAs);
 503
 504 /// Creates a \c CompilerInvocation.
 505 CompilerInvocation *newInvocation(DiagnosticsEngine *Diagnostics,
 506                                   const llvm::opt::ArgStringList &CC1Args);
 507
 508 } // namespace tooling
 509
 510 } // namespace clang
 511
 512 #endif // LLVM_CLANG_TOOLING_TOOLING_H