Tooling.h revision 295413422d0c8d70e8861b71f7b622871ba1ba44
1cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek//===--- Tooling.h - Framework for standalone Clang tools -------*- C++ -*-===// 2cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek// 3cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek// The LLVM Compiler Infrastructure 4cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek// 5cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek// This file is distributed under the University of Illinois Open Source 6cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek// License. See LICENSE.TXT for details. 7cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek// 8cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek//===----------------------------------------------------------------------===// 9cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek// 10cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek// This file implements functions to run clang tools standalone instead 11cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek// of running them as a plugin. 12cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek// 13cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek// A ClangTool is initialized with a CompilationDatabase and a set of files 14cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek// to run over. The tool will then run a user-specified FrontendAction over 15cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek// all TUs in which the given files are compiled. 16cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek// 17cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek// It is also possible to run a FrontendAction over a snippet of code by 18295413422d0c8d70e8861b71f7b622871ba1ba44Manuel Klimek// calling runToolOnCode, which is useful for unit testing. 19cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek// 20cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek// Applications that need more fine grained control over how to run 21cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek// multiple FrontendActions over code can use ToolInvocation. 22cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek// 23cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek// Example tools: 24cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek// - running clang -fsyntax-only over source code from an editor to get 25cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek// fast syntax checks 26cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek// - running match/replace tools over C++ code 27cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek// 28cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek//===----------------------------------------------------------------------===// 29cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek 30cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek#ifndef LLVM_CLANG_TOOLING_TOOLING_H 31cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek#define LLVM_CLANG_TOOLING_TOOLING_H 32cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek 33cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek#include "llvm/ADT/StringMap.h" 34cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek#include "llvm/ADT/Twine.h" 35cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek#include "clang/Basic/FileManager.h" 36cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek#include "clang/Basic/LLVM.h" 37cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek#include "clang/Driver/Util.h" 38cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek#include <string> 39cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek#include <vector> 40cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek 41cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimeknamespace clang { 42cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek 43cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimeknamespace driver { 44cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimekclass Compilation; 45cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek} // end namespace driver 46cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek 47cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimekclass CompilerInvocation; 48cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimekclass SourceManager; 49cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimekclass FrontendAction; 50cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek 51cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimeknamespace tooling { 52cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek 53cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimekclass CompilationDatabase; 54cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek 55cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek/// \brief Interface to generate clang::FrontendActions. 56cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimekclass FrontendActionFactory { 57cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimekpublic: 58cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek virtual ~FrontendActionFactory(); 59cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek 60cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek /// \brief Returns a new clang::FrontendAction. 61cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek /// 62cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek /// The caller takes ownership of the returned action. 63cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek virtual clang::FrontendAction *create() = 0; 64cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek}; 65cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek 66cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek/// \brief Returns a new FrontendActionFactory for a given type. 67cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek/// 68cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek/// T must extend clang::FrontendAction. 69cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek/// 70cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek/// Example: 71cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek/// FrontendActionFactory *Factory = 72cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek/// newFrontendActionFactory<clang::SyntaxOnlyAction>(); 73cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimektemplate <typename T> 74cb971c6726d16e12ecd2a340941d7f5c06698332Manuel KlimekFrontendActionFactory *newFrontendActionFactory(); 75cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek 76cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek/// \brief Returns a new FrontendActionFactory for any type that provides an 77cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek/// implementation of newFrontendAction(). 78cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek/// 79cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek/// FactoryT must implement: FrontendAction *newFrontendAction(). 80cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek/// 81cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek/// Example: 82cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek/// struct ProvidesFrontendActions { 83cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek/// FrontendAction *newFrontendAction(); 84cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek/// } Factory; 85cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek/// FrontendActionFactory *FactoryAdapter = 86cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek/// newFrontendActionFactory(&Factory); 87cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimektemplate <typename FactoryT> 88cb971c6726d16e12ecd2a340941d7f5c06698332Manuel KlimekFrontendActionFactory *newFrontendActionFactory(FactoryT *ActionFactory); 89cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek 90cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek/// \brief Runs (and deletes) the tool on 'Code' with the -fsyntax-only flag. 91cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek/// 92cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek/// \param ToolAction The action to run over the code. 93cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek/// \param Code C++ code. 94cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek/// \param FileName The file name which 'Code' will be mapped as. 95cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek/// 96cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek/// \return - True if 'ToolAction' was successfully executed. 97cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimekbool runToolOnCode(clang::FrontendAction *ToolAction, const Twine &Code, 98cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek const Twine &FileName = "input.cc"); 99cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek 100cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek/// \brief Utility to run a FrontendAction in a single clang invocation. 101cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimekclass ToolInvocation { 102cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek public: 103cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek /// \brief Create a tool invocation. 104cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek /// 105cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek /// \param CommandLine The command line arguments to clang. 106cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek /// \param ToolAction The action to be executed. Class takes ownership. 107cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek /// \param Files The FileManager used for the execution. Class does not take 108cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek /// ownership. 109cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek ToolInvocation(ArrayRef<std::string> CommandLine, FrontendAction *ToolAction, 110cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek FileManager *Files); 111cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek 112cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek /// \brief Map a virtual file to be used while running the tool. 113cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek /// 114cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek /// \param FilePath The path at which the content will be mapped. 115cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek /// \param Content A null terminated buffer of the file's content. 116cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek void mapVirtualFile(StringRef FilePath, StringRef Content); 117cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek 118cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek /// \brief Run the clang invocation. 119cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek /// 120cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek /// \returns True if there were no errors during execution. 121cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek bool run(); 122cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek 123cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek private: 124cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek void addFileMappingsTo(SourceManager &SourceManager); 125cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek 126cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek bool runInvocation(const char *BinaryName, 127cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek clang::driver::Compilation *Compilation, 128cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek clang::CompilerInvocation *Invocation, 129cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek const clang::driver::ArgStringList &CC1Args, 130cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek clang::FrontendAction *ToolAction); 131cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek 132cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek std::vector<std::string> CommandLine; 133cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek llvm::OwningPtr<FrontendAction> ToolAction; 134cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek FileManager *Files; 135cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek // Maps <file name> -> <file content>. 136cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek llvm::StringMap<StringRef> MappedFileContents; 137cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek}; 138cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek 139cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek/// \brief Utility to run a FrontendAction over a set of files. 140cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek/// 141cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek/// This class is written to be usable for command line utilities. 142cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimekclass ClangTool { 143cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek public: 144cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek /// \brief Constructs a clang tool to run over a list of files. 145cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek /// 146cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek /// \param Compilations The CompilationDatabase which contains the compile 147cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek /// command lines for the given source paths. 148cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek /// \param SourcePaths The source files to run over. If a source files is 149cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek /// not found in Compilations, it is skipped. 150cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek ClangTool(const CompilationDatabase &Compilations, 151cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek ArrayRef<std::string> SourcePaths); 152cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek 153cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek /// \brief Map a virtual file to be used while running the tool. 154cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek /// 155cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek /// \param FilePath The path at which the content will be mapped. 156cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek /// \param Content A null terminated buffer of the file's content. 157cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek void mapVirtualFile(StringRef FilePath, StringRef Content); 158cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek 159cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek /// Runs a frontend action over all files specified in the command line. 160cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek /// 161cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek /// \param ActionFactory Factory generating the frontend actions. The function 162cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek /// takes ownership of this parameter. A new action is generated for every 163cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek /// processed translation unit. 164cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek int run(FrontendActionFactory *ActionFactory); 165cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek 166cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek /// \brief Returns the file manager used in the tool. 167cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek /// 168cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek /// The file manager is shared between all translation units. 169cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek FileManager &getFiles() { return Files; } 170cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek 171cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek private: 172cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek // We store command lines as pair (file name, command line). 173cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek typedef std::pair< std::string, std::vector<std::string> > CommandLine; 174cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek std::vector<CommandLine> CommandLines; 175cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek 176cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek FileManager Files; 177cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek // Contains a list of pairs (<file name>, <file content>). 178cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek std::vector< std::pair<StringRef, StringRef> > MappedFileContents; 179cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek}; 180cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek 181cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimektemplate <typename T> 182cb971c6726d16e12ecd2a340941d7f5c06698332Manuel KlimekFrontendActionFactory *newFrontendActionFactory() { 183cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek class SimpleFrontendActionFactory : public FrontendActionFactory { 184cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek public: 185cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek virtual clang::FrontendAction *create() { return new T; } 186cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek }; 187cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek 188cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek return new SimpleFrontendActionFactory; 189cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek} 190cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek 191cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimektemplate <typename FactoryT> 192cb971c6726d16e12ecd2a340941d7f5c06698332Manuel KlimekFrontendActionFactory *newFrontendActionFactory(FactoryT *ActionFactory) { 193cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek class FrontendActionFactoryAdapter : public FrontendActionFactory { 194cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek public: 195cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek explicit FrontendActionFactoryAdapter(FactoryT *ActionFactory) 196cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek : ActionFactory(ActionFactory) {} 197cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek 198cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek virtual clang::FrontendAction *create() { 199cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek return ActionFactory->newFrontendAction(); 200cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek } 201cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek 202cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek private: 203cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek FactoryT *ActionFactory; 204cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek }; 205cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek 206cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek return new FrontendActionFactoryAdapter(ActionFactory); 207cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek} 208cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek 209cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek} // end namespace tooling 210cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek} // end namespace clang 211cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek 212cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek#endif // LLVM_CLANG_TOOLING_TOOLING_H 213cb971c6726d16e12ecd2a340941d7f5c06698332Manuel Klimek 214