| //===- CompilationDatabase.h ------------------------------------*- C++ -*-===// |
| // |
| // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. |
| // See https://llvm.org/LICENSE.txt for license information. |
| // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception |
| // |
| //===----------------------------------------------------------------------===// |
| // |
| // This file provides an interface and multiple implementations for |
| // CompilationDatabases. |
| // |
| // While C++ refactoring and analysis tools are not compilers, and thus |
| // don't run as part of the build system, they need the exact information |
| // of a build in order to be able to correctly understand the C++ code of |
| // the project. This information is provided via the CompilationDatabase |
| // interface. |
| // |
| // To create a CompilationDatabase from a build directory one can call |
| // CompilationDatabase::loadFromDirectory(), which deduces the correct |
| // compilation database from the root of the build tree. |
| // |
| // See the concrete subclasses of CompilationDatabase for currently supported |
| // formats. |
| // |
| //===----------------------------------------------------------------------===// |
| |
| #ifndef LLVM_CLANG_TOOLING_COMPILATIONDATABASE_H |
| #define LLVM_CLANG_TOOLING_COMPILATIONDATABASE_H |
| |
| #include "clang/Basic/LLVM.h" |
| #include "llvm/ADT/ArrayRef.h" |
| #include "llvm/ADT/StringRef.h" |
| #include "llvm/ADT/Twine.h" |
| #include "llvm/Support/VirtualFileSystem.h" |
| #include <memory> |
| #include <string> |
| #include <utility> |
| #include <vector> |
| |
| namespace clang { |
| namespace tooling { |
| |
| /// Specifies the working directory and command of a compilation. |
| struct CompileCommand { |
| CompileCommand() = default; |
| CompileCommand(const Twine &Directory, const Twine &Filename, |
| std::vector<std::string> CommandLine, const Twine &Output) |
| : Directory(Directory.str()), Filename(Filename.str()), |
| CommandLine(std::move(CommandLine)), Output(Output.str()) {} |
| |
| /// The working directory the command was executed from. |
| std::string Directory; |
| |
| /// The source file associated with the command. |
| std::string Filename; |
| |
| /// The command line that was executed. |
| std::vector<std::string> CommandLine; |
| |
| /// The output file associated with the command. |
| std::string Output; |
| |
| /// If this compile command was guessed rather than read from an authoritative |
| /// source, a short human-readable explanation. |
| /// e.g. "inferred from foo/bar.h". |
| std::string Heuristic; |
| |
| friend bool operator==(const CompileCommand &LHS, const CompileCommand &RHS) { |
| return LHS.Directory == RHS.Directory && LHS.Filename == RHS.Filename && |
| LHS.CommandLine == RHS.CommandLine && LHS.Output == RHS.Output && |
| LHS.Heuristic == RHS.Heuristic; |
| } |
| |
| friend bool operator!=(const CompileCommand &LHS, const CompileCommand &RHS) { |
| return !(LHS == RHS); |
| } |
| }; |
| |
| /// Interface for compilation databases. |
| /// |
| /// A compilation database allows the user to retrieve compile command lines |
| /// for the files in a project. |
| /// |
| /// Many implementations are enumerable, allowing all command lines to be |
| /// retrieved. These can be used to run clang tools over a subset of the files |
| /// in a project. |
| class CompilationDatabase { |
| public: |
| virtual ~CompilationDatabase(); |
| |
| /// Loads a compilation database from a build directory. |
| /// |
| /// Looks at the specified 'BuildDirectory' and creates a compilation database |
| /// that allows to query compile commands for source files in the |
| /// corresponding source tree. |
| /// |
| /// Returns NULL and sets ErrorMessage if we were not able to build up a |
| /// compilation database for the build directory. |
| /// |
| /// FIXME: Currently only supports JSON compilation databases, which |
| /// are named 'compile_commands.json' in the given directory. Extend this |
| /// for other build types (like ninja build files). |
| static std::unique_ptr<CompilationDatabase> |
| loadFromDirectory(StringRef BuildDirectory, std::string &ErrorMessage); |
| |
| /// Tries to detect a compilation database location and load it. |
| /// |
| /// Looks for a compilation database in all parent paths of file 'SourceFile' |
| /// by calling loadFromDirectory. |
| static std::unique_ptr<CompilationDatabase> |
| autoDetectFromSource(StringRef SourceFile, std::string &ErrorMessage); |
| |
| /// Tries to detect a compilation database location and load it. |
| /// |
| /// Looks for a compilation database in directory 'SourceDir' and all |
| /// its parent paths by calling loadFromDirectory. |
| static std::unique_ptr<CompilationDatabase> |
| autoDetectFromDirectory(StringRef SourceDir, std::string &ErrorMessage); |
| |
| /// Returns all compile commands in which the specified file was |
| /// compiled. |
| /// |
| /// This includes compile commands that span multiple source files. |
| /// For example, consider a project with the following compilations: |
| /// $ clang++ -o test a.cc b.cc t.cc |
| /// $ clang++ -o production a.cc b.cc -DPRODUCTION |
| /// A compilation database representing the project would return both command |
| /// lines for a.cc and b.cc and only the first command line for t.cc. |
| virtual std::vector<CompileCommand> getCompileCommands( |
| StringRef FilePath) const = 0; |
| |
| /// Returns the list of all files available in the compilation database. |
| /// |
| /// By default, returns nothing. Implementations should override this if they |
| /// can enumerate their source files. |
| virtual std::vector<std::string> getAllFiles() const { return {}; } |
| |
| /// Returns all compile commands for all the files in the compilation |
| /// database. |
| /// |
| /// FIXME: Add a layer in Tooling that provides an interface to run a tool |
| /// over all files in a compilation database. Not all build systems have the |
| /// ability to provide a feasible implementation for \c getAllCompileCommands. |
| /// |
| /// By default, this is implemented in terms of getAllFiles() and |
| /// getCompileCommands(). Subclasses may override this for efficiency. |
| virtual std::vector<CompileCommand> getAllCompileCommands() const; |
| }; |
| |
| /// A compilation database that returns a single compile command line. |
| /// |
| /// Useful when we want a tool to behave more like a compiler invocation. |
| /// This compilation database is not enumerable: getAllFiles() returns {}. |
| class FixedCompilationDatabase : public CompilationDatabase { |
| public: |
| /// Creates a FixedCompilationDatabase from the arguments after "--". |
| /// |
| /// Parses the given command line for "--". If "--" is found, the rest of |
| /// the arguments will make up the command line in the returned |
| /// FixedCompilationDatabase. |
| /// The arguments after "--" must not include positional parameters or the |
| /// argv[0] of the tool. Those will be added by the FixedCompilationDatabase |
| /// when a CompileCommand is requested. The argv[0] of the returned command |
| /// line will be "clang-tool". |
| /// |
| /// Returns NULL in case "--" is not found. |
| /// |
| /// The argument list is meant to be compatible with normal llvm command line |
| /// parsing in main methods. |
| /// int main(int argc, char **argv) { |
| /// std::unique_ptr<FixedCompilationDatabase> Compilations( |
| /// FixedCompilationDatabase::loadFromCommandLine(argc, argv)); |
| /// cl::ParseCommandLineOptions(argc, argv); |
| /// ... |
| /// } |
| /// |
| /// \param Argc The number of command line arguments - will be changed to |
| /// the number of arguments before "--", if "--" was found in the argument |
| /// list. |
| /// \param Argv Points to the command line arguments. |
| /// \param ErrorMsg Contains error text if the function returns null pointer. |
| /// \param Directory The base directory used in the FixedCompilationDatabase. |
| static std::unique_ptr<FixedCompilationDatabase> |
| loadFromCommandLine(int &Argc, const char *const *Argv, std::string &ErrorMsg, |
| const Twine &Directory = "."); |
| |
| /// Reads flags from the given file, one-per-line. |
| /// Returns nullptr and sets ErrorMessage if we can't read the file. |
| static std::unique_ptr<FixedCompilationDatabase> |
| loadFromFile(StringRef Path, std::string &ErrorMsg); |
| |
| /// Reads flags from the given buffer, one-per-line. |
| /// Directory is the command CWD, typically the parent of compile_flags.txt. |
| static std::unique_ptr<FixedCompilationDatabase> |
| loadFromBuffer(StringRef Directory, StringRef Data, std::string &ErrorMsg); |
| |
| /// Constructs a compilation data base from a specified directory |
| /// and command line. |
| FixedCompilationDatabase(const Twine &Directory, |
| ArrayRef<std::string> CommandLine); |
| |
| /// Returns the given compile command. |
| /// |
| /// Will always return a vector with one entry that contains the directory |
| /// and command line specified at construction with "clang-tool" as argv[0] |
| /// and 'FilePath' as positional argument. |
| std::vector<CompileCommand> |
| getCompileCommands(StringRef FilePath) const override; |
| |
| private: |
| /// This is built up to contain a single entry vector to be returned from |
| /// getCompileCommands after adding the positional argument. |
| std::vector<CompileCommand> CompileCommands; |
| }; |
| |
| /// Transforms a compile command so that it applies the same configuration to |
| /// a different file. Most args are left intact, but tweaks may be needed |
| /// to certain flags (-x, -std etc). |
| tooling::CompileCommand transferCompileCommand(tooling::CompileCommand, |
| StringRef Filename); |
| |
| /// Returns a wrapped CompilationDatabase that defers to the provided one, |
| /// but getCompileCommands() will infer commands for unknown files. |
| /// The return value of getAllFiles() or getAllCompileCommands() is unchanged. |
| /// See InterpolatingCompilationDatabase.cpp for details on heuristics. |
| std::unique_ptr<CompilationDatabase> |
| inferMissingCompileCommands(std::unique_ptr<CompilationDatabase>); |
| |
| /// Returns a wrapped CompilationDatabase that will add -target and -mode flags |
| /// to commandline when they can be deduced from argv[0] of commandline returned |
| /// by underlying database. |
| std::unique_ptr<CompilationDatabase> |
| inferTargetAndDriverMode(std::unique_ptr<CompilationDatabase> Base); |
| |
| /// Returns a wrapped CompilationDatabase that will expand all rsp(response) |
| /// files on commandline returned by underlying database. |
| std::unique_ptr<CompilationDatabase> |
| expandResponseFiles(std::unique_ptr<CompilationDatabase> Base, |
| llvm::IntrusiveRefCntPtr<llvm::vfs::FileSystem> FS); |
| |
| } // namespace tooling |
| } // namespace clang |
| |
| #endif // LLVM_CLANG_TOOLING_COMPILATIONDATABASE_H |