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; 53263508Sdim 54263508Sdim /// \brief An optional mapping from each file's path to its content for all 55263508Sdim /// files needed for the compilation that are not available via the file 56263508Sdim /// system. 57263508Sdim /// 58263508Sdim /// Note that a tool implementation is required to fall back to the file 59263508Sdim /// system if a source file is not provided in the mapped sources, as 60263508Sdim /// compilation databases will usually not provide all files in mapped sources 61263508Sdim /// for performance reasons. 62263508Sdim std::vector<std::pair<std::string, std::string> > MappedSources; 63234287Sdim}; 64234287Sdim 65234287Sdim/// \brief Interface for compilation databases. 66234287Sdim/// 67234287Sdim/// A compilation database allows the user to retrieve all compile command lines 68234287Sdim/// that a specified file is compiled with in a project. 69234287Sdim/// The retrieved compile command lines can be used to run clang tools over 70234287Sdim/// a subset of the files in a project. 71234287Sdimclass CompilationDatabase { 72234287Sdimpublic: 73234287Sdim virtual ~CompilationDatabase(); 74234287Sdim 75234287Sdim /// \brief Loads a compilation database from a build directory. 76234287Sdim /// 77234287Sdim /// Looks at the specified 'BuildDirectory' and creates a compilation database 78234287Sdim /// that allows to query compile commands for source files in the 79234287Sdim /// corresponding source tree. 80234287Sdim /// 81234287Sdim /// Returns NULL and sets ErrorMessage if we were not able to build up a 82234287Sdim /// compilation database for the build directory. 83234287Sdim /// 84234287Sdim /// FIXME: Currently only supports JSON compilation databases, which 85234287Sdim /// are named 'compile_commands.json' in the given directory. Extend this 86234287Sdim /// for other build types (like ninja build files). 87234287Sdim static CompilationDatabase *loadFromDirectory(StringRef BuildDirectory, 88234287Sdim std::string &ErrorMessage); 89234287Sdim 90239462Sdim /// \brief Tries to detect a compilation database location and load it. 91239462Sdim /// 92239462Sdim /// Looks for a compilation database in all parent paths of file 'SourceFile' 93239462Sdim /// by calling loadFromDirectory. 94239462Sdim static CompilationDatabase *autoDetectFromSource(StringRef SourceFile, 95239462Sdim std::string &ErrorMessage); 96239462Sdim 97239462Sdim /// \brief Tries to detect a compilation database location and load it. 98239462Sdim /// 99239462Sdim /// Looks for a compilation database in directory 'SourceDir' and all 100239462Sdim /// its parent paths by calling loadFromDirectory. 101239462Sdim static CompilationDatabase *autoDetectFromDirectory(StringRef SourceDir, 102239462Sdim std::string &ErrorMessage); 103239462Sdim 104234287Sdim /// \brief Returns all compile commands in which the specified file was 105234287Sdim /// compiled. 106234287Sdim /// 107234287Sdim /// This includes compile comamnds that span multiple source files. 108234287Sdim /// For example, consider a project with the following compilations: 109234287Sdim /// $ clang++ -o test a.cc b.cc t.cc 110234287Sdim /// $ clang++ -o production a.cc b.cc -DPRODUCTION 111234287Sdim /// A compilation database representing the project would return both command 112234287Sdim /// lines for a.cc and b.cc and only the first command line for t.cc. 113234287Sdim virtual std::vector<CompileCommand> getCompileCommands( 114234287Sdim StringRef FilePath) const = 0; 115239462Sdim 116239462Sdim /// \brief Returns the list of all files available in the compilation database. 117239462Sdim virtual std::vector<std::string> getAllFiles() const = 0; 118249423Sdim 119249423Sdim /// \brief Returns all compile commands for all the files in the compilation 120249423Sdim /// database. 121263508Sdim /// 122263508Sdim /// FIXME: Add a layer in Tooling that provides an interface to run a tool 123263508Sdim /// over all files in a compilation database. Not all build systems have the 124263508Sdim /// ability to provide a feasible implementation for \c getAllCompileCommands. 125249423Sdim virtual std::vector<CompileCommand> getAllCompileCommands() const = 0; 126234287Sdim}; 127234287Sdim 128243830Sdim/// \brief Interface for compilation database plugins. 129243830Sdim/// 130243830Sdim/// A compilation database plugin allows the user to register custom compilation 131243830Sdim/// databases that are picked up as compilation database if the corresponding 132243830Sdim/// library is linked in. To register a plugin, declare a static variable like: 133243830Sdim/// 134243830Sdim/// \code 135243830Sdim/// static CompilationDatabasePluginRegistry::Add<MyDatabasePlugin> 136243830Sdim/// X("my-compilation-database", "Reads my own compilation database"); 137243830Sdim/// \endcode 138243830Sdimclass CompilationDatabasePlugin { 139243830Sdimpublic: 140243830Sdim virtual ~CompilationDatabasePlugin(); 141243830Sdim 142243830Sdim /// \brief Loads a compilation database from a build directory. 143243830Sdim /// 144243830Sdim /// \see CompilationDatabase::loadFromDirectory(). 145243830Sdim virtual CompilationDatabase *loadFromDirectory(StringRef Directory, 146243830Sdim std::string &ErrorMessage) = 0; 147243830Sdim}; 148243830Sdim 149234982Sdim/// \brief A compilation database that returns a single compile command line. 150234982Sdim/// 151234982Sdim/// Useful when we want a tool to behave more like a compiler invocation. 152234982Sdimclass FixedCompilationDatabase : public CompilationDatabase { 153234982Sdimpublic: 154234982Sdim /// \brief Creates a FixedCompilationDatabase from the arguments after "--". 155234982Sdim /// 156234982Sdim /// Parses the given command line for "--". If "--" is found, the rest of 157234982Sdim /// the arguments will make up the command line in the returned 158234982Sdim /// FixedCompilationDatabase. 159234982Sdim /// The arguments after "--" must not include positional parameters or the 160234982Sdim /// argv[0] of the tool. Those will be added by the FixedCompilationDatabase 161234982Sdim /// when a CompileCommand is requested. The argv[0] of the returned command 162234982Sdim /// line will be "clang-tool". 163234982Sdim /// 164234982Sdim /// Returns NULL in case "--" is not found. 165234982Sdim /// 166234982Sdim /// The argument list is meant to be compatible with normal llvm command line 167234982Sdim /// parsing in main methods. 168234982Sdim /// int main(int argc, char **argv) { 169249423Sdim /// OwningPtr<FixedCompilationDatabase> Compilations( 170234982Sdim /// FixedCompilationDatabase::loadFromCommandLine(argc, argv)); 171234982Sdim /// cl::ParseCommandLineOptions(argc, argv); 172234982Sdim /// ... 173234982Sdim /// } 174234982Sdim /// 175234982Sdim /// \param Argc The number of command line arguments - will be changed to 176234982Sdim /// the number of arguments before "--", if "--" was found in the argument 177234982Sdim /// list. 178234982Sdim /// \param Argv Points to the command line arguments. 179234982Sdim /// \param Directory The base directory used in the FixedCompilationDatabase. 180234982Sdim static FixedCompilationDatabase *loadFromCommandLine(int &Argc, 181234982Sdim const char **Argv, 182234982Sdim Twine Directory = "."); 183234982Sdim 184234982Sdim /// \brief Constructs a compilation data base from a specified directory 185234982Sdim /// and command line. 186234982Sdim FixedCompilationDatabase(Twine Directory, ArrayRef<std::string> CommandLine); 187234982Sdim 188234982Sdim /// \brief Returns the given compile command. 189234982Sdim /// 190234982Sdim /// Will always return a vector with one entry that contains the directory 191234982Sdim /// and command line specified at construction with "clang-tool" as argv[0] 192234982Sdim /// and 'FilePath' as positional argument. 193234982Sdim virtual std::vector<CompileCommand> getCompileCommands( 194234982Sdim StringRef FilePath) const; 195234982Sdim 196239462Sdim /// \brief Returns the list of all files available in the compilation database. 197239462Sdim /// 198239462Sdim /// Note: This is always an empty list for the fixed compilation database. 199239462Sdim virtual std::vector<std::string> getAllFiles() const; 200239462Sdim 201249423Sdim /// \brief Returns all compile commands for all the files in the compilation 202249423Sdim /// database. 203249423Sdim /// 204249423Sdim /// Note: This is always an empty list for the fixed compilation database. 205249423Sdim virtual std::vector<CompileCommand> getAllCompileCommands() const; 206249423Sdim 207234982Sdimprivate: 208234982Sdim /// This is built up to contain a single entry vector to be returned from 209234982Sdim /// getCompileCommands after adding the positional argument. 210234982Sdim std::vector<CompileCommand> CompileCommands; 211234982Sdim}; 212234982Sdim 213234287Sdim} // end namespace tooling 214234287Sdim} // end namespace clang 215234287Sdim 216234287Sdim#endif // LLVM_CLANG_TOOLING_COMPILATION_DATABASE_H 217