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_COMPILATIONDATABASE_H 29 #define LLVM_CLANG_TOOLING_COMPILATIONDATABASE_H 30 31 #include "clang/Basic/LLVM.h" 32 #include "llvm/ADT/ArrayRef.h" 33 #include "llvm/ADT/StringRef.h" 34 #include "llvm/ADT/Twine.h" 35 #include <memory> 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, Twine Filename, 46 std::vector<std::string> CommandLine, Twine Output) 47 : Directory(Directory.str()), 48 Filename(Filename.str()), 49 CommandLine(std::move(CommandLine)), 50 Output(Output.str()){} 51 52 /// \brief The working directory the command was executed from. 53 std::string Directory; 54 55 /// The source file associated with the command. 56 std::string Filename; 57 58 /// \brief The command line that was executed. 59 std::vector<std::string> CommandLine; 60 61 /// The output file associated with the command. 62 std::string Output; 63 }; 64 65 /// \brief Interface for compilation databases. 66 /// 67 /// A compilation database allows the user to retrieve compile command lines 68 /// for the files in a project. 69 /// 70 /// Many implementations are enumerable, allowing all command lines to be 71 /// retrieved. These can be used to run clang tools over a subset of the files 72 /// in a project. 73 class CompilationDatabase { 74 public: 75 virtual ~CompilationDatabase(); 76 77 /// \brief Loads a compilation database from a build directory. 78 /// 79 /// Looks at the specified 'BuildDirectory' and creates a compilation database 80 /// that allows to query compile commands for source files in the 81 /// corresponding source tree. 82 /// 83 /// Returns NULL and sets ErrorMessage if we were not able to build up a 84 /// compilation database for the build directory. 85 /// 86 /// FIXME: Currently only supports JSON compilation databases, which 87 /// are named 'compile_commands.json' in the given directory. Extend this 88 /// for other build types (like ninja build files). 89 static std::unique_ptr<CompilationDatabase> 90 loadFromDirectory(StringRef BuildDirectory, std::string &ErrorMessage); 91 92 /// \brief Tries to detect a compilation database location and load it. 93 /// 94 /// Looks for a compilation database in all parent paths of file 'SourceFile' 95 /// by calling loadFromDirectory. 96 static std::unique_ptr<CompilationDatabase> 97 autoDetectFromSource(StringRef SourceFile, std::string &ErrorMessage); 98 99 /// \brief Tries to detect a compilation database location and load it. 100 /// 101 /// Looks for a compilation database in directory 'SourceDir' and all 102 /// its parent paths by calling loadFromDirectory. 103 static std::unique_ptr<CompilationDatabase> 104 autoDetectFromDirectory(StringRef SourceDir, std::string &ErrorMessage); 105 106 /// \brief Returns all compile commands in which the specified file was 107 /// compiled. 108 /// 109 /// This includes compile commands that span multiple source files. 110 /// For example, consider a project with the following compilations: 111 /// $ clang++ -o test a.cc b.cc t.cc 112 /// $ clang++ -o production a.cc b.cc -DPRODUCTION 113 /// A compilation database representing the project would return both command 114 /// lines for a.cc and b.cc and only the first command line for t.cc. 115 virtual std::vector<CompileCommand> getCompileCommands( 116 StringRef FilePath) const = 0; 117 118 /// \brief Returns the list of all files available in the compilation database. 119 /// 120 /// By default, returns nothing. Implementations should override this if they 121 /// can enumerate their source files. 122 virtual std::vector<std::string> getAllFiles() const { return {}; } 123 124 /// \brief Returns all compile commands for all the files in the compilation 125 /// database. 126 /// 127 /// FIXME: Add a layer in Tooling that provides an interface to run a tool 128 /// over all files in a compilation database. Not all build systems have the 129 /// ability to provide a feasible implementation for \c getAllCompileCommands. 130 /// 131 /// By default, this is implemented in terms of getAllFiles() and 132 /// getCompileCommands(). Subclasses may override this for efficiency. 133 virtual std::vector<CompileCommand> getAllCompileCommands() const; 134 }; 135 136 /// \brief Interface for compilation database plugins. 137 /// 138 /// A compilation database plugin allows the user to register custom compilation 139 /// databases that are picked up as compilation database if the corresponding 140 /// library is linked in. To register a plugin, declare a static variable like: 141 /// 142 /// \code 143 /// static CompilationDatabasePluginRegistry::Add<MyDatabasePlugin> 144 /// X("my-compilation-database", "Reads my own compilation database"); 145 /// \endcode 146 class CompilationDatabasePlugin { 147 public: 148 virtual ~CompilationDatabasePlugin(); 149 150 /// \brief Loads a compilation database from a build directory. 151 /// 152 /// \see CompilationDatabase::loadFromDirectory(). 153 virtual std::unique_ptr<CompilationDatabase> 154 loadFromDirectory(StringRef Directory, std::string &ErrorMessage) = 0; 155 }; 156 157 /// \brief A compilation database that returns a single compile command line. 158 /// 159 /// Useful when we want a tool to behave more like a compiler invocation. 160 /// This compilation database is not enumerable: getAllFiles() returns {}. 161 class FixedCompilationDatabase : public CompilationDatabase { 162 public: 163 /// \brief Creates a FixedCompilationDatabase from the arguments after "--". 164 /// 165 /// Parses the given command line for "--". If "--" is found, the rest of 166 /// the arguments will make up the command line in the returned 167 /// FixedCompilationDatabase. 168 /// The arguments after "--" must not include positional parameters or the 169 /// argv[0] of the tool. Those will be added by the FixedCompilationDatabase 170 /// when a CompileCommand is requested. The argv[0] of the returned command 171 /// line will be "clang-tool". 172 /// 173 /// Returns NULL in case "--" is not found. 174 /// 175 /// The argument list is meant to be compatible with normal llvm command line 176 /// parsing in main methods. 177 /// int main(int argc, char **argv) { 178 /// std::unique_ptr<FixedCompilationDatabase> Compilations( 179 /// FixedCompilationDatabase::loadFromCommandLine(argc, argv)); 180 /// cl::ParseCommandLineOptions(argc, argv); 181 /// ... 182 /// } 183 /// 184 /// \param Argc The number of command line arguments - will be changed to 185 /// the number of arguments before "--", if "--" was found in the argument 186 /// list. 187 /// \param Argv Points to the command line arguments. 188 /// \param ErrorMsg Contains error text if the function returns null pointer. 189 /// \param Directory The base directory used in the FixedCompilationDatabase. 190 static std::unique_ptr<FixedCompilationDatabase> loadFromCommandLine( 191 int &Argc, const char *const *Argv, std::string &ErrorMsg, 192 Twine Directory = "."); 193 194 /// Reads flags from the given file, one-per line. 195 /// Returns nullptr and sets ErrorMessage if we can't read the file. 196 static std::unique_ptr<FixedCompilationDatabase> 197 loadFromFile(StringRef Path, std::string &ErrorMsg); 198 199 /// \brief Constructs a compilation data base from a specified directory 200 /// and command line. 201 FixedCompilationDatabase(Twine Directory, ArrayRef<std::string> CommandLine); 202 203 /// \brief Returns the given compile command. 204 /// 205 /// Will always return a vector with one entry that contains the directory 206 /// and command line specified at construction with "clang-tool" as argv[0] 207 /// and 'FilePath' as positional argument. 208 std::vector<CompileCommand> 209 getCompileCommands(StringRef FilePath) const override; 210 211 private: 212 /// This is built up to contain a single entry vector to be returned from 213 /// getCompileCommands after adding the positional argument. 214 std::vector<CompileCommand> CompileCommands; 215 }; 216 217 } // end namespace tooling 218 } // end namespace clang 219 220 #endif 221