Adds a tooling library.

Provides an API to run clang tools (FrontendActions) as standalone tools,
or repeatedly in-memory in a process. This is useful for unit-testing,
map-reduce style applications, source transformation daemons or command line
tools.

The ability to run over multiple translation units with different command
line arguments enables building up refactoring tools that need to apply
transformations across translation unit boundaries.

See tools/clang-check/ClangCheck.cpp for an example.



git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@154008 91177308-0d34-0410-b5e6-96231b3b80d8

2 files changed, 377 insertions, 0 deletions

diff --git a/include/clang/Tooling/CompilationDatabase.h b/include/clang/Tooling/CompilationDatabase.h
new file mode 100644
index 0000000000..3430320b51
--- /dev/null
+++ b/include/clang/Tooling/CompilationDatabase.h
@@ -0,0 +1,164 @@
+//===--- CompilationDatabase.h - --------------------------------*- C++ -*-===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+//
+//  This file provides an interface and multiple implementations for
+//  CompilationDatabases.
+//
+//  While C++ refactoring and analysis tools are not compilers, and thus
+//  don't run as part of the build system, they need the exact information
+//  of a build in order to be able to correctly understand the C++ code of
+//  the project. This information is provided via the CompilationDatabase
+//  interface.
+//
+//  To create a CompilationDatabase from a build directory one can call
+//  CompilationDatabase::loadFromDirectory(), which deduces the correct
+//  compilation database from the root of the build tree.
+//
+//  See the concrete subclasses of CompilationDatabase for currently supported
+//  formats.
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef LLVM_CLANG_TOOLING_COMPILATION_DATABASE_H
+#define LLVM_CLANG_TOOLING_COMPILATION_DATABASE_H
+
+#include "clang/Basic/LLVM.h"
+#include "llvm/ADT/ArrayRef.h"
+#include "llvm/ADT/OwningPtr.h"
+#include "llvm/ADT/StringMap.h"
+#include "llvm/ADT/StringRef.h"
+#include "llvm/Support/MemoryBuffer.h"
+#include <string>
+#include <vector>
+
+namespace llvm {
+class MemoryBuffer;
+} // end namespace llvm
+
+namespace clang {
+namespace tooling {
+
+/// \brief Specifies the working directory and command of a compilation.
+struct CompileCommand {
+  CompileCommand() {}
+  CompileCommand(StringRef Directory, ArrayRef<std::string> CommandLine)
+    : Directory(Directory), CommandLine(CommandLine) {}
+
+  /// \brief The working directory the command was executed from.
+  std::string Directory;
+
+  /// \brief The command line that was executed.
+  std::vector<std::string> CommandLine;
+};
+
+/// \brief Interface for compilation databases.
+///
+/// A compilation database allows the user to retrieve all compile command lines
+/// that a specified file is compiled with in a project.
+/// The retrieved compile command lines can be used to run clang tools over
+/// a subset of the files in a project.
+class CompilationDatabase {
+public:
+  virtual ~CompilationDatabase();
+
+  /// \brief Loads a compilation database from a build directory.
+  ///
+  /// Looks at the specified 'BuildDirectory' and creates a compilation database
+  /// that allows to query compile commands for source files in the
+  /// corresponding source tree.
+  ///
+  /// Returns NULL and sets ErrorMessage if we were not able to build up a
+  /// compilation database for the build directory.
+  ///
+  /// FIXME: Currently only supports JSON compilation databases, which
+  /// are named 'compile_commands.json' in the given directory. Extend this
+  /// for other build types (like ninja build files).
+  static CompilationDatabase *loadFromDirectory(StringRef BuildDirectory,
+                                                std::string &ErrorMessage);
+
+  /// \brief Returns all compile commands in which the specified file was
+  /// compiled.
+  ///
+  /// This includes compile comamnds that span multiple source files.
+  /// For example, consider a project with the following compilations:
+  /// $ clang++ -o test a.cc b.cc t.cc
+  /// $ clang++ -o production a.cc b.cc -DPRODUCTION
+  /// A compilation database representing the project would return both command
+  /// lines for a.cc and b.cc and only the first command line for t.cc.
+  virtual std::vector<CompileCommand> getCompileCommands(
+    StringRef FilePath) const = 0;
+};
+
+/// \brief A JSON based compilation database.
+///
+/// JSON compilation database files must contain a list of JSON objects which
+/// provide the command lines in the attributes 'directory', 'command' and
+/// 'file':
+/// [
+///   { "directory": "<working directory of the compile>",
+///     "command": "<compile command line>",
+///     "file": "<path to source file>"
+///   },
+///   ...
+/// ]
+/// Each object entry defines one compile action. The specified file is
+/// considered to be the main source file for the translation unit.
+///
+/// JSON compilation databases can for example be generated in CMake projects
+/// by setting the flag -DCMAKE_EXPORT_COMPILE_COMMANDS.
+class JSONCompilationDatabase : public CompilationDatabase {
+public:
+
+  /// \brief Loads a JSON compilation database from the specified file.
+  ///
+  /// Returns NULL and sets ErrorMessage if the database could not be
+  /// loaded from the given file.
+  static JSONCompilationDatabase *loadFromFile(StringRef FilePath,
+                                               std::string &ErrorMessage);
+
+  /// \brief Loads a JSON compilation database from a data buffer.
+  ///
+  /// Returns NULL and sets ErrorMessage if the database could not be loaded.
+  static JSONCompilationDatabase *loadFromBuffer(StringRef DatabaseString,
+                                                 std::string &ErrorMessage);
+
+  /// \brief Returns all compile comamnds in which the specified file was
+  /// compiled.
+  ///
+  /// FIXME: Currently FilePath must be an absolute path inside the
+  /// source directory which does not have symlinks resolved.
+  virtual std::vector<CompileCommand> getCompileCommands(
+    StringRef FilePath) const;
+
+private:
+  /// \brief Constructs a JSON compilation database on a memory buffer.
+  JSONCompilationDatabase(llvm::MemoryBuffer *Database)
+    : Database(Database) {}
+
+  /// \brief Parses the database file and creates the index.
+  ///
+  /// Returns whether parsing succeeded. Sets ErrorMessage if parsing
+  /// failed.
+  bool parse(std::string &ErrorMessage);
+
+  // Tuple (directory, commandline) where 'commandline' is a JSON escaped bash
+  // escaped command line.
+  typedef std::pair<StringRef, StringRef> CompileCommandRef;
+
+  // Maps file paths to the compile command lines for that file.
+  llvm::StringMap< std::vector<CompileCommandRef> > IndexByFile;
+
+  llvm::OwningPtr<llvm::MemoryBuffer> Database;
+};
+
+} // end namespace tooling
+} // end namespace clang
+
+#endif // LLVM_CLANG_TOOLING_COMPILATION_DATABASE_H
+
diff --git a/include/clang/Tooling/Tooling.h b/include/clang/Tooling/Tooling.h
new file mode 100644
index 0000000000..868eae3068
--- /dev/null
+++ b/include/clang/Tooling/Tooling.h
@@ -0,0 +1,213 @@
+//===--- Tooling.h - Framework for standalone Clang tools -------*- C++ -*-===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+//
+//  This file implements functions to run clang tools standalone instead
+//  of running them as a plugin.
+//
+//  A ClangTool is initialized with a CompilationDatabase and a set of files
+//  to run over. The tool will then run a user-specified FrontendAction over
+//  all TUs in which the given files are compiled.
+//
+//  It is also possible to run a FrontendAction over a snippet of code by
+//  calling runSyntaxOnlyToolOnCode, which is useful for unit testing.
+//
+//  Applications that need more fine grained control over how to run
+//  multiple FrontendActions over code can use ToolInvocation.
+//
+//  Example tools:
+//  - running clang -fsyntax-only over source code from an editor to get
+//    fast syntax checks
+//  - running match/replace tools over C++ code
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef LLVM_CLANG_TOOLING_TOOLING_H
+#define LLVM_CLANG_TOOLING_TOOLING_H
+
+#include "llvm/ADT/StringMap.h"
+#include "llvm/ADT/Twine.h"
+#include "clang/Basic/FileManager.h"
+#include "clang/Basic/LLVM.h"
+#include "clang/Driver/Util.h"
+#include <string>
+#include <vector>
+
+namespace clang {
+
+namespace driver {
+class Compilation;
+} // end namespace driver
+
+class CompilerInvocation;
+class SourceManager;
+class FrontendAction;
+
+namespace tooling {
+
+class CompilationDatabase;
+
+/// \brief Interface to generate clang::FrontendActions.
+class FrontendActionFactory {
+public:
+  virtual ~FrontendActionFactory();
+
+  /// \brief Returns a new clang::FrontendAction.
+  ///
+  /// The caller takes ownership of the returned action.
+  virtual clang::FrontendAction *create() = 0;
+};
+
+/// \brief Returns a new FrontendActionFactory for a given type.
+///
+/// T must extend clang::FrontendAction.
+///
+/// Example:
+/// FrontendActionFactory *Factory =
+///   newFrontendActionFactory<clang::SyntaxOnlyAction>();
+template <typename T>
+FrontendActionFactory *newFrontendActionFactory();
+
+/// \brief Returns a new FrontendActionFactory for any type that provides an
+/// implementation of newFrontendAction().
+///
+/// FactoryT must implement: FrontendAction *newFrontendAction().
+///
+/// Example:
+/// struct ProvidesFrontendActions {
+///   FrontendAction *newFrontendAction();
+/// } Factory;
+/// FrontendActionFactory *FactoryAdapter =
+///   newFrontendActionFactory(&Factory);
+template <typename FactoryT>
+FrontendActionFactory *newFrontendActionFactory(FactoryT *ActionFactory);
+
+/// \brief Runs (and deletes) the tool on 'Code' with the -fsyntax-only flag.
+///
+/// \param ToolAction The action to run over the code.
+/// \param Code C++ code.
+/// \param FileName The file name which 'Code' will be mapped as.
+///
+/// \return - True if 'ToolAction' was successfully executed.
+bool runToolOnCode(clang::FrontendAction *ToolAction, const Twine &Code,
+                   const Twine &FileName = "input.cc");
+
+/// \brief Utility to run a FrontendAction in a single clang invocation.
+class ToolInvocation {
+ public:
+  /// \brief Create a tool invocation.
+  ///
+  /// \param CommandLine The command line arguments to clang.
+  /// \param ToolAction The action to be executed. Class takes ownership.
+  /// \param Files The FileManager used for the execution. Class does not take
+  /// ownership.
+  ToolInvocation(ArrayRef<std::string> CommandLine, FrontendAction *ToolAction,
+                 FileManager *Files);
+
+  /// \brief Map a virtual file to be used while running the tool.
+  ///
+  /// \param FilePath The path at which the content will be mapped.
+  /// \param Content A null terminated buffer of the file's content.
+  void mapVirtualFile(StringRef FilePath, StringRef Content);
+
+  /// \brief Run the clang invocation.
+  ///
+  /// \returns True if there were no errors during execution.
+  bool run();
+
+ private:
+  void addFileMappingsTo(SourceManager &SourceManager);
+
+  bool runInvocation(const char *BinaryName,
+                     clang::driver::Compilation *Compilation,
+                     clang::CompilerInvocation *Invocation,
+                     const clang::driver::ArgStringList &CC1Args,
+                     clang::FrontendAction *ToolAction);
+
+  std::vector<std::string> CommandLine;
+  llvm::OwningPtr<FrontendAction> ToolAction;
+  FileManager *Files;
+  // Maps <file name> -> <file content>.
+  llvm::StringMap<StringRef> MappedFileContents;
+};
+
+/// \brief Utility to run a FrontendAction over a set of files.
+///
+/// This class is written to be usable for command line utilities.
+class ClangTool {
+ public:
+  /// \brief Constructs a clang tool to run over a list of files.
+  ///
+  /// \param Compilations The CompilationDatabase which contains the compile
+  ///        command lines for the given source paths.
+  /// \param SourcePaths The source files to run over. If a source files is
+  ///        not found in Compilations, it is skipped.
+  ClangTool(const CompilationDatabase &Compilations,
+            ArrayRef<std::string> SourcePaths);
+
+  /// \brief Map a virtual file to be used while running the tool.
+  ///
+  /// \param FilePath The path at which the content will be mapped.
+  /// \param Content A null terminated buffer of the file's content.
+  void mapVirtualFile(StringRef FilePath, StringRef Content);
+
+  /// Runs a frontend action over all files specified in the command line.
+  ///
+  /// \param ActionFactory Factory generating the frontend actions. The function
+  /// takes ownership of this parameter. A new action is generated for every
+  /// processed translation unit.
+  int run(FrontendActionFactory *ActionFactory);
+
+  /// \brief Returns the file manager used in the tool.
+  ///
+  /// The file manager is shared between all translation units.
+  FileManager &getFiles() { return Files; }
+
+ private:
+  // We store command lines as pair (file name, command line).
+  typedef std::pair< std::string, std::vector<std::string> > CommandLine;
+  std::vector<CommandLine> CommandLines;
+
+  FileManager Files;
+  // Contains a list of pairs (<file name>, <file content>).
+  std::vector< std::pair<StringRef, StringRef> > MappedFileContents;
+};
+
+template <typename T>
+FrontendActionFactory *newFrontendActionFactory() {
+  class SimpleFrontendActionFactory : public FrontendActionFactory {
+  public:
+    virtual clang::FrontendAction *create() { return new T; }
+  };
+
+  return new SimpleFrontendActionFactory;
+}
+
+template <typename FactoryT>
+FrontendActionFactory *newFrontendActionFactory(FactoryT *ActionFactory) {
+  class FrontendActionFactoryAdapter : public FrontendActionFactory {
+  public:
+    explicit FrontendActionFactoryAdapter(FactoryT *ActionFactory)
+      : ActionFactory(ActionFactory) {}
+
+    virtual clang::FrontendAction *create() {
+      return ActionFactory->newFrontendAction();
+    }
+
+  private:
+    FactoryT *ActionFactory;
+  };
+
+  return new FrontendActionFactoryAdapter(ActionFactory);
+}
+
+} // end namespace tooling
+} // end namespace clang
+
+#endif // LLVM_CLANG_TOOLING_TOOLING_H
+