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 <string>
  14
  15 namespace llvm {
  16
  17 class Module;
  18 class LLVMContext;
  19 class StringRef;
  20
  21 /// This class provides the core functionality of linking in LLVM. It retains a
  22 /// Module object which is the composite of the modules and libraries linked
  23 /// into it. The composite Module can be retrieved via the getModule() method.
  24 /// In this case the Linker still retains ownership of the Module. If the
  25 /// releaseModule() method is used, the ownership of the Module is transferred
  26 /// to the caller and the Linker object is only suitable for destruction.
  27 /// The Linker can link Modules from memory. By default, the linker
  28 /// will generate error and warning messages to stderr but this capability can
  29 /// be turned off with the QuietWarnings and QuietErrors flags. It can also be
  30 /// instructed to verbosely print out the linking actions it is taking with
  31 /// the Verbose flag.
  32 /// @brief The LLVM Linker.
  33 class Linker {
  34
  35   /// @name Types
  36   /// @{
  37   public:
  38     enum LinkerMode {
  39       DestroySource = 0, // Allow source module to be destroyed.
  40       PreserveSource = 1 // Preserve the source module.
  41     };
  42
  43   /// @}
  44   /// @name Constructors
  45   /// @{
  46   public:
  47     /// Construct the Linker with an empty module which will be given the
  48     /// name \p progname. \p progname will also be used for error messages.
  49     /// @brief Construct with empty module
  50     Linker(StringRef progname, ///< name of tool running linker
  51            StringRef modulename, ///< name of linker's end-result module
  52            LLVMContext &C, ///< Context for global info
  53            unsigned Flags = 0  ///< ControlFlags (one or more |'d together)
  54     );
  55
  56     /// Construct the Linker with a previously defined module, \p aModule. Use
  57     /// \p progname for the name of the program in error messages.
  58     /// @brief Construct with existing module
  59     Linker(StringRef progname, Module* aModule, unsigned Flags = 0);
  60
  61     /// Destruct the Linker.
  62     /// @brief Destructor
  63     ~Linker();
  64
  65   /// @}
  66   /// @name Accessors
  67   /// @{
  68   public:
  69     /// This method gets the composite module into which linking is being
  70     /// done. The Composite module starts out empty and accumulates modules
  71     /// linked into it via the various LinkIn* methods. This method does not
  72     /// release the Module to the caller. The Linker retains ownership and will
  73     /// destruct the Module when the Linker is destructed.
  74     /// @see releaseModule
  75     /// @brief Get the linked/composite module.
  76     Module* getModule() const { return Composite; }
  77
  78   /// @}
  79   /// @name Mutators
  80   /// @{
  81   public:
  82     /// This method links the \p Src module into the Linker's Composite module
  83     /// by calling LinkModules.
  84     /// @see LinkModules
  85     /// @returns True if an error occurs, false otherwise.
  86     /// @brief Link in a module.
  87     bool LinkInModule(
  88       Module* Src,              ///< Module linked into \p Dest
  89       std::string* ErrorMsg = 0 /// Error/diagnostic string
  90     ) {
  91       return LinkModules(Composite, Src, Linker::DestroySource, ErrorMsg);
  92     }
  93
  94     /// This is the heart of the linker. This method will take unconditional
  95     /// control of the \p Src module and link it into the \p Dest module. The
  96     /// \p Src module will be destructed or subsumed by this method. In either
  97     /// case it is not usable by the caller after this method is invoked. Only
  98     /// the \p Dest module will remain. The \p Src module is linked into the
  99     /// Linker's composite module such that types, global variables, functions,
 100     /// and etc. are matched and resolved.  If an error occurs, this function
 101     /// returns true and ErrorMsg is set to a descriptive message about the
 102     /// error.
 103     /// @returns True if an error occurs, false otherwise.
 104     /// @brief Generically link two modules together.
 105     static bool LinkModules(Module* Dest, Module* Src, unsigned Mode,
 106                             std::string* ErrorMsg);
 107
 108   /// @}
 109   /// @name Implementation
 110   /// @{
 111   private:
 112   /// @}
 113   /// @name Data
 114   /// @{
 115   private:
 116     LLVMContext& Context; ///< The context for global information
 117     Module* Composite; ///< The composite module linked together
 118     unsigned Flags;    ///< Flags to control optional behavior.
 119     std::string Error; ///< Text of error that occurred.
 120     std::string ProgramName; ///< Name of the program being linked
 121   /// @}
 122
 123 };
 124
 125 } // End llvm namespace
 126
 127 #endif