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 modulename, ///< name of linker's end-result module
  51            LLVMContext &C ///< Context for global info
  52     );
  53
  54     /// Construct the Linker with a previously defined module, \p aModule. Use
  55     /// \p progname for the name of the program in error messages.
  56     /// @brief Construct with existing module
  57     Linker(Module* aModule);
  58
  59     /// Destruct the Linker.
  60     /// @brief Destructor
  61     ~Linker();
  62
  63   /// @}
  64   /// @name Accessors
  65   /// @{
  66   public:
  67     /// This method gets the composite module into which linking is being
  68     /// done. The Composite module starts out empty and accumulates modules
  69     /// linked into it via the various LinkIn* methods. This method does not
  70     /// release the Module to the caller. The Linker retains ownership and will
  71     /// destruct the Module when the Linker is destructed.
  72     /// @see releaseModule
  73     /// @brief Get the linked/composite module.
  74     Module* getModule() const { return Composite; }
  75
  76   /// @}
  77   /// @name Mutators
  78   /// @{
  79   public:
  80     /// This method links the \p Src module into the Linker's Composite module
  81     /// by calling LinkModules.
  82     /// @see LinkModules
  83     /// @returns True if an error occurs, false otherwise.
  84     /// @brief Link in a module.
  85     bool LinkInModule(
  86       Module* Src,              ///< Module linked into \p Dest
  87       std::string* ErrorMsg = 0 /// Error/diagnostic string
  88     ) {
  89       return LinkModules(Composite, Src, Linker::DestroySource, ErrorMsg);
  90     }
  91
  92     /// This is the heart of the linker. This method will take unconditional
  93     /// control of the \p Src module and link it into the \p Dest module. The
  94     /// \p Src module will be destructed or subsumed by this method. In either
  95     /// case it is not usable by the caller after this method is invoked. Only
  96     /// the \p Dest module will remain. The \p Src module is linked into the
  97     /// Linker's composite module such that types, global variables, functions,
  98     /// and etc. are matched and resolved.  If an error occurs, this function
  99     /// returns true and ErrorMsg is set to a descriptive message about the
 100     /// error.
 101     /// @returns True if an error occurs, false otherwise.
 102     /// @brief Generically link two modules together.
 103     static bool LinkModules(Module* Dest, Module* Src, unsigned Mode,
 104                             std::string* ErrorMsg);
 105
 106   /// @}
 107   /// @name Implementation
 108   /// @{
 109   private:
 110   /// @}
 111   /// @name Data
 112   /// @{
 113   private:
 114     Module* Composite; ///< The composite module linked together
 115   /// @}
 116
 117 };
 118
 119 } // End llvm namespace
 120
 121 #endif