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

   1 //===--- CompilationDatabase.h - --------------------------------*- 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 provides an interface and multiple implementations for
  11 //  CompilationDatabases.
  12 //
  13 //  While C++ refactoring and analysis tools are not compilers, and thus
  14 //  don't run as part of the build system, they need the exact information
  15 //  of a build in order to be able to correctly understand the C++ code of
  16 //  the project. This information is provided via the CompilationDatabase
  17 //  interface.
  18 //
  19 //  To create a CompilationDatabase from a build directory one can call
  20 //  CompilationDatabase::loadFromDirectory(), which deduces the correct
  21 //  compilation database from the root of the build tree.
  22 //
  23 //  See the concrete subclasses of CompilationDatabase for currently supported
  24 //  formats.
  25 //
  26 //===----------------------------------------------------------------------===//
  27
  28 #ifndef LLVM_CLANG_TOOLING_COMPILATION_DATABASE_H
  29 #define LLVM_CLANG_TOOLING_COMPILATION_DATABASE_H
  30
  31 #include "clang/Basic/LLVM.h"
  32 #include "llvm/ADT/ArrayRef.h"
  33 #include "llvm/ADT/OwningPtr.h"
  34 #include "llvm/ADT/StringRef.h"
  35 #include "llvm/ADT/Twine.h"
  36 #include <string>
  37 #include <vector>
  38
  39 namespace clang {
  40 namespace tooling {
  41
  42 /// \brief Specifies the working directory and command of a compilation.
  43 struct CompileCommand {
  44   CompileCommand() {}
  45   CompileCommand(Twine Directory, ArrayRef<std::string> CommandLine)
  46     : Directory(Directory.str()), CommandLine(CommandLine) {}
  47
  48   /// \brief The working directory the command was executed from.
  49   std::string Directory;
  50
  51   /// \brief The command line that was executed.
  52   std::vector<std::string> CommandLine;
  53 };
  54
  55 /// \brief Interface for compilation databases.
  56 ///
  57 /// A compilation database allows the user to retrieve all compile command lines
  58 /// that a specified file is compiled with in a project.
  59 /// The retrieved compile command lines can be used to run clang tools over
  60 /// a subset of the files in a project.
  61 class CompilationDatabase {
  62 public:
  63   virtual ~CompilationDatabase();
  64
  65   /// \brief Loads a compilation database from a build directory.
  66   ///
  67   /// Looks at the specified 'BuildDirectory' and creates a compilation database
  68   /// that allows to query compile commands for source files in the
  69   /// corresponding source tree.
  70   ///
  71   /// Returns NULL and sets ErrorMessage if we were not able to build up a
  72   /// compilation database for the build directory.
  73   ///
  74   /// FIXME: Currently only supports JSON compilation databases, which
  75   /// are named 'compile_commands.json' in the given directory. Extend this
  76   /// for other build types (like ninja build files).
  77   static CompilationDatabase *loadFromDirectory(StringRef BuildDirectory,
  78                                                 std::string &ErrorMessage);
  79
  80   /// \brief Tries to detect a compilation database location and load it.
  81   ///
  82   /// Looks for a compilation database in all parent paths of file 'SourceFile'
  83   /// by calling loadFromDirectory.
  84   static CompilationDatabase *autoDetectFromSource(StringRef SourceFile,
  85                                                    std::string &ErrorMessage);
  86
  87   /// \brief Tries to detect a compilation database location and load it.
  88   ///
  89   /// Looks for a compilation database in directory 'SourceDir' and all
  90   /// its parent paths by calling loadFromDirectory.
  91   static CompilationDatabase *autoDetectFromDirectory(StringRef SourceDir,
  92                                                       std::string &ErrorMessage);
  93
  94   /// \brief Returns all compile commands in which the specified file was
  95   /// compiled.
  96   ///
  97   /// This includes compile comamnds that span multiple source files.
  98   /// For example, consider a project with the following compilations:
  99   /// $ clang++ -o test a.cc b.cc t.cc
 100   /// $ clang++ -o production a.cc b.cc -DPRODUCTION
 101   /// A compilation database representing the project would return both command
 102   /// lines for a.cc and b.cc and only the first command line for t.cc.
 103   virtual std::vector<CompileCommand> getCompileCommands(
 104     StringRef FilePath) const = 0;
 105
 106   /// \brief Returns the list of all files available in the compilation database.
 107   virtual std::vector<std::string> getAllFiles() const = 0;
 108
 109   /// \brief Returns all compile commands for all the files in the compilation
 110   /// database.
 111   virtual std::vector<CompileCommand> getAllCompileCommands() const = 0;
 112 };
 113
 114 /// \brief Interface for compilation database plugins.
 115 ///
 116 /// A compilation database plugin allows the user to register custom compilation
 117 /// databases that are picked up as compilation database if the corresponding
 118 /// library is linked in. To register a plugin, declare a static variable like:
 119 ///
 120 /// \code
 121 /// static CompilationDatabasePluginRegistry::Add<MyDatabasePlugin>
 122 /// X("my-compilation-database", "Reads my own compilation database");
 123 /// \endcode
 124 class CompilationDatabasePlugin {
 125 public:
 126   virtual ~CompilationDatabasePlugin();
 127
 128   /// \brief Loads a compilation database from a build directory.
 129   ///
 130   /// \see CompilationDatabase::loadFromDirectory().
 131   virtual CompilationDatabase *loadFromDirectory(StringRef Directory,
 132                                                  std::string &ErrorMessage) = 0;
 133 };
 134
 135 /// \brief A compilation database that returns a single compile command line.
 136 ///
 137 /// Useful when we want a tool to behave more like a compiler invocation.
 138 class FixedCompilationDatabase : public CompilationDatabase {
 139 public:
 140   /// \brief Creates a FixedCompilationDatabase from the arguments after "--".
 141   ///
 142   /// Parses the given command line for "--". If "--" is found, the rest of
 143   /// the arguments will make up the command line in the returned
 144   /// FixedCompilationDatabase.
 145   /// The arguments after "--" must not include positional parameters or the
 146   /// argv[0] of the tool. Those will be added by the FixedCompilationDatabase
 147   /// when a CompileCommand is requested. The argv[0] of the returned command
 148   /// line will be "clang-tool".
 149   ///
 150   /// Returns NULL in case "--" is not found.
 151   ///
 152   /// The argument list is meant to be compatible with normal llvm command line
 153   /// parsing in main methods.
 154   /// int main(int argc, char **argv) {
 155   ///   OwningPtr<FixedCompilationDatabase> Compilations(
 156   ///     FixedCompilationDatabase::loadFromCommandLine(argc, argv));
 157   ///   cl::ParseCommandLineOptions(argc, argv);
 158   ///   ...
 159   /// }
 160   ///
 161   /// \param Argc The number of command line arguments - will be changed to
 162   /// the number of arguments before "--", if "--" was found in the argument
 163   /// list.
 164   /// \param Argv Points to the command line arguments.
 165   /// \param Directory The base directory used in the FixedCompilationDatabase.
 166   static FixedCompilationDatabase *loadFromCommandLine(int &Argc,
 167                                                        const char **Argv,
 168                                                        Twine Directory = ".");
 169
 170   /// \brief Constructs a compilation data base from a specified directory
 171   /// and command line.
 172   FixedCompilationDatabase(Twine Directory, ArrayRef<std::string> CommandLine);
 173
 174   /// \brief Returns the given compile command.
 175   ///
 176   /// Will always return a vector with one entry that contains the directory
 177   /// and command line specified at construction with "clang-tool" as argv[0]
 178   /// and 'FilePath' as positional argument.
 179   virtual std::vector<CompileCommand> getCompileCommands(
 180     StringRef FilePath) const;
 181
 182   /// \brief Returns the list of all files available in the compilation database.
 183   ///
 184   /// Note: This is always an empty list for the fixed compilation database.
 185   virtual std::vector<std::string> getAllFiles() const;
 186
 187   /// \brief Returns all compile commands for all the files in the compilation
 188   /// database.
 189   ///
 190   /// Note: This is always an empty list for the fixed compilation database.
 191   virtual std::vector<CompileCommand> getAllCompileCommands() const;
 192
 193 private:
 194   /// This is built up to contain a single entry vector to be returned from
 195   /// getCompileCommands after adding the positional argument.
 196   std::vector<CompileCommand> CompileCommands;
 197 };
 198
 199 } // end namespace tooling
 200 } // end namespace clang
 201
 202 #endif // LLVM_CLANG_TOOLING_COMPILATION_DATABASE_H