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