LLVM API Documentation
00001 //===- llvm/Linker.h - Module Linker Interface ------------------*- C++ -*-===// 00002 // 00003 // The LLVM Compiler Infrastructure 00004 // 00005 // This file was developed by Reid Spencer and is distributed under the 00006 // University of Illinois Open Source License. See LICENSE.TXT for details. 00007 // 00008 //===----------------------------------------------------------------------===// 00009 // 00010 // This file defines the interface to the module/file/archive linker. 00011 // 00012 //===----------------------------------------------------------------------===// 00013 00014 #ifndef LLVM_LINKER_H 00015 #define LLVM_LINKER_H 00016 00017 #include "llvm/Support/CommandLine.h" 00018 #include <string> 00019 #include <vector> 00020 #include <set> 00021 00022 namespace llvm { 00023 00024 class Module; 00025 00026 /// This type is used to pass the linkage items (libraries and files) to 00027 /// the LinkItems function. It is composed of string/bool pairs. The string 00028 /// provides the name of the file or library (as with the -l option). The bool 00029 /// should be true for libraries, false for files, signifying "isLibrary". 00030 /// @brief A list of string/bool pairs 00031 typedef std::vector<std::pair<std::string,bool> > LinkItemList; 00032 00033 /// This function can be used to link a set of linkage items into a module. A 00034 /// linkage item is one of the three things identified by the LinkItemKind 00035 /// enumeration. This function allows linking to preserve the order of 00036 /// specification associated with a command line, or for other purposes. Each 00037 /// item will be linked in turn as it occurs in \p Items. Note that library 00038 /// path items will only be in effect after they have been processed. 00039 /// @returns The aggregated/linked Module. 00040 /// @throws nothing 00041 Module* LinkItems ( 00042 const char * progname, ///< Name of the program being linked (for output) 00043 const LinkItemList& Items, // Set of libraries/files to link in 00044 const std::vector<std::string>& LibPaths, // Paths to search for libraries 00045 bool Verbose, ///< Link verbosely, indicating each action 00046 bool Native ///< Linking is for a native executable 00047 ); 00048 00049 /// This function provides some utility for tools that need to build the list 00050 /// of link items from a triplet of command line options: Files, Libraries, and 00051 /// LibraryPaths. The command line ordering is preserved by this function even 00052 /// though the options are split into three separate cl::list<std::string>. The 00053 /// resulting \p OutList is suitable for use with LinkItems. 00054 /// @see LinkItems 00055 /// @throws nothing 00056 void BuildLinkItems( 00057 LinkItemList& OutList, 00058 const cl::list<std::string>& Files, ///< List of files to put in list 00059 const cl::list<std::string>& Libs ///< List of libraries to put in list 00060 ); 00061 00062 /// This is the heart of the linker. The \p Src module is linked into the \p 00063 /// Dest module. If an error occurs, true is returned, otherwise false. If \p 00064 /// ErrorMsg is not null and an error occurs, \p *ErrorMsg will be set to a 00065 /// readable string that indicates the nature of the error. Note that this can 00066 /// destroy the Src module in arbitrary ways. 00067 /// 00068 /// @returns true if there's an error 00069 /// @brief Link two modules together 00070 bool LinkModules( 00071 Module* Dest, ///< Module into which \p Src is linked 00072 Module* Src, ///< Module linked into \p Dest 00073 std::string* ErrorMsg ///< Optional error message string 00074 ); 00075 00076 /// This function links the bytecode \p Files into the \p HeadModule. Note that 00077 /// this does not do any linking of unresolved symbols. The \p Files are all 00078 /// completely linked into \p HeadModule regardless of unresolved symbols. This 00079 /// function just loads each bytecode file and calls LinkModules on them. 00080 /// @returns true if an error occurs, false otherwise 00081 bool LinkFiles ( 00082 const char * progname, ///< Name of the program being linked (for output) 00083 Module * HeadModule, ///< Main (resulting) module to be linked into 00084 const std::vector<std::string> & Files, ///< Files to link in 00085 bool Verbose ///< Link verbosely, indicating each action 00086 ); 00087 00088 /// This function links one archive, \p Filename, that contains bytecode into 00089 /// \p HeadModule. If an error occurs, true is returned, otherwise false. If 00090 /// \p ErrorMsg is not null and an error occurs, \p *ErrorMsg will be set to a 00091 /// readable string that indicates the nature of the error. 00092 /// @returns true if there's an error 00093 /// @brief Link in one archive. 00094 bool LinkInArchive( 00095 Module* HeadModule, ///< Main (resulting) module to be linked into 00096 const std::string& Filename, ///< Filename of the archive to link 00097 std::string* ErrorMsg, ///< Error message if an error occurs. 00098 bool Verbose ///< Link verbosely, indicating each action 00099 ); 00100 00101 /// This function provides the ability to handle the -L and -l options on a 00102 /// linker's command line. It will link into \p HeadModule any modules found in 00103 /// the \p Libraries (which might be found in the \p LibPaths). 00104 /// @brief Link libraries into a module 00105 void LinkLibraries ( 00106 const char * progname, ///< Name of the program being linked (for output) 00107 Module* HeadModule, ///< Main (resulting) module to be linked into 00108 const std::vector<std::string> & Libraries, ///< Set of libraries to link in 00109 const std::vector<std::string> & LibPaths, ///< Set of library paths 00110 bool Verbose, ///< Link verbosely, indicating each action 00111 bool Native ///< Linking is for a native executable 00112 ); 00113 00114 /// This function looks at Module \p M and returns a set of strings, 00115 /// \p DefinedSymbols, that is the publicly visible defined symbols in 00116 /// module \p M. 00117 void GetAllDefinedSymbols (Module *M, std::set<std::string> &DefinedSymbols); 00118 00119 /// This function looks at Module \p M and returns a set of strings, 00120 /// \p UnefinedSymbols, that is the publicly visible undefined symbols in 00121 /// module \p M. 00122 void GetAllUndefinedSymbols(Module *M, std::set<std::string> &UndefinedSymbols); 00123 00124 /// This function looks through a set of \p Paths to find a library with the 00125 /// name \p Filename. If \p SharedObjectOnly is true, it only finds a match 00126 /// if the file is a shared library. 00127 std::string FindLib(const std::string &Filename, 00128 const std::vector<std::string> &Paths, 00129 bool SharedObjectOnly = false); 00130 00131 } // End llvm namespace 00132 00133 #endif