Linker.h revision d25c05efd55fe190a50965b31e04db69bd8e19de
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. 34d25c05efd55fe190a50965b31e04db69bd8e19deEli Bendersky/// The Linker can link Modules from memory. It retains a set of search paths 35d25c05efd55fe190a50965b31e04db69bd8e19deEli Bendersky/// in which to find any libraries presented to it. By default, the linker 36d25c05efd55fe190a50965b31e04db69bd8e19deEli Bendersky/// will generate error and warning messages to stderr but this capability can 37d25c05efd55fe190a50965b31e04db69bd8e19deEli Bendersky/// be turned off with the QuietWarnings and QuietErrors flags. It can also be 38d25c05efd55fe190a50965b31e04db69bd8e19deEli Bendersky/// instructed to verbosely print out the linking actions it is taking with 39d25c05efd55fe190a50965b31e04db69bd8e19deEli Bendersky/// 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 enumeration is used to control various optional features of the 479769ab22265b313171d201b5928688524a01bd87Misha Brukman /// linker. 48e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer enum ControlFlags { 49275872e79950dafc6699f6502cee52f74b84a22aDaniel Dunbar Verbose = 1, ///< Print to stderr what steps the linker is taking 50275872e79950dafc6699f6502cee52f74b84a22aDaniel Dunbar QuietWarnings = 2, ///< Don't print warnings to stderr. 51275872e79950dafc6699f6502cee52f74b84a22aDaniel Dunbar QuietErrors = 4 ///< Don't print errors to stderr. 52e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer }; 53d25c05efd55fe190a50965b31e04db69bd8e19deEli Bendersky 54f1f1a4f16128ffa2910f0b1d5c7052b3697f9fcdTanya Lattner enum LinkerMode { 55f1f1a4f16128ffa2910f0b1d5c7052b3697f9fcdTanya Lattner DestroySource = 0, // Allow source module to be destroyed. 56f1f1a4f16128ffa2910f0b1d5c7052b3697f9fcdTanya Lattner PreserveSource = 1 // Preserve the source module. 57f1f1a4f16128ffa2910f0b1d5c7052b3697f9fcdTanya Lattner }; 58d25c05efd55fe190a50965b31e04db69bd8e19deEli Bendersky 59e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @} 60e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @name Constructors 61e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @{ 62e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer public: 63e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// Construct the Linker with an empty module which will be given the 64e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// name \p progname. \p progname will also be used for error messages. 65e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @brief Construct with empty module 662928c83b010f7cfdb0f819199d806f6942a7d995Daniel Dunbar Linker(StringRef progname, ///< name of tool running linker 672928c83b010f7cfdb0f819199d806f6942a7d995Daniel Dunbar StringRef modulename, ///< name of linker's end-result module 6874382b7c699120fbec5cb5603c9cf4212eb37f06Chris Lattner LLVMContext &C, ///< Context for global info 6974382b7c699120fbec5cb5603c9cf4212eb37f06Chris Lattner unsigned Flags = 0 ///< ControlFlags (one or more |'d together) 70328ead9fce26b505857234de0e3508b3372e2e6dReid Spencer ); 71e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer 72e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// Construct the Linker with a previously defined module, \p aModule. Use 73e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// \p progname for the name of the program in error messages. 74e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @brief Construct with existing module 752928c83b010f7cfdb0f819199d806f6942a7d995Daniel Dunbar Linker(StringRef progname, Module* aModule, unsigned Flags = 0); 76e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer 77e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// Destruct the Linker. 78e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @brief Destructor 79e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer ~Linker(); 80e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer 81e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @} 82e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @name Accessors 83e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @{ 84e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer public: 85e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// This method gets the composite module into which linking is being 869769ab22265b313171d201b5928688524a01bd87Misha Brukman /// done. The Composite module starts out empty and accumulates modules 87e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// linked into it via the various LinkIn* methods. This method does not 88e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// release the Module to the caller. The Linker retains ownership and will 899769ab22265b313171d201b5928688524a01bd87Misha Brukman /// destruct the Module when the Linker is destructed. 90e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @see releaseModule 91e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @brief Get the linked/composite module. 92e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer Module* getModule() const { return Composite; } 93e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer 94e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// This method releases the composite Module into which linking is being 95e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// done. Ownership of the composite Module is transferred to the caller who 969769ab22265b313171d201b5928688524a01bd87Misha Brukman /// must arrange for its destruct. After this method is called, the Linker 979769ab22265b313171d201b5928688524a01bd87Misha Brukman /// terminates the linking session for the returned Module. It will no 989769ab22265b313171d201b5928688524a01bd87Misha Brukman /// longer utilize the returned Module but instead resets itself for 999769ab22265b313171d201b5928688524a01bd87Misha Brukman /// subsequent linking as if the constructor had been called. The Linker's 1009769ab22265b313171d201b5928688524a01bd87Misha Brukman /// LibPaths and flags to be reset, and memory will be released. 1019769ab22265b313171d201b5928688524a01bd87Misha Brukman /// @brief Release the linked/composite module. 102e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer Module* releaseModule(); 103e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer 104e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// This method gets the list of libraries that form the path that the 1059769ab22265b313171d201b5928688524a01bd87Misha Brukman /// Linker will search when it is presented with a library name. 106e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @brief Get the Linkers library path 107e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer const std::vector<sys::Path>& getLibPaths() const { return LibPaths; } 108e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer 109e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// This method returns an error string suitable for printing to the user. 110e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// The return value will be empty unless an error occurred in one of the 111e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// LinkIn* methods. In those cases, the LinkIn* methods will have returned 1129769ab22265b313171d201b5928688524a01bd87Misha Brukman /// true, indicating an error occurred. At most one error is retained so 113e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// this function always returns the last error that occurred. Note that if 114e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// the Quiet control flag is not set, the error string will have already 115275872e79950dafc6699f6502cee52f74b84a22aDaniel Dunbar /// been printed to stderr. 116e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @brief Get the text of the last error that occurred. 11792ccf70ad448eb02f9f273d2c70ae4708b3bd0f2Daniel Dunbar const std::string &getLastError() const { return Error; } 118e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer 119e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @} 120e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @name Mutators 121e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @{ 122e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer public: 123e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// Add a path to the list of paths that the Linker will search. The Linker 124e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// accumulates the set of libraries added 125e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// library paths for the target platform. The standard libraries will 126e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// always be searched last. The added libraries will be searched in the 127e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// order added. 128e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @brief Add a path. 129e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer void addPath(const sys::Path& path); 130e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer 131e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// Add a set of paths to the list of paths that the linker will search. The 1329769ab22265b313171d201b5928688524a01bd87Misha Brukman /// Linker accumulates the set of libraries added. The \p paths will be 133e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// added to the end of the Linker's list. Order will be retained. 134e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @brief Add a set of paths. 135e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer void addPaths(const std::vector<std::string>& paths); 136e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer 137e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// This method augments the Linker's list of library paths with the system 138e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// paths of the host operating system, include LLVM_LIB_SEARCH_PATH. 139e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @brief Add the system paths. 140e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer void addSystemPaths(); 141e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer 142e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// Control optional linker behavior by setting a group of flags. The flags 143e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// are defined in the ControlFlags enumeration. 144e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @see ControlFlags 145e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @brief Set control flags. 146e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer void setFlags(unsigned flags) { Flags = flags; } 147e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer 148e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// This method links the \p Src module into the Linker's Composite module 149d25c05efd55fe190a50965b31e04db69bd8e19deEli Bendersky /// by calling LinkModules. 150e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @see LinkModules 151e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @returns True if an error occurs, false otherwise. 152e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @brief Link in a module. 153e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer bool LinkInModule( 1544952143236afe43b974798c45ed265bb175c9d7fReid Spencer Module* Src, ///< Module linked into \p Dest 1554952143236afe43b974798c45ed265bb175c9d7fReid Spencer std::string* ErrorMsg = 0 /// Error/diagnostic string 156d25c05efd55fe190a50965b31e04db69bd8e19deEli Bendersky ) { 157d25c05efd55fe190a50965b31e04db69bd8e19deEli Bendersky return LinkModules(Composite, Src, Linker::DestroySource, ErrorMsg); 1582803b4cc581af06bf99af5ddc3353836c63d1562Reid Spencer } 159e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer 1609769ab22265b313171d201b5928688524a01bd87Misha Brukman /// This is the heart of the linker. This method will take unconditional 161e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// control of the \p Src module and link it into the \p Dest module. The 162e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// \p Src module will be destructed or subsumed by this method. In either 163e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// case it is not usable by the caller after this method is invoked. Only 1649769ab22265b313171d201b5928688524a01bd87Misha Brukman /// the \p Dest module will remain. The \p Src module is linked into the 165e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// Linker's composite module such that types, global variables, functions, 166e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// and etc. are matched and resolved. If an error occurs, this function 167e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// returns true and ErrorMsg is set to a descriptive message about the 168e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// error. 169e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @returns True if an error occurs, false otherwise. 170e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @brief Generically link two modules together. 171f1f1a4f16128ffa2910f0b1d5c7052b3697f9fcdTanya Lattner static bool LinkModules(Module* Dest, Module* Src, unsigned Mode, 172f1f1a4f16128ffa2910f0b1d5c7052b3697f9fcdTanya Lattner std::string* ErrorMsg); 173e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer 174e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @} 175e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @name Implementation 176e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @{ 177e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer private: 1782928c83b010f7cfdb0f819199d806f6942a7d995Daniel Dunbar bool warning(StringRef message); 1792928c83b010f7cfdb0f819199d806f6942a7d995Daniel Dunbar bool error(StringRef message); 1802928c83b010f7cfdb0f819199d806f6942a7d995Daniel Dunbar void verbose(StringRef message); 181e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer 182e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @} 183e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @name Data 184e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @{ 185e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer private: 1864434ed44c45c87a72b7a0bf2f91211f895022b91Owen Anderson LLVMContext& Context; ///< The context for global information 187e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer Module* Composite; ///< The composite module linked together 188e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer std::vector<sys::Path> LibPaths; ///< The library search paths 189e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer unsigned Flags; ///< Flags to control optional behavior. 190e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer std::string Error; ///< Text of error that occurred. 191e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer std::string ProgramName; ///< Name of the program being linked 192e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer /// @} 1939769ab22265b313171d201b5928688524a01bd87Misha Brukman 194e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer}; 195e5caf877e9355ba68cfb6d995e0b1a2b2a466288Reid Spencer 196d0fde30ce850b78371fd1386338350591f9ff494Brian Gaeke} // End llvm namespace 197d0fde30ce850b78371fd1386338350591f9ff494Brian Gaeke 1981166b00316761df873db882c7212133f9b074d41Chris Lattner#endif 199