include/llvm/Linker.h

   1 //===- llvm/Linker.h - Module Linker Interface ------------------*- C++ -*-===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file was developed by Reid Spencer and is distributed under the
   6 // University of Illinois Open Source License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9 //
  10 // This file defines the interface to the module/file/archive linker.
  11 //
  12 //===----------------------------------------------------------------------===//
  13
  14 #ifndef LLVM_LINKER_H
  15 #define LLVM_LINKER_H
  16
  17 #include "llvm/Support/CommandLine.h"
  18 #include <string>
  19 #include <vector>
  20 #include <set>
  21
  22 namespace llvm {
  23
  24 class Module;
  25
  26 /// This type is used to pass the linkage items (libraries and files) to
  27 /// the LinkItems function. It is composed of string/bool pairs. The string
  28 /// provides the name of the file or library (as with the -l option). The bool
  29 /// should be true for libraries, false for files, signifying "isLibrary".
  30 /// @brief A list of string/bool pairs
  31 typedef std::vector<std::pair<std::string,bool> > LinkItemList;
  32
  33 /// This function can be used to link a set of linkage items into a module. A
  34 /// linkage item is one of the three things identified by the LinkItemKind
  35 /// enumeration. This function allows linking to preserve the order of
  36 /// specification associated with a command line, or for other purposes. Each
  37 /// item will be linked in turn as it occurs in \p Items. Note that library
  38 /// path items will only be in effect after they have been processed.
  39 /// @returns The aggregated/linked Module.
  40 /// @throws nothing
  41 Module* LinkItems (
  42   const char * progname,   ///< Name of the program being linked (for output)
  43   const LinkItemList& Items, // Set of libraries/files to link in
  44   const std::vector<std::string>& LibPaths, // Paths to search for libraries
  45   bool Verbose, ///< Link verbosely, indicating each action
  46   bool Native ///< Linking is for a native executable
  47 );
  48
  49 /// This function provides some utility for tools that need to build the list
  50 /// of link items from a triplet of command line options: Files, Libraries, and
  51 /// LibraryPaths. The command line ordering is preserved by this function even
  52 /// though the options are split into three separate cl::list<std::string>. The
  53 /// resulting \p OutList is suitable for use with LinkItems.
  54 /// @see LinkItems
  55 /// @throws nothing
  56 void BuildLinkItems(
  57   LinkItemList& OutList,
  58   const cl::list<std::string>& Files, ///< List of files to put in list
  59   const cl::list<std::string>& Libs   ///< List of libraries to put in list
  60 );
  61
  62 /// This is the heart of the linker. The \p Src module is linked into the \p
  63 /// Dest module. If an error occurs, true is returned, otherwise false. If \p
  64 /// ErrorMsg is not null and an error occurs, \p *ErrorMsg will be set to a
  65 /// readable string that indicates the nature of the error.  Note that this can
  66 /// destroy the Src module in arbitrary ways.
  67 ///
  68 /// @returns true if there's an error
  69 /// @brief Link two modules together
  70 bool LinkModules(
  71   Module* Dest,          ///< Module into which \p Src is linked
  72   Module* Src,     ///< Module linked into \p Dest
  73   std::string* ErrorMsg  ///< Optional error message string
  74 );
  75
  76 /// This function links the bytecode \p Files into the \p HeadModule. Note that
  77 /// this does not do any linking of unresolved symbols. The \p Files are all
  78 /// completely linked into \p HeadModule regardless of unresolved symbols. This
  79 /// function just loads each bytecode file and calls LinkModules on them.
  80 /// @returns true if an error occurs, false otherwise
  81 bool LinkFiles (
  82   const char * progname, ///< Name of the program being linked (for output)
  83   Module * HeadModule,   ///< Main (resulting) module to be linked into
  84   const std::vector<std::string> & Files, ///< Files to link in
  85   bool Verbose ///< Link verbosely, indicating each action
  86 );
  87
  88 /// This function links one archive, \p Filename,  that contains bytecode into
  89 /// \p HeadModule.  If an error occurs, true is returned, otherwise false. If
  90 /// \p ErrorMsg is not null and an error occurs, \p *ErrorMsg will be set to a
  91 /// readable string that indicates the nature of the error.
  92 /// @returns true if there's an error
  93 /// @brief Link in one archive.
  94 bool LinkInArchive(
  95   Module* HeadModule,          ///< Main (resulting) module to be linked into
  96   const std::string& Filename, ///< Filename of the archive to link
  97   std::string* ErrorMsg,       ///< Error message if an error occurs.
  98   bool Verbose                 ///< Link verbosely, indicating each action
  99 );
 100
 101 /// This function provides the ability to handle the -L and -l options on a
 102 /// linker's command line. It will link into \p HeadModule any modules found in
 103 /// the \p Libraries (which might be found in the \p LibPaths).
 104 /// @brief Link libraries into a module
 105 void LinkLibraries (
 106   const char * progname,   ///< Name of the program being linked (for output)
 107   Module* HeadModule,      ///< Main (resulting) module to be linked into
 108   const std::vector<std::string> & Libraries, ///< Set of libraries to link in
 109   const std::vector<std::string> & LibPaths,  ///< Set of library paths
 110   bool Verbose, ///< Link verbosely, indicating each action
 111   bool Native ///< Linking is for a native executable
 112 );
 113
 114 /// This function looks at Module \p M and returns a set of strings,
 115 /// \p DefinedSymbols, that is the publicly visible defined symbols in
 116 /// module \p M.
 117 void GetAllDefinedSymbols (Module *M, std::set<std::string> &DefinedSymbols);
 118
 119 /// This function looks at Module \p M and returns a set of strings,
 120 /// \p UnefinedSymbols, that is the publicly visible undefined symbols in
 121 /// module \p M.
 122 void GetAllUndefinedSymbols(Module *M, std::set<std::string> &UndefinedSymbols);
 123
 124 /// This function looks through a set of \p Paths to find a library with the
 125 /// name \p Filename. If \p SharedObjectOnly is true, it only finds a match
 126 /// if the file is a shared library.
 127 std::string FindLib(const std::string &Filename,
 128                     const std::vector<std::string> &Paths,
 129                     bool SharedObjectOnly = false);
 130
 131 } // End llvm namespace
 132
 133 #endif