include/llvm/Linker.h

   1 //===- llvm/Linker.h - Module Linker Interface ------------------*- C++ -*-===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file is distributed under the University of Illinois Open Source
   6 // License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9
  10 #ifndef LLVM_LINKER_H
  11 #define LLVM_LINKER_H
  12
  13 #include <memory>
  14 #include <string>
  15 #include <vector>
  16
  17 namespace llvm {
  18
  19 class Module;
  20 class LLVMContext;
  21 class StringRef;
  22
  23 /// This class provides the core functionality of linking in LLVM. It retains a
  24 /// Module object which is the composite of the modules and libraries linked
  25 /// into it. The composite Module can be retrieved via the getModule() method.
  26 /// In this case the Linker still retains ownership of the Module. If the
  27 /// releaseModule() method is used, the ownership of the Module is transferred
  28 /// to the caller and the Linker object is only suitable for destruction.
  29 /// The Linker can link Modules from memory. By default, the linker
  30 /// will generate error and warning messages to stderr but this capability can
  31 /// be turned off with the QuietWarnings and QuietErrors flags. It can also be
  32 /// instructed to verbosely print out the linking actions it is taking with
  33 /// the Verbose flag.
  34 /// @brief The LLVM Linker.
  35 class Linker {
  36
  37   /// @name Types
  38   /// @{
  39   public:
  40     /// This enumeration is used to control various optional features of the
  41     /// linker.
  42     enum ControlFlags {
  43       Verbose       = 1, ///< Print to stderr what steps the linker is taking
  44       QuietWarnings = 2, ///< Don't print warnings to stderr.
  45       QuietErrors   = 4  ///< Don't print errors to stderr.
  46     };
  47
  48     enum LinkerMode {
  49       DestroySource = 0, // Allow source module to be destroyed.
  50       PreserveSource = 1 // Preserve the source module.
  51     };
  52
  53   /// @}
  54   /// @name Constructors
  55   /// @{
  56   public:
  57     /// Construct the Linker with an empty module which will be given the
  58     /// name \p progname. \p progname will also be used for error messages.
  59     /// @brief Construct with empty module
  60     Linker(StringRef progname, ///< name of tool running linker
  61            StringRef modulename, ///< name of linker's end-result module
  62            LLVMContext &C, ///< Context for global info
  63            unsigned Flags = 0  ///< ControlFlags (one or more |'d together)
  64     );
  65
  66     /// Construct the Linker with a previously defined module, \p aModule. Use
  67     /// \p progname for the name of the program in error messages.
  68     /// @brief Construct with existing module
  69     Linker(StringRef progname, Module* aModule, unsigned Flags = 0);
  70
  71     /// Destruct the Linker.
  72     /// @brief Destructor
  73     ~Linker();
  74
  75   /// @}
  76   /// @name Accessors
  77   /// @{
  78   public:
  79     /// This method gets the composite module into which linking is being
  80     /// done. The Composite module starts out empty and accumulates modules
  81     /// linked into it via the various LinkIn* methods. This method does not
  82     /// release the Module to the caller. The Linker retains ownership and will
  83     /// destruct the Module when the Linker is destructed.
  84     /// @see releaseModule
  85     /// @brief Get the linked/composite module.
  86     Module* getModule() const { return Composite; }
  87
  88     /// This method releases the composite Module into which linking is being
  89     /// done. Ownership of the composite Module is transferred to the caller who
  90     /// must arrange for its destruct. After this method is called, the Linker
  91     /// terminates the linking session for the returned Module. It will no
  92     /// longer utilize the returned Module but instead resets itself for
  93     /// subsequent linking as if the constructor had been called.
  94     /// @brief Release the linked/composite module.
  95     Module* releaseModule();
  96
  97     /// This method returns an error string suitable for printing to the user.
  98     /// The return value will be empty unless an error occurred in one of the
  99     /// LinkIn* methods. In those cases, the LinkIn* methods will have returned
 100     /// true, indicating an error occurred. At most one error is retained so
 101     /// this function always returns the last error that occurred. Note that if
 102     /// the Quiet control flag is not set, the error string will have already
 103     /// been printed to stderr.
 104     /// @brief Get the text of the last error that occurred.
 105     const std::string &getLastError() const { return Error; }
 106
 107   /// @}
 108   /// @name Mutators
 109   /// @{
 110   public:
 111     /// This method links the \p Src module into the Linker's Composite module
 112     /// by calling LinkModules.
 113     /// @see LinkModules
 114     /// @returns True if an error occurs, false otherwise.
 115     /// @brief Link in a module.
 116     bool LinkInModule(
 117       Module* Src,              ///< Module linked into \p Dest
 118       std::string* ErrorMsg = 0 /// Error/diagnostic string
 119     ) {
 120       return LinkModules(Composite, Src, Linker::DestroySource, ErrorMsg);
 121     }
 122
 123     /// This is the heart of the linker. This method will take unconditional
 124     /// control of the \p Src module and link it into the \p Dest module. The
 125     /// \p Src module will be destructed or subsumed by this method. In either
 126     /// case it is not usable by the caller after this method is invoked. Only
 127     /// the \p Dest module will remain. The \p Src module is linked into the
 128     /// Linker's composite module such that types, global variables, functions,
 129     /// and etc. are matched and resolved.  If an error occurs, this function
 130     /// returns true and ErrorMsg is set to a descriptive message about the
 131     /// error.
 132     /// @returns True if an error occurs, false otherwise.
 133     /// @brief Generically link two modules together.
 134     static bool LinkModules(Module* Dest, Module* Src, unsigned Mode,
 135                             std::string* ErrorMsg);
 136
 137   /// @}
 138   /// @name Implementation
 139   /// @{
 140   private:
 141     bool warning(StringRef message);
 142     bool error(StringRef message);
 143     void verbose(StringRef message);
 144
 145   /// @}
 146   /// @name Data
 147   /// @{
 148   private:
 149     LLVMContext& Context; ///< The context for global information
 150     Module* Composite; ///< The composite module linked together
 151     unsigned Flags;    ///< Flags to control optional behavior.
 152     std::string Error; ///< Text of error that occurred.
 153     std::string ProgramName; ///< Name of the program being linked
 154   /// @}
 155
 156 };
 157
 158 } // End llvm namespace
 159
 160 #endif