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/StringMap.h"
  35 #include "llvm/ADT/StringRef.h"
  36 #include "llvm/ADT/Twine.h"
  37 #include "llvm/Support/MemoryBuffer.h"
  38 #include "llvm/Support/SourceMgr.h"
  39 #include "llvm/Support/YAMLParser.h"
  40 #include <string>
  41 #include <vector>
  42
  43 namespace clang {
  44 namespace tooling {
  45
  46 /// \brief Specifies the working directory and command of a compilation.
  47 struct CompileCommand {
  48   CompileCommand() {}
  49   CompileCommand(Twine Directory, ArrayRef<std::string> CommandLine)
  50     : Directory(Directory.str()), CommandLine(CommandLine) {}
  51
  52   /// \brief The working directory the command was executed from.
  53   std::string Directory;
  54
  55   /// \brief The command line that was executed.
  56   std::vector<std::string> CommandLine;
  57 };
  58
  59 /// \brief Interface for compilation databases.
  60 ///
  61 /// A compilation database allows the user to retrieve all compile command lines
  62 /// that a specified file is compiled with in a project.
  63 /// The retrieved compile command lines can be used to run clang tools over
  64 /// a subset of the files in a project.
  65 class CompilationDatabase {
  66 public:
  67   virtual ~CompilationDatabase();
  68
  69   /// \brief Loads a compilation database from a build directory.
  70   ///
  71   /// Looks at the specified 'BuildDirectory' and creates a compilation database
  72   /// that allows to query compile commands for source files in the
  73   /// corresponding source tree.
  74   ///
  75   /// Returns NULL and sets ErrorMessage if we were not able to build up a
  76   /// compilation database for the build directory.
  77   ///
  78   /// FIXME: Currently only supports JSON compilation databases, which
  79   /// are named 'compile_commands.json' in the given directory. Extend this
  80   /// for other build types (like ninja build files).
  81   static CompilationDatabase *loadFromDirectory(StringRef BuildDirectory,
  82                                                 std::string &ErrorMessage);
  83
  84   /// \brief Returns all compile commands in which the specified file was
  85   /// compiled.
  86   ///
  87   /// This includes compile comamnds that span multiple source files.
  88   /// For example, consider a project with the following compilations:
  89   /// $ clang++ -o test a.cc b.cc t.cc
  90   /// $ clang++ -o production a.cc b.cc -DPRODUCTION
  91   /// A compilation database representing the project would return both command
  92   /// lines for a.cc and b.cc and only the first command line for t.cc.
  93   virtual std::vector<CompileCommand> getCompileCommands(
  94     StringRef FilePath) const = 0;
  95 };
  96
  97 /// \brief A compilation database that returns a single compile command line.
  98 ///
  99 /// Useful when we want a tool to behave more like a compiler invocation.
 100 class FixedCompilationDatabase : public CompilationDatabase {
 101 public:
 102   /// \brief Creates a FixedCompilationDatabase from the arguments after "--".
 103   ///
 104   /// Parses the given command line for "--". If "--" is found, the rest of
 105   /// the arguments will make up the command line in the returned
 106   /// FixedCompilationDatabase.
 107   /// The arguments after "--" must not include positional parameters or the
 108   /// argv[0] of the tool. Those will be added by the FixedCompilationDatabase
 109   /// when a CompileCommand is requested. The argv[0] of the returned command
 110   /// line will be "clang-tool".
 111   ///
 112   /// Returns NULL in case "--" is not found.
 113   ///
 114   /// The argument list is meant to be compatible with normal llvm command line
 115   /// parsing in main methods.
 116   /// int main(int argc, char **argv) {
 117   ///   llvm::OwningPtr<FixedCompilationDatabase> Compilations(
 118   ///     FixedCompilationDatabase::loadFromCommandLine(argc, argv));
 119   ///   cl::ParseCommandLineOptions(argc, argv);
 120   ///   ...
 121   /// }
 122   ///
 123   /// \param Argc The number of command line arguments - will be changed to
 124   /// the number of arguments before "--", if "--" was found in the argument
 125   /// list.
 126   /// \param Argv Points to the command line arguments.
 127   /// \param Directory The base directory used in the FixedCompilationDatabase.
 128   static FixedCompilationDatabase *loadFromCommandLine(int &Argc,
 129                                                        const char **Argv,
 130                                                        Twine Directory = ".");
 131
 132   /// \brief Constructs a compilation data base from a specified directory
 133   /// and command line.
 134   FixedCompilationDatabase(Twine Directory, ArrayRef<std::string> CommandLine);
 135
 136   /// \brief Returns the given compile command.
 137   ///
 138   /// Will always return a vector with one entry that contains the directory
 139   /// and command line specified at construction with "clang-tool" as argv[0]
 140   /// and 'FilePath' as positional argument.
 141   virtual std::vector<CompileCommand> getCompileCommands(
 142     StringRef FilePath) const;
 143
 144 private:
 145   /// This is built up to contain a single entry vector to be returned from
 146   /// getCompileCommands after adding the positional argument.
 147   std::vector<CompileCommand> CompileCommands;
 148 };
 149
 150 /// \brief A JSON based compilation database.
 151 ///
 152 /// JSON compilation database files must contain a list of JSON objects which
 153 /// provide the command lines in the attributes 'directory', 'command' and
 154 /// 'file':
 155 /// [
 156 ///   { "directory": "<working directory of the compile>",
 157 ///     "command": "<compile command line>",
 158 ///     "file": "<path to source file>"
 159 ///   },
 160 ///   ...
 161 /// ]
 162 /// Each object entry defines one compile action. The specified file is
 163 /// considered to be the main source file for the translation unit.
 164 ///
 165 /// JSON compilation databases can for example be generated in CMake projects
 166 /// by setting the flag -DCMAKE_EXPORT_COMPILE_COMMANDS.
 167 class JSONCompilationDatabase : public CompilationDatabase {
 168 public:
 169   /// \brief Loads a JSON compilation database from the specified file.
 170   ///
 171   /// Returns NULL and sets ErrorMessage if the database could not be
 172   /// loaded from the given file.
 173   static JSONCompilationDatabase *loadFromFile(StringRef FilePath,
 174                                                std::string &ErrorMessage);
 175
 176   /// \brief Loads a JSON compilation database from a data buffer.
 177   ///
 178   /// Returns NULL and sets ErrorMessage if the database could not be loaded.
 179   static JSONCompilationDatabase *loadFromBuffer(StringRef DatabaseString,
 180                                                  std::string &ErrorMessage);
 181
 182   /// \brief Returns all compile comamnds in which the specified file was
 183   /// compiled.
 184   ///
 185   /// FIXME: Currently FilePath must be an absolute path inside the
 186   /// source directory which does not have symlinks resolved.
 187   virtual std::vector<CompileCommand> getCompileCommands(
 188     StringRef FilePath) const;
 189
 190 private:
 191   /// \brief Constructs a JSON compilation database on a memory buffer.
 192   JSONCompilationDatabase(llvm::MemoryBuffer *Database)
 193     : Database(Database), YAMLStream(Database->getBuffer(), SM) {}
 194
 195   /// \brief Parses the database file and creates the index.
 196   ///
 197   /// Returns whether parsing succeeded. Sets ErrorMessage if parsing
 198   /// failed.
 199   bool parse(std::string &ErrorMessage);
 200
 201   // Tuple (directory, commandline) where 'commandline' pointing to the
 202   // corresponding nodes in the YAML stream.
 203   typedef std::pair<llvm::yaml::ScalarNode*,
 204                     llvm::yaml::ScalarNode*> CompileCommandRef;
 205
 206   // Maps file paths to the compile command lines for that file.
 207   llvm::StringMap< std::vector<CompileCommandRef> > IndexByFile;
 208
 209   llvm::OwningPtr<llvm::MemoryBuffer> Database;
 210   llvm::SourceMgr SM;
 211   llvm::yaml::Stream YAMLStream;
 212 };
 213
 214 } // end namespace tooling
 215 } // end namespace clang
 216
 217 #endif // LLVM_CLANG_TOOLING_COMPILATION_DATABASE_H
 218