Linker.h revision 212904
1105197Ssam//===- llvm/Linker.h - Module Linker Interface ------------------*- C++ -*-===// 2105197Ssam// 3105197Ssam// The LLVM Compiler Infrastructure 4139823Simp// 5105197Ssam// This file is distributed under the University of Illinois Open Source 6105197Ssam// License. See LICENSE.TXT for details. 7105197Ssam// 8105197Ssam//===----------------------------------------------------------------------===// 9105197Ssam// 10105197Ssam// This file defines the interface to the module/file/archive linker. 11105197Ssam// 12105197Ssam//===----------------------------------------------------------------------===// 13105197Ssam 14105197Ssam#ifndef LLVM_LINKER_H 15105197Ssam#define LLVM_LINKER_H 16105197Ssam 17105197Ssam#include <memory> 18105197Ssam#include <vector> 19105197Ssam#include "llvm/ADT/StringRef.h" 20105197Ssam 21105197Ssamnamespace llvm { 22105197Ssam namespace sys { class Path; } 23105197Ssam 24105197Ssamclass Module; 25105197Ssamclass LLVMContext; 26105197Ssam 27105197Ssam/// This class provides the core functionality of linking in LLVM. It retains a 28105197Ssam/// Module object which is the composite of the modules and libraries linked 29105197Ssam/// into it. The composite Module can be retrieved via the getModule() method. 30105197Ssam/// In this case the Linker still retains ownership of the Module. If the 31105197Ssam/// releaseModule() method is used, the ownership of the Module is transferred 32105197Ssam/// to the caller and the Linker object is only suitable for destruction. 33105197Ssam/// The Linker can link Modules from memory, bitcode files, or bitcode 34105197Ssam/// archives. It retains a set of search paths in which to find any libraries 35105197Ssam/// presented to it. By default, the linker will generate error and warning 36105197Ssam/// messages to stderr but this capability can be turned off with the 37105197Ssam/// QuietWarnings and QuietErrors flags. It can also be instructed to verbosely 38105197Ssam/// print out the linking actions it is taking with the Verbose flag. 39105197Ssam/// @brief The LLVM Linker. 40105197Ssamclass Linker { 41105197Ssam 42105197Ssam /// @name Types 43105197Ssam /// @{ 44105197Ssam public: 45119643Ssam /// This type is used to pass the linkage items (libraries and files) to 46119643Ssam /// the LinkItems function. It is composed of string/bool pairs. The string 47105197Ssam /// provides the name of the file or library (as with the -l option). The 48105197Ssam /// bool should be true for libraries and false for files, signifying 49105197Ssam /// "isLibrary". 50105197Ssam /// @brief A list of linkage items 51105197Ssam typedef std::vector<std::pair<std::string,bool> > ItemList; 52105197Ssam 53105197Ssam /// This enumeration is used to control various optional features of the 54105197Ssam /// linker. 55105197Ssam enum ControlFlags { 56105197Ssam Verbose = 1, ///< Print to stderr what steps the linker is taking 57158767Spjd QuietWarnings = 2, ///< Don't print warnings to stderr. 58105197Ssam QuietErrors = 4 ///< Don't print errors to stderr. 59183550Szec }; 60105197Ssam 61105197Ssam /// @} 62105197Ssam /// @name Constructors 63105197Ssam /// @{ 64105197Ssam public: 65105197Ssam /// Construct the Linker with an empty module which will be given the 66105197Ssam /// name \p progname. \p progname will also be used for error messages. 67105197Ssam /// @brief Construct with empty module 68105197Ssam Linker(StringRef progname, ///< name of tool running linker 69105197Ssam StringRef modulename, ///< name of linker's end-result module 70105197Ssam LLVMContext &C, ///< Context for global info 71105197Ssam unsigned Flags = 0 ///< ControlFlags (one or more |'d together) 72105197Ssam ); 73105197Ssam 74105197Ssam /// Construct the Linker with a previously defined module, \p aModule. Use 75105197Ssam /// \p progname for the name of the program in error messages. 76105197Ssam /// @brief Construct with existing module 77105197Ssam Linker(StringRef progname, Module* aModule, unsigned Flags = 0); 78185571Sbz 79105197Ssam /// Destruct the Linker. 80105197Ssam /// @brief Destructor 81105197Ssam ~Linker(); 82185571Sbz 83105197Ssam /// @} 84105197Ssam /// @name Accessors 85105197Ssam /// @{ 86105197Ssam public: 87105197Ssam /// This method gets the composite module into which linking is being 88105197Ssam /// done. The Composite module starts out empty and accumulates modules 89105197Ssam /// linked into it via the various LinkIn* methods. This method does not 90105197Ssam /// release the Module to the caller. The Linker retains ownership and will 91105197Ssam /// destruct the Module when the Linker is destructed. 92105197Ssam /// @see releaseModule 93105197Ssam /// @brief Get the linked/composite module. 94105197Ssam Module* getModule() const { return Composite; } 95105197Ssam 96105197Ssam /// This method releases the composite Module into which linking is being 97105197Ssam /// done. Ownership of the composite Module is transferred to the caller who 98105197Ssam /// must arrange for its destruct. After this method is called, the Linker 99105197Ssam /// terminates the linking session for the returned Module. It will no 100105197Ssam /// longer utilize the returned Module but instead resets itself for 101105197Ssam /// subsequent linking as if the constructor had been called. The Linker's 102181803Sbz /// LibPaths and flags to be reset, and memory will be released. 103105197Ssam /// @brief Release the linked/composite module. 104105197Ssam Module* releaseModule(); 105105197Ssam 106105197Ssam /// This method gets the list of libraries that form the path that the 107105197Ssam /// Linker will search when it is presented with a library name. 108105197Ssam /// @brief Get the Linkers library path 109105197Ssam const std::vector<sys::Path>& getLibPaths() const { return LibPaths; } 110105197Ssam 111105197Ssam /// This method returns an error string suitable for printing to the user. 112105197Ssam /// The return value will be empty unless an error occurred in one of the 113105197Ssam /// LinkIn* methods. In those cases, the LinkIn* methods will have returned 114105197Ssam /// true, indicating an error occurred. At most one error is retained so 115105197Ssam /// this function always returns the last error that occurred. Note that if 116105197Ssam /// the Quiet control flag is not set, the error string will have already 117105197Ssam /// been printed to stderr. 118185088Szec /// @brief Get the text of the last error that occurred. 119185088Szec const std::string &getLastError() const { return Error; } 120185088Szec 121185088Szec /// @} 122185088Szec /// @name Mutators 123185088Szec /// @{ 124185088Szec public: 125185088Szec /// Add a path to the list of paths that the Linker will search. The Linker 126185088Szec /// accumulates the set of libraries added 127185088Szec /// library paths for the target platform. The standard libraries will 128185088Szec /// always be searched last. The added libraries will be searched in the 129105197Ssam /// order added. 130185088Szec /// @brief Add a path. 131105197Ssam void addPath(const sys::Path& path); 132185088Szec 133185088Szec /// Add a set of paths to the list of paths that the linker will search. The 134185088Szec /// Linker accumulates the set of libraries added. The \p paths will be 135185088Szec /// added to the end of the Linker's list. Order will be retained. 136105197Ssam /// @brief Add a set of paths. 137185088Szec void addPaths(const std::vector<std::string>& paths); 138185088Szec 139185088Szec /// This method augments the Linker's list of library paths with the system 140185088Szec /// paths of the host operating system, include LLVM_LIB_SEARCH_PATH. 141185088Szec /// @brief Add the system paths. 142185088Szec void addSystemPaths(); 143119643Ssam 144120585Ssam /// Control optional linker behavior by setting a group of flags. The flags 145120585Ssam /// are defined in the ControlFlags enumeration. 146120585Ssam /// @see ControlFlags 147120585Ssam /// @brief Set control flags. 148120585Ssam void setFlags(unsigned flags) { Flags = flags; } 149120585Ssam 150120585Ssam /// This method is the main interface to the linker. It can be used to 151120585Ssam /// link a set of linkage items into a module. A linkage item is either a 152119643Ssam /// file name with fully qualified path, or a library for which the Linker's 153120585Ssam /// LibraryPath will be utilized to locate the library. The bool value in 154120585Ssam /// the LinkItemKind should be set to true for libraries. This function 155120585Ssam /// allows linking to preserve the order of specification associated with 156120585Ssam /// the command line, or for other purposes. Each item will be linked in 157120585Ssam /// turn as it occurs in \p Items. 158120585Ssam /// @returns true if an error occurred, false otherwise 159120585Ssam /// @see LinkItemKind 160120585Ssam /// @see getLastError 161119643Ssam bool LinkInItems ( 162119643Ssam const ItemList& Items, ///< Set of libraries/files to link in 163120585Ssam ItemList& NativeItems ///< Output list of native files/libs 164120585Ssam ); 165120585Ssam 166120585Ssam /// This function links the bitcode \p Files into the composite module. 167120585Ssam /// Note that this does not do any linking of unresolved symbols. The \p 168120585Ssam /// Files are all completely linked into \p HeadModule regardless of 169120585Ssam /// unresolved symbols. This function just loads each bitcode file and 170119643Ssam /// calls LinkInModule on them. 171120585Ssam /// @returns true if an error occurs, false otherwise 172120585Ssam /// @see getLastError 173120585Ssam /// @brief Link in multiple files. 174120585Ssam bool LinkInFiles ( 175120585Ssam const std::vector<sys::Path> & Files ///< Files to link in 176120585Ssam ); 177120585Ssam 178119643Ssam /// This function links a single bitcode file, \p File, into the composite 179120585Ssam /// module. Note that this does not attempt to resolve symbols. This method 180120585Ssam /// just loads the bitcode file and calls LinkInModule on it. If an error 181120585Ssam /// occurs, the Linker's error string is set. 182120585Ssam /// @returns true if an error occurs, false otherwise 183120585Ssam /// @see getLastError 184120585Ssam /// @brief Link in a single file. 185120585Ssam bool LinkInFile( 186105197Ssam const sys::Path& File, ///< File to link in. 187105197Ssam bool &is_native ///< Indicates if the file is native object file 188128856Ssam ); 189105197Ssam 190105197Ssam /// This function provides a way to selectively link in a set of modules, 191128856Ssam /// found in libraries, based on the unresolved symbols in the composite 192128856Ssam /// module. Each item in \p Libraries should be the base name of a library, 193128856Ssam /// as if given with the -l option of a linker tool. The Linker's LibPaths 194185348Szec /// are searched for the \p Libraries and any found will be linked in with 195105197Ssam /// LinkInArchive. If an error occurs, the Linker's error string is set. 196105197Ssam /// @see LinkInArchive 197105197Ssam /// @see getLastError 198185348Szec /// @returns true if an error occurs, false otherwise 199105197Ssam /// @brief Link libraries into the module 200105197Ssam bool LinkInLibraries ( 201105197Ssam const std::vector<std::string> & Libraries ///< Libraries to link in 202105197Ssam ); 203105197Ssam 204105197Ssam /// This function provides a way to selectively link in a set of modules, 205105197Ssam /// found in one library, based on the unresolved symbols in the composite 206105197Ssam /// module.The \p Library should be the base name of a library, as if given 207105197Ssam /// with the -l option of a linker tool. The Linker's LibPaths are searched 208105197Ssam /// for the \p Library and if found, it will be linked in with via the 209105197Ssam /// LinkInArchive method. If an error occurs, the Linker's error string is 210105197Ssam /// set. 211105197Ssam /// @see LinkInArchive 212105197Ssam /// @see getLastError 213105197Ssam /// @returns true if an error occurs, false otherwise 214105197Ssam /// @brief Link one library into the module 215105197Ssam bool LinkInLibrary ( 216105197Ssam StringRef Library, ///< The library to link in 217105197Ssam bool& is_native ///< Indicates if lib a native library 218105197Ssam ); 219105197Ssam 220105197Ssam /// This function links one bitcode archive, \p Filename, into the module. 221105197Ssam /// The archive is searched to resolve outstanding symbols. Any modules in 222105197Ssam /// the archive that resolve outstanding symbols will be linked in. The 223105197Ssam /// library is searched repeatedly until no more modules that resolve 224105197Ssam /// symbols can be found. If an error occurs, the error string is set. 225105197Ssam /// To speed up this function, ensure the archive has been processed 226105197Ssam /// llvm-ranlib or the S option was given to llvm-ar when the archive was 227105197Ssam /// created. These tools add a symbol table to the archive which makes the 228105197Ssam /// search for undefined symbols much faster. 229105197Ssam /// @see getLastError 230105197Ssam /// @returns true if an error occurs, otherwise false. 231105197Ssam /// @brief Link in one archive. 232105197Ssam bool LinkInArchive( 233105197Ssam const sys::Path& Filename, ///< Filename of the archive to link 234105197Ssam bool& is_native ///< Indicates if archive is a native archive 235105197Ssam ); 236105197Ssam 237105197Ssam /// This method links the \p Src module into the Linker's Composite module 238105197Ssam /// by calling LinkModules. All the other LinkIn* methods eventually 239105197Ssam /// result in calling this method to link a Module into the Linker's 240105197Ssam /// composite. 241105197Ssam /// @see LinkModules 242105197Ssam /// @returns True if an error occurs, false otherwise. 243105197Ssam /// @brief Link in a module. 244105197Ssam bool LinkInModule( 245105197Ssam Module* Src, ///< Module linked into \p Dest 246105197Ssam std::string* ErrorMsg = 0 /// Error/diagnostic string 247105197Ssam ) { 248105197Ssam return LinkModules(Composite, Src, ErrorMsg ); 249105197Ssam } 250105197Ssam 251105197Ssam /// This is the heart of the linker. This method will take unconditional 252183550Szec /// control of the \p Src module and link it into the \p Dest module. The 253183550Szec /// \p Src module will be destructed or subsumed by this method. In either 254105197Ssam /// case it is not usable by the caller after this method is invoked. Only 255105197Ssam /// the \p Dest module will remain. The \p Src module is linked into the 256183550Szec /// Linker's composite module such that types, global variables, functions, 257183550Szec /// and etc. are matched and resolved. If an error occurs, this function 258105197Ssam /// returns true and ErrorMsg is set to a descriptive message about the 259105197Ssam /// error. 260183550Szec /// @returns True if an error occurs, false otherwise. 261183550Szec /// @brief Generically link two modules together. 262105197Ssam static bool LinkModules(Module* Dest, Module* Src, std::string* ErrorMsg); 263105197Ssam 264183550Szec /// This function looks through the Linker's LibPaths to find a library with 265183550Szec /// the name \p Filename. If the library cannot be found, the returned path 266105197Ssam /// will be empty (i.e. sys::Path::isEmpty() will return true). 267105197Ssam /// @returns A sys::Path to the found library 268183550Szec /// @brief Find a library from its short name. 269183550Szec sys::Path FindLib(StringRef Filename); 270105197Ssam 271105197Ssam /// @} 272183550Szec /// @name Implementation 273183550Szec /// @{ 274105197Ssam private: 275105197Ssam /// Read in and parse the bitcode file named by FN and return the 276183550Szec /// Module it contains (wrapped in an auto_ptr), or 0 if an error occurs. 277183550Szec std::auto_ptr<Module> LoadObject(const sys::Path& FN); 278105197Ssam 279105197Ssam bool warning(StringRef message); 280183550Szec bool error(StringRef message); 281183550Szec void verbose(StringRef message); 282105197Ssam 283105197Ssam /// @} 284183550Szec /// @name Data 285183550Szec /// @{ 286105197Ssam private: 287105197Ssam LLVMContext& Context; ///< The context for global information 288183550Szec Module* Composite; ///< The composite module linked together 289183550Szec std::vector<sys::Path> LibPaths; ///< The library search paths 290105197Ssam unsigned Flags; ///< Flags to control optional behavior. 291105197Ssam std::string Error; ///< Text of error that occurred. 292183550Szec std::string ProgramName; ///< Name of the program being linked 293183550Szec /// @} 294105197Ssam 295105197Ssam}; 296183550Szec 297183550Szec} // End llvm namespace 298105197Ssam 299105197Ssam#endif 300105197Ssam