1234287Sdim//===--- CompilationDatabase.h - --------------------------------*- C++ -*-===// 2234287Sdim// 3234287Sdim// The LLVM Compiler Infrastructure 4234287Sdim// 5234287Sdim// This file is distributed under the University of Illinois Open Source 6234287Sdim// License. See LICENSE.TXT for details. 7234287Sdim// 8234287Sdim//===----------------------------------------------------------------------===// 9234287Sdim// 10234287Sdim// This file provides an interface and multiple implementations for 11234287Sdim// CompilationDatabases. 12234287Sdim// 13234287Sdim// While C++ refactoring and analysis tools are not compilers, and thus 14234287Sdim// don't run as part of the build system, they need the exact information 15234287Sdim// of a build in order to be able to correctly understand the C++ code of 16234287Sdim// the project. This information is provided via the CompilationDatabase 17234287Sdim// interface. 18234287Sdim// 19234287Sdim// To create a CompilationDatabase from a build directory one can call 20234287Sdim// CompilationDatabase::loadFromDirectory(), which deduces the correct 21234287Sdim// compilation database from the root of the build tree. 22234287Sdim// 23234287Sdim// See the concrete subclasses of CompilationDatabase for currently supported 24234287Sdim// formats. 25234287Sdim// 26234287Sdim//===----------------------------------------------------------------------===// 27234287Sdim 28234287Sdim#ifndef LLVM_CLANG_TOOLING_COMPILATION_DATABASE_H 29234287Sdim#define LLVM_CLANG_TOOLING_COMPILATION_DATABASE_H 30234287Sdim 31234287Sdim#include "clang/Basic/LLVM.h" 32234287Sdim#include "llvm/ADT/ArrayRef.h" 33234287Sdim#include "llvm/ADT/OwningPtr.h" 34234287Sdim#include "llvm/ADT/StringRef.h" 35234982Sdim#include "llvm/ADT/Twine.h" 36234287Sdim#include <string> 37234287Sdim#include <vector> 38234287Sdim 39234287Sdimnamespace clang { 40234287Sdimnamespace tooling { 41234287Sdim 42234287Sdim/// \brief Specifies the working directory and command of a compilation. 43234287Sdimstruct CompileCommand { 44234287Sdim CompileCommand() {} 45234982Sdim CompileCommand(Twine Directory, ArrayRef<std::string> CommandLine) 46234982Sdim : Directory(Directory.str()), CommandLine(CommandLine) {} 47234287Sdim 48234287Sdim /// \brief The working directory the command was executed from. 49234287Sdim std::string Directory; 50234287Sdim 51234287Sdim /// \brief The command line that was executed. 52234287Sdim std::vector<std::string> CommandLine; 53234287Sdim}; 54234287Sdim 55234287Sdim/// \brief Interface for compilation databases. 56234287Sdim/// 57234287Sdim/// A compilation database allows the user to retrieve all compile command lines 58234287Sdim/// that a specified file is compiled with in a project. 59234287Sdim/// The retrieved compile command lines can be used to run clang tools over 60234287Sdim/// a subset of the files in a project. 61234287Sdimclass CompilationDatabase { 62234287Sdimpublic: 63234287Sdim virtual ~CompilationDatabase(); 64234287Sdim 65234287Sdim /// \brief Loads a compilation database from a build directory. 66234287Sdim /// 67234287Sdim /// Looks at the specified 'BuildDirectory' and creates a compilation database 68234287Sdim /// that allows to query compile commands for source files in the 69234287Sdim /// corresponding source tree. 70234287Sdim /// 71234287Sdim /// Returns NULL and sets ErrorMessage if we were not able to build up a 72234287Sdim /// compilation database for the build directory. 73234287Sdim /// 74234287Sdim /// FIXME: Currently only supports JSON compilation databases, which 75234287Sdim /// are named 'compile_commands.json' in the given directory. Extend this 76234287Sdim /// for other build types (like ninja build files). 77234287Sdim static CompilationDatabase *loadFromDirectory(StringRef BuildDirectory, 78234287Sdim std::string &ErrorMessage); 79234287Sdim 80239462Sdim /// \brief Tries to detect a compilation database location and load it. 81239462Sdim /// 82239462Sdim /// Looks for a compilation database in all parent paths of file 'SourceFile' 83239462Sdim /// by calling loadFromDirectory. 84239462Sdim static CompilationDatabase *autoDetectFromSource(StringRef SourceFile, 85239462Sdim std::string &ErrorMessage); 86239462Sdim 87239462Sdim /// \brief Tries to detect a compilation database location and load it. 88239462Sdim /// 89239462Sdim /// Looks for a compilation database in directory 'SourceDir' and all 90239462Sdim /// its parent paths by calling loadFromDirectory. 91239462Sdim static CompilationDatabase *autoDetectFromDirectory(StringRef SourceDir, 92239462Sdim std::string &ErrorMessage); 93239462Sdim 94234287Sdim /// \brief Returns all compile commands in which the specified file was 95234287Sdim /// compiled. 96234287Sdim /// 97234287Sdim /// This includes compile comamnds that span multiple source files. 98234287Sdim /// For example, consider a project with the following compilations: 99234287Sdim /// $ clang++ -o test a.cc b.cc t.cc 100234287Sdim /// $ clang++ -o production a.cc b.cc -DPRODUCTION 101234287Sdim /// A compilation database representing the project would return both command 102234287Sdim /// lines for a.cc and b.cc and only the first command line for t.cc. 103234287Sdim virtual std::vector<CompileCommand> getCompileCommands( 104234287Sdim StringRef FilePath) const = 0; 105239462Sdim 106239462Sdim /// \brief Returns the list of all files available in the compilation database. 107239462Sdim virtual std::vector<std::string> getAllFiles() const = 0; 108249423Sdim 109249423Sdim /// \brief Returns all compile commands for all the files in the compilation 110249423Sdim /// database. 111249423Sdim virtual std::vector<CompileCommand> getAllCompileCommands() const = 0; 112234287Sdim}; 113234287Sdim 114243830Sdim/// \brief Interface for compilation database plugins. 115243830Sdim/// 116243830Sdim/// A compilation database plugin allows the user to register custom compilation 117243830Sdim/// databases that are picked up as compilation database if the corresponding 118243830Sdim/// library is linked in. To register a plugin, declare a static variable like: 119243830Sdim/// 120243830Sdim/// \code 121243830Sdim/// static CompilationDatabasePluginRegistry::Add<MyDatabasePlugin> 122243830Sdim/// X("my-compilation-database", "Reads my own compilation database"); 123243830Sdim/// \endcode 124243830Sdimclass CompilationDatabasePlugin { 125243830Sdimpublic: 126243830Sdim virtual ~CompilationDatabasePlugin(); 127243830Sdim 128243830Sdim /// \brief Loads a compilation database from a build directory. 129243830Sdim /// 130243830Sdim /// \see CompilationDatabase::loadFromDirectory(). 131243830Sdim virtual CompilationDatabase *loadFromDirectory(StringRef Directory, 132243830Sdim std::string &ErrorMessage) = 0; 133243830Sdim}; 134243830Sdim 135234982Sdim/// \brief A compilation database that returns a single compile command line. 136234982Sdim/// 137234982Sdim/// Useful when we want a tool to behave more like a compiler invocation. 138234982Sdimclass FixedCompilationDatabase : public CompilationDatabase { 139234982Sdimpublic: 140234982Sdim /// \brief Creates a FixedCompilationDatabase from the arguments after "--". 141234982Sdim /// 142234982Sdim /// Parses the given command line for "--". If "--" is found, the rest of 143234982Sdim /// the arguments will make up the command line in the returned 144234982Sdim /// FixedCompilationDatabase. 145234982Sdim /// The arguments after "--" must not include positional parameters or the 146234982Sdim /// argv[0] of the tool. Those will be added by the FixedCompilationDatabase 147234982Sdim /// when a CompileCommand is requested. The argv[0] of the returned command 148234982Sdim /// line will be "clang-tool". 149234982Sdim /// 150234982Sdim /// Returns NULL in case "--" is not found. 151234982Sdim /// 152234982Sdim /// The argument list is meant to be compatible with normal llvm command line 153234982Sdim /// parsing in main methods. 154234982Sdim /// int main(int argc, char **argv) { 155249423Sdim /// OwningPtr<FixedCompilationDatabase> Compilations( 156234982Sdim /// FixedCompilationDatabase::loadFromCommandLine(argc, argv)); 157234982Sdim /// cl::ParseCommandLineOptions(argc, argv); 158234982Sdim /// ... 159234982Sdim /// } 160234982Sdim /// 161234982Sdim /// \param Argc The number of command line arguments - will be changed to 162234982Sdim /// the number of arguments before "--", if "--" was found in the argument 163234982Sdim /// list. 164234982Sdim /// \param Argv Points to the command line arguments. 165234982Sdim /// \param Directory The base directory used in the FixedCompilationDatabase. 166234982Sdim static FixedCompilationDatabase *loadFromCommandLine(int &Argc, 167234982Sdim const char **Argv, 168234982Sdim Twine Directory = "."); 169234982Sdim 170234982Sdim /// \brief Constructs a compilation data base from a specified directory 171234982Sdim /// and command line. 172234982Sdim FixedCompilationDatabase(Twine Directory, ArrayRef<std::string> CommandLine); 173234982Sdim 174234982Sdim /// \brief Returns the given compile command. 175234982Sdim /// 176234982Sdim /// Will always return a vector with one entry that contains the directory 177234982Sdim /// and command line specified at construction with "clang-tool" as argv[0] 178234982Sdim /// and 'FilePath' as positional argument. 179234982Sdim virtual std::vector<CompileCommand> getCompileCommands( 180234982Sdim StringRef FilePath) const; 181234982Sdim 182239462Sdim /// \brief Returns the list of all files available in the compilation database. 183239462Sdim /// 184239462Sdim /// Note: This is always an empty list for the fixed compilation database. 185239462Sdim virtual std::vector<std::string> getAllFiles() const; 186239462Sdim 187249423Sdim /// \brief Returns all compile commands for all the files in the compilation 188249423Sdim /// database. 189249423Sdim /// 190249423Sdim /// Note: This is always an empty list for the fixed compilation database. 191249423Sdim virtual std::vector<CompileCommand> getAllCompileCommands() const; 192249423Sdim 193234982Sdimprivate: 194234982Sdim /// This is built up to contain a single entry vector to be returned from 195234982Sdim /// getCompileCommands after adding the positional argument. 196234982Sdim std::vector<CompileCommand> CompileCommands; 197234982Sdim}; 198234982Sdim 199234287Sdim} // end namespace tooling 200234287Sdim} // end namespace clang 201234287Sdim 202234287Sdim#endif // LLVM_CLANG_TOOLING_COMPILATION_DATABASE_H 203