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