LLVM API Documentation

Main Page | Namespace List | Class Hierarchy | Alphabetical List | Class List | Directories | File List | Namespace Members | Class Members | File Members | Related Pages

Linker.h

Go to the documentation of this file.
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