Linker.h revision f1d0f7781e766df878bec4e7977fa3204374f394
17d0a022489b56220c365d00aed23bf8ad9983108Reid Spencer//===- llvm/Linker.h - Module Linker Interface ------------------*- C++ -*-===// 29769ab22265b313171d201b5928688524a01bd87Misha Brukman// 36fbcc26f1460eaee4e0eb8b426fc1ff0c7af11beJohn Criswell// The LLVM Compiler Infrastructure 46fbcc26f1460eaee4e0eb8b426fc1ff0c7af11beJohn Criswell// 57ed47a13356daed2a34cd2209a31f92552e3bdd8Chris Lattner// This file is distributed under the University of Illinois Open Source 67ed47a13356daed2a34cd2209a31f92552e3bdd8Chris Lattner// License. See LICENSE.TXT for details. 79769ab22265b313171d201b5928688524a01bd87Misha Brukman// 86fbcc26f1460eaee4e0eb8b426fc1ff0c7af11beJohn Criswell//===----------------------------------------------------------------------===// 91166b00316761df873db882c7212133f9b074d41Chris Lattner// 1056ae5185ae249cd74712aca6953217b16468ef6eReid Spencer// This file defines the interface to the module/file/archive linker. 111166b00316761df873db882c7212133f9b074d41Chris Lattner// 121166b00316761df873db882c7212133f9b074d41Chris Lattner//===----------------------------------------------------------------------===// 131166b00316761df873db882c7212133f9b074d41Chris Lattner 147d0a022489b56220c365d00aed23bf8ad9983108Reid Spencer#ifndef LLVM_LINKER_H 157d0a022489b56220c365d00aed23bf8ad9983108Reid Spencer#define LLVM_LINKER_H 161166b00316761df873db882c7212133f9b074d41Chris Lattner 174c4e12fb1f9be1bf75360dd8178a3ae074cc8e49Duraid Madina#include <memory> 18f1d0f7781e766df878bec4e7977fa3204374f394Craig Topper#include <string> 19630fcb86785f96501126e52009619b475403dc62Misha Brukman#include <vector> 20d0fde30ce850b78371fd1386338350591f9ff494Brian Gaeke 21d0fde30ce850b78371fd1386338350591f9ff494Brian Gaekenamespace llvm { 2274382b7c699120fbec5cb5603c9cf4212eb37f06Chris Lattner namespace sys { class Path; } 23d0fde30ce850b78371fd1386338350591f9ff494Brian Gaeke 241166b00316761df873db882c7212133f9b074d41Chris Lattnerclass Module; 2512ddd409535b52a7fa5157ded9a4cedd161fedb6Benjamin Kramerclass LLVMContext; 26f1d0f7781e766df878bec4e7977fa3204374f394Craig Topperclass StringRef; 274321ded265a20cb62fa5a99918dfc7d227094b8eVikram S. Adve 28e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer/// This class provides the core functionality of linking in LLVM. It retains a 299769ab22265b313171d201b5928688524a01bd87Misha Brukman/// Module object which is the composite of the modules and libraries linked 309769ab22265b313171d201b5928688524a01bd87Misha Brukman/// into it. The composite Module can be retrieved via the getModule() method. 319769ab22265b313171d201b5928688524a01bd87Misha Brukman/// In this case the Linker still retains ownership of the Module. If the 329769ab22265b313171d201b5928688524a01bd87Misha Brukman/// releaseModule() method is used, the ownership of the Module is transferred 33e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer/// to the caller and the Linker object is only suitable for destruction. 34a99be51bf5cdac1438069d4b01766c47704961c8Gabor Greif/// The Linker can link Modules from memory, bitcode files, or bitcode 359769ab22265b313171d201b5928688524a01bd87Misha Brukman/// archives. It retains a set of search paths in which to find any libraries 369769ab22265b313171d201b5928688524a01bd87Misha Brukman/// presented to it. By default, the linker will generate error and warning 37275872e79950dafc6699f6502cee52f74b84a22aDaniel Dunbar/// messages to stderr but this capability can be turned off with the 38e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer/// QuietWarnings and QuietErrors flags. It can also be instructed to verbosely 39e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer/// print out the linking actions it is taking with the Verbose flag. 40e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer/// @brief The LLVM Linker. 41e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencerclass Linker { 42e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer 43e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @name Types 44e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @{ 45e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer public: 46e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// This type is used to pass the linkage items (libraries and files) to 47e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// the LinkItems function. It is composed of string/bool pairs. The string 489769ab22265b313171d201b5928688524a01bd87Misha Brukman /// provides the name of the file or library (as with the -l option). The 499769ab22265b313171d201b5928688524a01bd87Misha Brukman /// bool should be true for libraries and false for files, signifying 50e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// "isLibrary". 51e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @brief A list of linkage items 52e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer typedef std::vector<std::pair<std::string,bool> > ItemList; 53e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer 54e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// This enumeration is used to control various optional features of the 559769ab22265b313171d201b5928688524a01bd87Misha Brukman /// linker. 56e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer enum ControlFlags { 57275872e79950dafc6699f6502cee52f74b84a22aDaniel Dunbar Verbose = 1, ///< Print to stderr what steps the linker is taking 58275872e79950dafc6699f6502cee52f74b84a22aDaniel Dunbar QuietWarnings = 2, ///< Don't print warnings to stderr. 59275872e79950dafc6699f6502cee52f74b84a22aDaniel Dunbar QuietErrors = 4 ///< Don't print errors to stderr. 60e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer }; 61f1f1a4f16128ffa2910f0b1d5c7052b3697f9fcdTanya Lattner 62f1f1a4f16128ffa2910f0b1d5c7052b3697f9fcdTanya Lattner enum LinkerMode { 63f1f1a4f16128ffa2910f0b1d5c7052b3697f9fcdTanya Lattner DestroySource = 0, // Allow source module to be destroyed. 64f1f1a4f16128ffa2910f0b1d5c7052b3697f9fcdTanya Lattner PreserveSource = 1 // Preserve the source module. 65f1f1a4f16128ffa2910f0b1d5c7052b3697f9fcdTanya Lattner }; 66f1f1a4f16128ffa2910f0b1d5c7052b3697f9fcdTanya Lattner 67e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @} 68e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @name Constructors 69e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @{ 70e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer public: 71e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// Construct the Linker with an empty module which will be given the 72e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// name \p progname. \p progname will also be used for error messages. 73e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @brief Construct with empty module 742928c83b010f7cfdb0f819199d806f6942a7d995Daniel Dunbar Linker(StringRef progname, ///< name of tool running linker 752928c83b010f7cfdb0f819199d806f6942a7d995Daniel Dunbar StringRef modulename, ///< name of linker's end-result module 7674382b7c699120fbec5cb5603c9cf4212eb37f06Chris Lattner LLVMContext &C, ///< Context for global info 7774382b7c699120fbec5cb5603c9cf4212eb37f06Chris Lattner unsigned Flags = 0 ///< ControlFlags (one or more |'d together) 78328ead9fce26b505857234de0e3508b3372e2e6dReid Spencer ); 79e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer 80e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// Construct the Linker with a previously defined module, \p aModule. Use 81e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// \p progname for the name of the program in error messages. 82e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @brief Construct with existing module 832928c83b010f7cfdb0f819199d806f6942a7d995Daniel Dunbar Linker(StringRef progname, Module* aModule, unsigned Flags = 0); 84e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer 85e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// Destruct the Linker. 86e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @brief Destructor 87e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer ~Linker(); 88e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer 89e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @} 90e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @name Accessors 91e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @{ 92e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer public: 93e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// This method gets the composite module into which linking is being 949769ab22265b313171d201b5928688524a01bd87Misha Brukman /// done. The Composite module starts out empty and accumulates modules 95e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// linked into it via the various LinkIn* methods. This method does not 96e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// release the Module to the caller. The Linker retains ownership and will 979769ab22265b313171d201b5928688524a01bd87Misha Brukman /// destruct the Module when the Linker is destructed. 98e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @see releaseModule 99e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @brief Get the linked/composite module. 100e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer Module* getModule() const { return Composite; } 101e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer 102e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// This method releases the composite Module into which linking is being 103e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// done. Ownership of the composite Module is transferred to the caller who 1049769ab22265b313171d201b5928688524a01bd87Misha Brukman /// must arrange for its destruct. After this method is called, the Linker 1059769ab22265b313171d201b5928688524a01bd87Misha Brukman /// terminates the linking session for the returned Module. It will no 1069769ab22265b313171d201b5928688524a01bd87Misha Brukman /// longer utilize the returned Module but instead resets itself for 1079769ab22265b313171d201b5928688524a01bd87Misha Brukman /// subsequent linking as if the constructor had been called. The Linker's 1089769ab22265b313171d201b5928688524a01bd87Misha Brukman /// LibPaths and flags to be reset, and memory will be released. 1099769ab22265b313171d201b5928688524a01bd87Misha Brukman /// @brief Release the linked/composite module. 110e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer Module* releaseModule(); 111e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer 112e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// This method gets the list of libraries that form the path that the 1139769ab22265b313171d201b5928688524a01bd87Misha Brukman /// Linker will search when it is presented with a library name. 114e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @brief Get the Linkers library path 115e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer const std::vector<sys::Path>& getLibPaths() const { return LibPaths; } 116e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer 117e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// This method returns an error string suitable for printing to the user. 118e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// The return value will be empty unless an error occurred in one of the 119e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// LinkIn* methods. In those cases, the LinkIn* methods will have returned 1209769ab22265b313171d201b5928688524a01bd87Misha Brukman /// true, indicating an error occurred. At most one error is retained so 121e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// this function always returns the last error that occurred. Note that if 122e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// the Quiet control flag is not set, the error string will have already 123275872e79950dafc6699f6502cee52f74b84a22aDaniel Dunbar /// been printed to stderr. 124e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @brief Get the text of the last error that occurred. 12592ccf70ad448eb02f9f273d2c70ae4708b3bd0f2Daniel Dunbar const std::string &getLastError() const { return Error; } 126e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer 127e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @} 128e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @name Mutators 129e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @{ 130e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer public: 131e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// Add a path to the list of paths that the Linker will search. The Linker 132e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// accumulates the set of libraries added 133e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// library paths for the target platform. The standard libraries will 134e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// always be searched last. The added libraries will be searched in the 135e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// order added. 136e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @brief Add a path. 137e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer void addPath(const sys::Path& path); 138e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer 139e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// Add a set of paths to the list of paths that the linker will search. The 1409769ab22265b313171d201b5928688524a01bd87Misha Brukman /// Linker accumulates the set of libraries added. The \p paths will be 141e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// added to the end of the Linker's list. Order will be retained. 142e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @brief Add a set of paths. 143e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer void addPaths(const std::vector<std::string>& paths); 144e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer 145e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// This method augments the Linker's list of library paths with the system 146e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// paths of the host operating system, include LLVM_LIB_SEARCH_PATH. 147e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @brief Add the system paths. 148e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer void addSystemPaths(); 149e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer 150e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// Control optional linker behavior by setting a group of flags. The flags 151e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// are defined in the ControlFlags enumeration. 152e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @see ControlFlags 153e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @brief Set control flags. 154e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer void setFlags(unsigned flags) { Flags = flags; } 155e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer 1569769ab22265b313171d201b5928688524a01bd87Misha Brukman /// This method is the main interface to the linker. It can be used to 157e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// link a set of linkage items into a module. A linkage item is either a 158e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// file name with fully qualified path, or a library for which the Linker's 159e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// LibraryPath will be utilized to locate the library. The bool value in 1609769ab22265b313171d201b5928688524a01bd87Misha Brukman /// the LinkItemKind should be set to true for libraries. This function 1619769ab22265b313171d201b5928688524a01bd87Misha Brukman /// allows linking to preserve the order of specification associated with 1629769ab22265b313171d201b5928688524a01bd87Misha Brukman /// the command line, or for other purposes. Each item will be linked in 1639769ab22265b313171d201b5928688524a01bd87Misha Brukman /// turn as it occurs in \p Items. 164e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @returns true if an error occurred, false otherwise 165e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @see LinkItemKind 166e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @see getLastError 167e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer bool LinkInItems ( 168f4484f3e16e19377af27f062ca8a0450616d319aReid Spencer const ItemList& Items, ///< Set of libraries/files to link in 169f4484f3e16e19377af27f062ca8a0450616d319aReid Spencer ItemList& NativeItems ///< Output list of native files/libs 170e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer ); 171e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer 172a99be51bf5cdac1438069d4b01766c47704961c8Gabor Greif /// This function links the bitcode \p Files into the composite module. 1739769ab22265b313171d201b5928688524a01bd87Misha Brukman /// Note that this does not do any linking of unresolved symbols. The \p 1749769ab22265b313171d201b5928688524a01bd87Misha Brukman /// Files are all completely linked into \p HeadModule regardless of 175a99be51bf5cdac1438069d4b01766c47704961c8Gabor Greif /// unresolved symbols. This function just loads each bitcode file and 1769769ab22265b313171d201b5928688524a01bd87Misha Brukman /// calls LinkInModule on them. 177e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @returns true if an error occurs, false otherwise 178e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @see getLastError 179e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @brief Link in multiple files. 180e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer bool LinkInFiles ( 181e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer const std::vector<sys::Path> & Files ///< Files to link in 182e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer ); 183e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer 184a99be51bf5cdac1438069d4b01766c47704961c8Gabor Greif /// This function links a single bitcode file, \p File, into the composite 185e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// module. Note that this does not attempt to resolve symbols. This method 186a99be51bf5cdac1438069d4b01766c47704961c8Gabor Greif /// just loads the bitcode file and calls LinkInModule on it. If an error 187e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// occurs, the Linker's error string is set. 188e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @returns true if an error occurs, false otherwise 189e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @see getLastError 190e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @brief Link in a single file. 191e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer bool LinkInFile( 19258de5571817e08c05c7ef22a1d9146b84773e800Reid Spencer const sys::Path& File, ///< File to link in. 19358de5571817e08c05c7ef22a1d9146b84773e800Reid Spencer bool &is_native ///< Indicates if the file is native object file 194e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer ); 195e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer 1969769ab22265b313171d201b5928688524a01bd87Misha Brukman /// This function provides a way to selectively link in a set of modules, 1979769ab22265b313171d201b5928688524a01bd87Misha Brukman /// found in libraries, based on the unresolved symbols in the composite 198e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// module. Each item in \p Libraries should be the base name of a library, 199e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// as if given with the -l option of a linker tool. The Linker's LibPaths 2009769ab22265b313171d201b5928688524a01bd87Misha Brukman /// are searched for the \p Libraries and any found will be linked in with 201e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// LinkInArchive. If an error occurs, the Linker's error string is set. 202e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @see LinkInArchive 203e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @see getLastError 204e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @returns true if an error occurs, false otherwise 205e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @brief Link libraries into the module 206e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer bool LinkInLibraries ( 207e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer const std::vector<std::string> & Libraries ///< Libraries to link in 208e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer ); 209e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer 2109769ab22265b313171d201b5928688524a01bd87Misha Brukman /// This function provides a way to selectively link in a set of modules, 211e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// found in one library, based on the unresolved symbols in the composite 2129769ab22265b313171d201b5928688524a01bd87Misha Brukman /// module.The \p Library should be the base name of a library, as if given 213e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// with the -l option of a linker tool. The Linker's LibPaths are searched 214181b6c9cb5def44658d15848e34c5c45d973f065Reid Spencer /// for the \p Library and if found, it will be linked in with via the 215e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// LinkInArchive method. If an error occurs, the Linker's error string is 216e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// set. 217e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @see LinkInArchive 218e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @see getLastError 219e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @returns true if an error occurs, false otherwise 220e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @brief Link one library into the module 221e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer bool LinkInLibrary ( 2222928c83b010f7cfdb0f819199d806f6942a7d995Daniel Dunbar StringRef Library, ///< The library to link in 2232928c83b010f7cfdb0f819199d806f6942a7d995Daniel Dunbar bool& is_native ///< Indicates if lib a native library 224e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer ); 225e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer 226a99be51bf5cdac1438069d4b01766c47704961c8Gabor Greif /// This function links one bitcode archive, \p Filename, into the module. 2279769ab22265b313171d201b5928688524a01bd87Misha Brukman /// The archive is searched to resolve outstanding symbols. Any modules in 2289769ab22265b313171d201b5928688524a01bd87Misha Brukman /// the archive that resolve outstanding symbols will be linked in. The 2299769ab22265b313171d201b5928688524a01bd87Misha Brukman /// library is searched repeatedly until no more modules that resolve 230e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// symbols can be found. If an error occurs, the error string is set. 231f451cb870efcf9e0302d25ed05f4cac6bb494e42Dan Gohman /// To speed up this function, ensure the archive has been processed 232e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// llvm-ranlib or the S option was given to llvm-ar when the archive was 233e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// created. These tools add a symbol table to the archive which makes the 234e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// search for undefined symbols much faster. 235e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @see getLastError 2369769ab22265b313171d201b5928688524a01bd87Misha Brukman /// @returns true if an error occurs, otherwise false. 237e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @brief Link in one archive. 2389769ab22265b313171d201b5928688524a01bd87Misha Brukman bool LinkInArchive( 239c9a83e4f19519e19469efa0ed39d81ed60b94401Reid Spencer const sys::Path& Filename, ///< Filename of the archive to link 240c9a83e4f19519e19469efa0ed39d81ed60b94401Reid Spencer bool& is_native ///< Indicates if archive is a native archive 241e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer ); 242e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer 243e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// This method links the \p Src module into the Linker's Composite module 2449769ab22265b313171d201b5928688524a01bd87Misha Brukman /// by calling LinkModules. All the other LinkIn* methods eventually 2459769ab22265b313171d201b5928688524a01bd87Misha Brukman /// result in calling this method to link a Module into the Linker's 2469769ab22265b313171d201b5928688524a01bd87Misha Brukman /// composite. 247e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @see LinkModules 248e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @returns True if an error occurs, false otherwise. 249e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @brief Link in a module. 250e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer bool LinkInModule( 2514952143236afe43b974798c45ed265bb175c9d7fReid Spencer Module* Src, ///< Module linked into \p Dest 2524952143236afe43b974798c45ed265bb175c9d7fReid Spencer std::string* ErrorMsg = 0 /// Error/diagnostic string 2532803b4cc581af06bf99af5ddc3353836c63d1562Reid Spencer ) { 254f1f1a4f16128ffa2910f0b1d5c7052b3697f9fcdTanya Lattner return LinkModules(Composite, Src, Linker::DestroySource, ErrorMsg ); 2552803b4cc581af06bf99af5ddc3353836c63d1562Reid Spencer } 256e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer 2579769ab22265b313171d201b5928688524a01bd87Misha Brukman /// This is the heart of the linker. This method will take unconditional 258e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// control of the \p Src module and link it into the \p Dest module. The 259e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// \p Src module will be destructed or subsumed by this method. In either 260e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// case it is not usable by the caller after this method is invoked. Only 2619769ab22265b313171d201b5928688524a01bd87Misha Brukman /// the \p Dest module will remain. The \p Src module is linked into the 262e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// Linker's composite module such that types, global variables, functions, 263e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// and etc. are matched and resolved. If an error occurs, this function 264e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// returns true and ErrorMsg is set to a descriptive message about the 265e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// error. 266e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @returns True if an error occurs, false otherwise. 267e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @brief Generically link two modules together. 268f1f1a4f16128ffa2910f0b1d5c7052b3697f9fcdTanya Lattner static bool LinkModules(Module* Dest, Module* Src, unsigned Mode, 269f1f1a4f16128ffa2910f0b1d5c7052b3697f9fcdTanya Lattner std::string* ErrorMsg); 270e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer 271e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// This function looks through the Linker's LibPaths to find a library with 272e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// the name \p Filename. If the library cannot be found, the returned path 273e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// will be empty (i.e. sys::Path::isEmpty() will return true). 274e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @returns A sys::Path to the found library 275e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @brief Find a library from its short name. 2762928c83b010f7cfdb0f819199d806f6942a7d995Daniel Dunbar sys::Path FindLib(StringRef Filename); 277e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer 278e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @} 279e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @name Implementation 280e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @{ 281e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer private: 282a99be51bf5cdac1438069d4b01766c47704961c8Gabor Greif /// Read in and parse the bitcode file named by FN and return the 283e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// Module it contains (wrapped in an auto_ptr), or 0 if an error occurs. 284e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer std::auto_ptr<Module> LoadObject(const sys::Path& FN); 285e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer 2862928c83b010f7cfdb0f819199d806f6942a7d995Daniel Dunbar bool warning(StringRef message); 2872928c83b010f7cfdb0f819199d806f6942a7d995Daniel Dunbar bool error(StringRef message); 2882928c83b010f7cfdb0f819199d806f6942a7d995Daniel Dunbar void verbose(StringRef message); 289e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer 290e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @} 291e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @name Data 292e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @{ 293e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer private: 2944434ed44c45c87a72b7a0bf2f91211f895022b91Owen Anderson LLVMContext& Context; ///< The context for global information 295e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer Module* Composite; ///< The composite module linked together 296e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer std::vector<sys::Path> LibPaths; ///< The library search paths 297e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer unsigned Flags; ///< Flags to control optional behavior. 298e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer std::string Error; ///< Text of error that occurred. 299e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer std::string ProgramName; ///< Name of the program being linked 300e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @} 3019769ab22265b313171d201b5928688524a01bd87Misha Brukman 302e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer}; 303e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer 304d0fde30ce850b78371fd1386338350591f9ff494Brian Gaeke} // End llvm namespace 305d0fde30ce850b78371fd1386338350591f9ff494Brian Gaeke 3061166b00316761df873db882c7212133f9b074d41Chris Lattner#endif 307