1 //===- llvm/Linker.h - Module Linker Interface ------------------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
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
34 /// @brief The LLVM Linker.
40 /// This enumeration is used to control various optional features of the
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.
49 DestroySource = 0, // Allow source module to be destroyed.
50 PreserveSource = 1 // Preserve the source module.
54 /// @name Constructors
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)
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);
71 /// Destruct the Linker.
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; }
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();
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; }
111 /// This method links the \p Src module into the Linker's Composite module
112 /// by calling LinkModules.
114 /// @returns True if an error occurs, false otherwise.
115 /// @brief Link in a module.
117 Module* Src, ///< Module linked into \p Dest
118 std::string* ErrorMsg = 0 /// Error/diagnostic string
120 return LinkModules(Composite, Src, Linker::DestroySource, ErrorMsg);
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
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);
138 /// @name Implementation
141 bool warning(StringRef message);
142 bool error(StringRef message);
143 void verbose(StringRef message);
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
158 } // End llvm namespace