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