1 //===- llvm/Linker.h - Module Linker Interface ------------------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file was developed by Reid Spencer and is distributed under the
6 // University of Illinois Open Source License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 // This file defines the interface to the module/file/archive linker.
12 //===----------------------------------------------------------------------===//
17 #include "llvm/Support/CommandLine.h"
26 /// This type is used to pass the linkage items (libraries and files) to
27 /// the LinkItems function. It is composed of string/bool pairs. The string
28 /// provides the name of the file or library (as with the -l option). The bool
29 /// should be true for libraries, false for files, signifying "isLibrary".
30 /// @brief A list of string/bool pairs
31 typedef std::vector<std::pair<std::string,bool> > LinkItemList;
33 /// This function can be used to link a set of linkage items into a module. A
34 /// linkage item is one of the three things identified by the LinkItemKind
35 /// enumeration. This function allows linking to preserve the order of
36 /// specification associated with a command line, or for other purposes. Each
37 /// item will be linked in turn as it occurs in \p Items. Note that library
38 /// path items will only be in effect after they have been processed.
39 /// @returns The aggregated/linked Module.
42 const char * progname, ///< Name of the program being linked (for output)
43 const LinkItemList& Items, // Set of libraries/files to link in
44 const std::vector<std::string>& LibPaths, // Paths to search for libraries
45 bool Verbose, ///< Link verbosely, indicating each action
46 bool Native ///< Linking is for a native executable
49 /// This function provides some utility for tools that need to build the list
50 /// of link items from a triplet of command line options: Files, Libraries, and
51 /// LibraryPaths. The command line ordering is preserved by this function even
52 /// though the options are split into three separate cl::list<std::string>. The
53 /// resulting \p OutList is suitable for use with LinkItems.
57 LinkItemList& OutList,
58 const cl::list<std::string>& Files, ///< List of files to put in list
59 const cl::list<std::string>& Libs ///< List of libraries to put in list
62 /// This is the heart of the linker. The \p Src module is linked into the \p
63 /// Dest module. If an error occurs, true is returned, otherwise false. If \p
64 /// ErrorMsg is not null and an error occurs, \p *ErrorMsg will be set to a
65 /// readable string that indicates the nature of the error. Note that this can
66 /// destroy the Src module in arbitrary ways.
68 /// @returns true if there's an error
69 /// @brief Link two modules together
71 Module* Dest, ///< Module into which \p Src is linked
72 Module* Src, ///< Module linked into \p Dest
73 std::string* ErrorMsg ///< Optional error message string
76 /// This function links the bytecode \p Files into the \p HeadModule. Note that
77 /// this does not do any linking of unresolved symbols. The \p Files are all
78 /// completely linked into \p HeadModule regardless of unresolved symbols. This
79 /// function just loads each bytecode file and calls LinkModules on them.
80 /// @returns true if an error occurs, false otherwise
82 const char * progname, ///< Name of the program being linked (for output)
83 Module * HeadModule, ///< Main (resulting) module to be linked into
84 const std::vector<std::string> & Files, ///< Files to link in
85 bool Verbose ///< Link verbosely, indicating each action
88 /// This function links one archive, \p Filename, that contains bytecode into
89 /// \p HeadModule. If an error occurs, true is returned, otherwise false. If
90 /// \p ErrorMsg is not null and an error occurs, \p *ErrorMsg will be set to a
91 /// readable string that indicates the nature of the error.
92 /// @returns true if there's an error
93 /// @brief Link in one archive.
95 Module* HeadModule, ///< Main (resulting) module to be linked into
96 const std::string& Filename, ///< Filename of the archive to link
97 std::string* ErrorMsg, ///< Error message if an error occurs.
98 bool Verbose ///< Link verbosely, indicating each action
101 /// This function provides the ability to handle the -L and -l options on a
102 /// linker's command line. It will link into \p HeadModule any modules found in
103 /// the \p Libraries (which might be found in the \p LibPaths).
104 /// @brief Link libraries into a module
106 const char * progname, ///< Name of the program being linked (for output)
107 Module* HeadModule, ///< Main (resulting) module to be linked into
108 const std::vector<std::string> & Libraries, ///< Set of libraries to link in
109 const std::vector<std::string> & LibPaths, ///< Set of library paths
110 bool Verbose, ///< Link verbosely, indicating each action
111 bool Native ///< Linking is for a native executable
114 /// This function looks at Module \p M and returns a set of strings,
115 /// \p DefinedSymbols, that is the publicly visible defined symbols in
117 void GetAllDefinedSymbols (Module *M, std::set<std::string> &DefinedSymbols);
119 /// This function looks at Module \p M and returns a set of strings,
120 /// \p UnefinedSymbols, that is the publicly visible undefined symbols in
122 void GetAllUndefinedSymbols(Module *M, std::set<std::string> &UndefinedSymbols);
124 /// This function looks through a set of \p Paths to find a library with the
125 /// name \p Filename. If \p SharedObjectOnly is true, it only finds a match
126 /// if the file is a shared library.
127 std::string FindLib(const std::string &Filename,
128 const std::vector<std::string> &Paths,
129 bool SharedObjectOnly = false);
131 } // End llvm namespace