LLVM API Documentation

llvm::Linker Class Reference

The LLVM Linker. More...

#include <Linker.h>

Collaboration diagram for llvm::Linker:

Collaboration graph
[legend]
List of all members.

Mutators

void addPath (const sys::Path &path)
 Add a path.
void addPaths (const std::vector< std::string > &paths)
 Add a set of paths.
void addSystemPaths ()
 Add the system paths.
void setFlags (unsigned flags)
 Set control flags.
bool LinkInItems (const ItemList &Items, ItemList &NativeItems)
bool LinkInFiles (const std::vector< sys::Path > &Files)
 Link in multiple files.
bool LinkInFile (const sys::Path &File)
 Link in a single file.
bool LinkInLibraries (const std::vector< std::string > &Libraries)
 Link libraries into the module.
bool LinkInLibrary (const std::string &Library, bool &is_file)
 Link one library into the module.
bool LinkInArchive (const sys::Path &Filename)
 Link in one archive.
bool LinkInModule (Module *Src)
 Link in a module.
sys::Path FindLib (const std::string &Filename)
 Find a library from its short name.
static bool LinkModules (Module *Dest, Module *Src, std::string *ErrorMsg)
 Generically link two modules together.

Public Types

 Verbose = 1
 Print to std::cerr what steps the linker is taking.
 QuietWarnings = 2
 Don't print errors and warnings to std::cerr.
 QuietErrors = 4
 Indicate that this link is for a native executable.
Types
typedef std::vector< std::pair<
std::string, bool > > 
ItemList
 A list of linkage items.
enum  ControlFlags { Verbose = 1, QuietWarnings = 2, QuietErrors = 4 }

Public Member Functions

Constructors
 Linker (const std::string &progname, const std::string &modulename, unsigned Flags=0)
 Construct with empty module.
 Linker (const std::string &progname, Module *aModule, unsigned Flags=0)
 Construct with existing module.
 ~Linker ()
 Destructor.
Accessors
ModulegetModule () const
 Get the linked/composite module.
ModulereleaseModule ()
 Release the linked/composite module.
const std::vector< sys::Path > & getLibPaths () const
 Get the Linkers library path.
const std::string & getLastError () const
 Get the text of the last error that occurred.

Detailed Description

The LLVM Linker.

This class provides the core functionality of linking in LLVM. It retains a Module object which is the composite of the modules and libraries linked into it. The composite Module can be retrieved via the getModule() method. In this case the Linker still retains ownership of the Module. If the releaseModule() method is used, the ownership of the Module is transferred to the caller and the Linker object is only suitable for destruction. The Linker can link Modules from memory, bytecode files, or bytecode archives. It retains a set of search paths in which to find any libraries presented to it. By default, the linker will generate error and warning messages to std::cerr but this capability can be turned off with the QuietWarnings and QuietErrors flags. It can also be instructed to verbosely print out the linking actions it is taking with the Verbose flag.

Definition at line 38 of file Linker.h.


Member Typedef Documentation

typedef std::vector<std::pair<std::string,bool> > llvm::Linker::ItemList

A list of linkage items.

This type is used to pass the linkage items (libraries and files) to the LinkItems function. It is composed of string/bool pairs. The string provides the name of the file or library (as with the -l option). The bool should be true for libraries and false for files, signifying "isLibrary".

Definition at line 49 of file Linker.h.


Member Enumeration Documentation

enum llvm::Linker::ControlFlags

This enumeration is used to control various optional features of the linker.

Enumerator:
Verbose  Print to std::cerr what steps the linker is taking.
QuietWarnings  Don't print errors and warnings to std::cerr.
QuietErrors  Indicate that this link is for a native executable.

Definition at line 53 of file Linker.h.


Constructor & Destructor Documentation

Linker::Linker ( const std::string &  progname,
const std::string &  modulename,
unsigned  Flags = 0 
)

Construct with empty module.

Construct the Linker with an empty module which will be given the name progname. progname will also be used for error messages.

Parameters:
progname  name of tool running linker
modulename  name of linker's end-result module
Flags  ControlFlags (one or more |'d together)

Definition at line 22 of file Linker.cpp.

Linker::Linker ( const std::string &  progname,
Module aModule,
unsigned  Flags = 0 
)

Construct with existing module.

Construct the Linker with a previously defined module, aModule. Use progname for the name of the program in error messages.

Definition at line 32 of file Linker.cpp.

Linker::~Linker (  ) 

Destructor.

Destruct the Linker.

Definition at line 41 of file Linker.cpp.


Member Function Documentation

void Linker::addPath ( const sys::Path path  ) 

Add a path.

Add a path to the list of paths that the Linker will search. The Linker accumulates the set of libraries added library paths for the target platform. The standard libraries will always be searched last. The added libraries will be searched in the order added.

Definition at line 71 of file Linker.cpp.

void Linker::addPaths ( const std::vector< std::string > &  paths  ) 

Add a set of paths.

Add a set of paths to the list of paths that the linker will search. The Linker accumulates the set of libraries added. The paths will be added to the end of the Linker's list. Order will be retained.

Definition at line 76 of file Linker.cpp.

void Linker::addSystemPaths (  ) 

Add the system paths.

This method augments the Linker's list of library paths with the system paths of the host operating system, include LLVM_LIB_SEARCH_PATH.

Definition at line 85 of file Linker.cpp.

References llvm::sys::Path::GetBytecodeLibraryPaths().

sys::Path Linker::FindLib ( const std::string &  Filename  ) 

Find a library from its short name.

This function looks through the Linker's LibPaths to find a library with the name Filename. If the library cannot be found, the returned path will be empty (i.e. sys::Path::isEmpty() will return true).

Returns:
A sys::Path to the found library

Definition at line 160 of file Linker.cpp.

References llvm::sys::Path::canRead(), llvm::sys::Path::isArchive(), llvm::sys::Path::isDynamicLibrary(), llvm::sys::Path::isEmpty(), and IsLibrary().

Referenced by LinkInLibrary().

const std::string& llvm::Linker::getLastError (  )  const [inline]

Get the text of the last error that occurred.

This method returns an error string suitable for printing to the user. The return value will be empty unless an error occurred in one of the LinkIn* methods. In those cases, the LinkIn* methods will have returned true, indicating an error occurred. At most one error is retained so this function always returns the last error that occurred. Note that if the Quiet control flag is not set, the error string will have already been printed to std::cerr.

Definition at line 117 of file Linker.h.

const std::vector<sys::Path>& llvm::Linker::getLibPaths (  )  const [inline]

Get the Linkers library path.

This method gets the list of libraries that form the path that the Linker will search when it is presented with a library name.

Definition at line 107 of file Linker.h.

Module* llvm::Linker::getModule (  )  const [inline]

Get the linked/composite module.

This method gets the composite module into which linking is being done. The Composite module starts out empty and accumulates modules linked into it via the various LinkIn* methods. This method does not release the Module to the caller. The Linker retains ownership and will destruct the Module when the Linker is destructed.

See also:
releaseModule

Definition at line 92 of file Linker.h.

bool Linker::LinkInArchive ( const sys::Path Filename  ) 

Link in one archive.

This function links one bytecode archive, Filename, into the module. The archive is searched to resolve outstanding symbols. Any modules in the archive that resolve outstanding symbols will be linked in. The library is searched repeatedly until no more modules that resolve symbols can be found. If an error occurs, the error string is set. To speed up this function, ensure the the archive has been processed llvm-ranlib or the S option was given to llvm-ar when the archive was created. These tools add a symbol table to the archive which makes the search for undefined symbols much faster.

See also:
getLastError
Returns:
true if an error occurs, otherwise false.
Parameters:
Filename  Filename of the archive to link

Definition at line 99 of file LinkArchives.cpp.

References E, Filename, llvm::Archive::findModulesDefiningSymbols(), GetAllUndefinedSymbols(), llvm::Module::getModuleIdentifier(), I, LinkInModule(), llvm::Archive::OpenAndLoadSymbols(), and llvm::set_subtract().

Referenced by LinkInFile(), and LinkInLibrary().

bool Linker::LinkInFile ( const sys::Path File  ) 

Link in a single file.

This function links a single bytecode file, File, into the composite module. Note that this does not attempt to resolve symbols. This method just loads the bytecode file and calls LinkInModule on it. If an error occurs, the Linker's error string is set.

Returns:
true if an error occurs, false otherwise
See also:
getLastError
Parameters:
File  File to link in.

Definition at line 137 of file LinkItems.cpp.

References llvm::sys::Path::canRead(), llvm::sys::Path::isArchive(), llvm::sys::Path::isBytecodeFile(), LinkInArchive(), LinkInModule(), M, and llvm::sys::Path::toString().

Referenced by LinkInFiles(), LinkInItems(), and LinkInLibrary().

bool Linker::LinkInFiles ( const std::vector< sys::Path > &  Files  ) 

Link in multiple files.

This function links the bytecode Files into the composite module. Note that this does not do any linking of unresolved symbols. The Files are all completely linked into HeadModule regardless of unresolved symbols. This function just loads each bytecode file and calls LinkInModule on them.

Returns:
true if an error occurs, false otherwise
See also:
getLastError
Parameters:
Files  Files to link in

Definition at line 176 of file LinkItems.cpp.

References LinkInFile().

bool Linker::LinkInItems ( const ItemList Items,
ItemList NativeItems 
)

This method is the main interface to the linker. It can be used to link a set of linkage items into a module. A linkage item is either a file name with fully qualified path, or a library for which the Linker's LibraryPath will be utilized to locate the library. The bool value in the LinkItemKind should be set to true for libraries. This function allows linking to preserve the order of specification associated with the command line, or for other purposes. Each item will be linked in turn as it occurs in Items.

Returns:
true if an error occurred, false otherwise
See also:
LinkItemKind

getLastError

Exceptions:
nothing 
Parameters:
Items  Set of libraries/files to link in
NativeItems  Output list of native files/libs

Definition at line 26 of file LinkItems.cpp.

References E, I, llvm::Module::lib_begin(), llvm::Module::lib_end(), LinkInFile(), and LinkInLibrary().

bool Linker::LinkInLibraries ( const std::vector< std::string > &  Libraries  ) 

Link libraries into the module.

This function provides a way to selectively link in a set of modules, found in libraries, based on the unresolved symbols in the composite module. Each item in Libraries should be the base name of a library, as if given with the -l option of a linker tool. The Linker's LibPaths are searched for the Libraries and any found will be linked in with LinkInArchive. If an error occurs, the Linker's error string is set.

See also:
LinkInArchive

getLastError

Returns:
true if an error occurs, false otherwise
Parameters:
Libraries  Libraries to link in

Definition at line 102 of file LinkItems.cpp.

References llvm::SetVector< T >::begin(), E, llvm::SetVector< T >::end(), llvm::Module::getLibraries(), I, and LinkInLibrary().

bool Linker::LinkInLibrary ( const std::string &  Library,
bool &  is_file 
)

Link one library into the module.

This function provides a way to selectively link in a set of modules, found in one library, based on the unresolved symbols in the composite module.The Library should be the base name of a library, as if given with the -l option of a linker tool. The Linker's LibPaths are searched for the Library and if found, it will be linked in with via the LinkInArchive method. If an error occurs, the Linker's error string is set.

See also:
LinkInArchive

getLastError

Returns:
true if an error occurs, false otherwise
Parameters:
Lib  The library to link in
is_file  Indicates if lib is really a bc file

Definition at line 64 of file LinkItems.cpp.

References llvm::sys::ArchiveFileType, llvm::sys::BytecodeFileType, llvm::sys::CompressedBytecodeFileType, FindLib(), llvm::sys::Path::getMagicNumber(), llvm::sys::IdentifyFileType(), llvm::sys::Path::isEmpty(), LinkInArchive(), LinkInFile(), and llvm::sys::Path::toString().

Referenced by LinkInItems(), and LinkInLibraries().

bool llvm::Linker::LinkInModule ( Module Src  )  [inline]

Link in a module.

This method links the Src module into the Linker's Composite module by calling LinkModules. All the other LinkIn* methods eventually result in calling this method to link a Module into the Linker's composite.

See also:
LinkModules
Returns:
True if an error occurs, false otherwise.
Parameters:
Src  Module linked into Dest

Definition at line 241 of file Linker.h.

References LinkModules(), and Src.

Referenced by LinkInArchive(), and LinkInFile().

bool Linker::LinkModules ( Module Dest,
Module Src,
std::string *  ErrorMsg 
) [static]

Generically link two modules together.

This is the heart of the linker. This method will take unconditional control of the Src module and link it into the Dest module. The Src module will be destructed or subsumed by this method. In either case it is not usable by the caller after this method is invoked. Only the Dest module will remain. The Src module is linked into the Linker's composite module such that types, global variables, functions, and etc. are matched and resolved. If an error occurs, this function returns true and ErrorMsg is set to a descriptive message about the error.

Returns:
True if an error occurs, false otherwise.

Definition at line 833 of file LinkModules.cpp.

References llvm::Module::AnyEndianness, llvm::Module::AnyPointerSize, Dest, E, llvm::sys::Path::getBasename(), I, llvm::sys::Path::isEmpty(), LinkAppendingVars(), LinkFunctionBodies(), LinkFunctionProtos(), LinkGlobalInits(), LinkGlobals(), LinkTypes(), SE, llvm::sys::Path::set(), and Src.

Referenced by LinkInModule().

Module * Linker::releaseModule (  ) 

Release the linked/composite module.

This method releases the composite Module into which linking is being done. Ownership of the composite Module is transferred to the caller who must arrange for its destruct. After this method is called, the Linker terminates the linking session for the returned Module. It will no longer utilize the returned Module but instead resets itself for subsequent linking as if the constructor had been called. The Linker's LibPaths and flags to be reset, and memory will be released.

Definition at line 91 of file Linker.cpp.

void llvm::Linker::setFlags ( unsigned  flags  )  [inline]

Set control flags.

Control optional linker behavior by setting a group of flags. The flags are defined in the ControlFlags enumeration.

See also:
ControlFlags

Definition at line 146 of file Linker.h.


The documentation for this class was generated from the following files: