Module

public final class Module : CustomStringConvertible

A Module represents the top-level structure of an LLVM program. An LLVM module is effectively a translation unit or a collection of translation units merged together.

LLVM programs are composed of Modules consisting of functions, global variables, symbol table entries, and metadata. Modules may be combined together with the LLVM linker, which merges function (and global variable) definitions, resolves forward declarations, and merges symbol table entries.

Creating a Module

A module can be created using init(name:context:). Note that the default target triple is bare metal and there is no default data layout. If you require these to be specified (e.g. to increase the correctness of default alignment values), be sure to set them yourself.

if let machine = try? TargetMachine() {
    module.targetTriple = machine.triple
    module.dataLayout = machine.dataLayout
}

Verifying a Module

A module naturally grows to encompass a large amount of data during code generation. To verify that the module is well-formed and suitable for submission to later phases of LLVM, call Module.verify(). If the module does not pass verification, an error describing the cause will be thrown.

let module = Module(name: "Example")
let builder = IRBuilder(module: module)
let main = builder.addFunction("main",
                               type: FunctionType([], VoidType()))
let entry = main.appendBasicBlock(named: "entry")
builder.positionAtEnd(of: entry)
builder.buildRet(main.address(of: entry)!)

try module.verify()
// The following error is thrown:
//   module did not pass verification: blockaddress may not be used with the entry block!
//   Found return instr that returns non-void in Function of void return type!

The built-in verifier attempts to be correct at the cost of completeness. For strictest checking, invoke the lli tool on any IR that is generated.

Threading Considerations

A module value is associated with exactly one LLVM context. That context, and its creating thread, must be used to access and mutate this module as LLVM provides no locking or atomicity guarantees.

Printing The Contents of a Module

The contents of a module are mostly machine-independent. It is often useful while debugging to view this machine-independent IR. A module responds to Module.dump() by printing this representation to standard output. To dump the module to a file, use Module.print(to:). In general, a module must be associated with a TargetMachine and a target environment for its contents to be fully useful for export to later file formats such as object files or bitcode. See TargetMachine.emitToFile(module:type:path) for more details.

Module Flags

To convey information about a module to LLVM’s various subsystems, a module may have flags attached. These flags are keyed by global strings, and attached as metadata to the module with the privileged llvm.module.flags metadata identifier. Certain flags have hard-coded meanings in LLVM such as the Objective-C garbage collection flags or the linker options flags. Most other flags are stripped from any resulting object files.

  • Returns the context associated with this module.

    Declaration

    Swift

    public let context: Context

  • Creates a Module with the given name.

    Declaration

    Swift

    public init(name: String, context: Context = .global)

    Parameters

    name

    The name of the module.
    context

    The context to associate this module with. If no context is provided, the global context is assumed.

  • Obtain the target triple for this module.

    Declaration

    Swift

    public var targetTriple: Triple { get set }

  • Obtain the data layout for this module.

    Declaration

    Swift

    public var dataLayout: TargetData { get set }

  • Returns a string describing the data layout associated with this module.

    Declaration

    Swift

    public var dataLayoutString: String { get set }

  • The identifier of this module.

    Declaration

    Swift

    public var name: String { get set }

  • The source filename of this module.

    The source filename appears at the top of an IR module:

    source_filename = "/path/to/source.c"

    Local functions used in profile data prepend the source file name to the local function name.

    If not otherwise set, name is used.

    Declaration

    Swift

    public var sourceFileName: String { get set }

  • Retrieves the inline assembly for this module, if any.

    Declaration

    Swift

    public var inlineAssembly: String { get set }

  • Retrieves the sequence of functions that make up this module.

    Declaration

    Swift

    public var functions: AnySequence<Function> { get }

  • Retrieves the first function in this module, if there are any functions.

    Declaration

    Swift

    public var firstFunction: Function? { get }

  • Retrieves the last function in this module, if there are any functions.

    Declaration

    Swift

    public var lastFunction: Function? { get }

  • Retrieves the first global in this module, if there are any globals.

    Declaration

    Swift

    public var firstGlobal: Global? { get }

  • Retrieves the last global in this module, if there are any globals.

    Declaration

    Swift

    public var lastGlobal: Global? { get }

  • Retrieves the sequence of functions that make up this module.

    Declaration

    Swift

    public var globals: AnySequence<Global> { get }

  • Retrieves the first alias in this module, if there are any aliases.

    Declaration

    Swift

    public var firstAlias: Alias? { get }

  • Retrieves the last alias in this module, if there are any aliases.

    Declaration

    Swift

    public var lastAlias: Alias? { get }

  • Retrieves the sequence of aliases that make up this module.

    Declaration

    Swift

    public var aliases: AnySequence<Alias> { get }

  • Retrieves the first alias in this module, if there are any aliases.

    Declaration

    Swift

    public var firstNamedMetadata: NamedMetadata? { get }

  • Retrieves the last alias in this module, if there are any aliases.

    Declaration

    Swift

    public var lastNamedMetadata: NamedMetadata? { get }

  • Retrieves the sequence of aliases that make up this module.

    Declaration

    Swift

    public var namedMetadata: AnySequence<NamedMetadata> { get }

  • The current debug metadata version number.

    Declaration

    Swift

    public static var debugMetadataVersion: UInt32 { get }

  • The version of debug metadata that’s present in this module.

    Declaration

    Swift

    public var debugMetadataVersion: UInt32 { get }

Module Printing

  • Print a representation of a module to a file at the given path.

    If the provided path is not suitable for writing, this function will throw ModuleError.couldNotPrint.

    Declaration

    Swift

    public func print(to path: String) throws

    Parameters

    path

    The path to write the module’s representation to.

  • Dump a representation of this module to stderr.

    Declaration

    Swift

    public func dump()

  • The full text IR of this module

    Declaration

    Swift

    public var description: String { get }

Module Emission

  • Writes the bitcode of elements in this module to a file at the given path.

    If the provided path is not suitable for writing, this function will throw ModuleError.couldNotEmitBitCode.

    Declaration

    Swift

    public func emitBitCode(to path: String) throws

    Parameters

    path

    The path to write the module’s representation to.

Module Actions

  • Verifies that this module is valid, taking the specified action if not. If this module did not pass verification, a description of any invalid constructs is provided with the thrown ModuleError.didNotPassVerification error.

    Declaration

    Swift

    public func verify() throws

  • Links the given module with this module. If the link succeeds, this module will the composite of the two input modules.

    The result of this function is true if the link succeeds, or false otherwise.

    Declaration

    Swift

    public func link(_ other: Module) -> Bool

    Parameters

    other

    The module to link with this module.

  • Strip debug info in the module if it exists.

    To do this, we remove all calls to the debugger intrinsics and any named metadata for debugging. We also remove debug locations for instructions. Return true if module is modified.

    Declaration

    Swift

    public func stripDebugInfo() -> Bool

Global Declarations

  • Searches for and retrieves a global variable with the given name in this module if that name references an existing global variable.

    Declaration

    Swift

    public func global(named name: String) -> Global?

    Parameters

    name

    The name of the global to reference.

    Return Value

    A value representing the referenced global if it exists.

  • Searches for and retrieves a type with the given name in this module if that name references an existing type.

    Declaration

    Swift

    public func type(named name: String) -> IRType?

    Parameters

    name

    The name of the type to create.

    Return Value

    A representation of the newly created type with the given name or nil if such a representation could not be created.

  • Searches for and retrieves a function with the given name in this module if that name references an existing function.

    Declaration

    Swift

    public func function(named name: String) -> Function?

    Parameters

    name

    The name of the function to create.

    Return Value

    A representation of a function with the given name or nil if such a representation could not be created.

  • Searches for and retrieves an intrinsic with the given name in this module if that name references an intrinsic.

    Declaration

    Swift

    public func intrinsic(named name: String, parameters: [IRType] = []) -> Intrinsic?

    Parameters

    name

    The name of the intrinsic to search for.
    parameters

    The type of the parameters of the intrinsic to resolve any ambiguity caused by overloads.

    Return Value

    A representation of an intrinsic with the given name or nil if such an intrinsic could not be found.

  • Searches for and retrieves an intrinsic with the given selector in this module if that selector references an intrinsic.

    Unlike Module.intrinsic(named:parameters:), the intrinsic function need not be declared. If the module contains a declaration of the intrinsic function, it will be returned. Else, a declaration for the intrinsic will be created and appended to this module.

    LLVMSwift intrinsic selector syntax differs from the LLVM naming conventions for intrinsics in one crucial way: all dots are replaced by underscores.

    For example:

    llvm.foo.bar.baz -> Intrinsic.ID.llvm_foo_bar_baz
llvm.sin -> Intrinsic.ID.llvm_sin
llvm.stacksave -> Intrinsic.ID.llvm_stacksave
llvm.x86.xsave64 -> Intrinsic.ID.llvm_x86_xsave64

    Declaration

    Swift

    public func intrinsic(_ selector: Intrinsic.Selector, parameters: [IRType] = []) -> Intrinsic?

    Parameters

    selector

    The selector of the intrinsic to search for.
    parameters

    The type of the parameters of the intrinsic to resolve any ambiguity caused by overloads.

    Return Value

    A representation of an intrinsic with the given name or nil if such an intrinsic could not be found.

  • Searches for and retrieves an alias with the given name in this module if that name references an existing alias.

    Declaration

    Swift

    public func alias(named name: String) -> Alias?

    Parameters

    name

    The name of the alias to search for.

    Return Value

    A representation of an alias with the given name or nil if no such named alias exists.

  • Searches for and retrieves a comdat section with the given name in this module. If none is found, one with that name is created and returned.

    Declaration

    Swift

    public func comdat(named name: String) -> Comdat

    Parameters

    name

    The name of the comdat section to create.

    Return Value

    A representation of the newly created comdat section with the given name.

  • Searches for and retrieves module-level named metadata with the given name in this module. If none is found, one with that name is created and returned.

    Declaration

    Swift

    public func metadata(named name: String) -> NamedMetadata

    Parameters

    name

    The name of the comdat section to create.

    Return Value

    A representation of the newly created metadata with the given name.

  • Build a named function body with the given type.

    Declaration

    Swift

    public func addFunction(_ name: String, type: FunctionType) -> Function

    Parameters

    name

    The name of the newly defined function.
    type

    The type of the newly defined function.

    Return Value

    A value representing the newly inserted function definition.

  • Build a named global of the given type.

    Declaration

    Swift

    public func addGlobal(_ name: String, type: IRType, addressSpace: AddressSpace = .zero) -> Global

    Parameters

    name

    The name of the newly inserted global value.
    type

    The type of the newly inserted global value.
    addressSpace

    The optional address space where the global variable resides.

    Return Value

    A value representing the newly inserted global variable.

  • Build a named global of the given type.

    Declaration

    Swift

    public func addGlobal(_ name: String, initializer: IRValue, addressSpace: AddressSpace = .zero) -> Global

    Parameters

    name

    The name of the newly inserted global value.
    initializer

    The initial value for the global variable.
    addressSpace

    The optional address space where the global variable resides.

    Return Value

    A value representing the newly inserted global variable.

  • Build a named global string consisting of an array of i8 type filled in with the nul terminated string value.

    Declaration

    Swift

    public func addGlobalString(name: String, value: String) -> Global

    Parameters

    name

    The name of the newly inserted global string value.
    value

    The character contents of the newly inserted global.

    Return Value

    A value representing the newly inserted global string variable.

  • Build a named alias to a global value or a constant expression.

    Aliases, unlike function or variables, don’t create any new data. They are just a new symbol and metadata for an existing position.

    Declaration

    Swift

    public func addAlias(name: String, to aliasee: IRGlobal, type: IRType) -> Alias

    Parameters

    name

    The name of the newly inserted alias.
    aliasee

    The value or constant to alias.
    type

    The type of the aliased value or expression.

    Return Value

    A value representing the newly created alias.

  • Append to the module-scope inline assembly blocks.

    A trailing newline is added if the given string doesn’t have one.

    Declaration

    Swift

    public func appendInlineAssembly(_ asm: String)

    Parameters

    asm

    The inline assembly expression template string.

Module Flags

  • Represents flags that describe information about the module for use by an external entity e.g. the dynamic linker.

    Warning

    Module flags are not a general runtime metadata infrastructure, and may be stripped by LLVM. As of the current release, LLVM hardcodes support for object-file emission of module flags related to Objective-C.
    See more

    Declaration

    Swift

    public class Flags

  • Add a module-level flag to the module-level flags metadata.

    Declaration

    Swift

    public func addFlag(named name: String, value: IRMetadata, behavior: Flags.Behavior)

    Parameters

    name

    The key for this flag.
    value

    The metadata node to insert as the value for this flag.
    behavior

    The resolution strategy to apply should the key for this flag conflict with an existing flag.

  • A convenience for inserting constant values as module-level flags.

    Declaration

    Swift

    public func addFlag(named name: String, constant: IRConstant, behavior: Flags.Behavior)

    Parameters

    name

    The key for this flag.
    value

    The constant value to insert as the metadata for this flag.
    behavior

    The resolution strategy to apply should the key for this flag conflict with an existing flag.

  • Retrieves the module-level flags, if they exist.

    Declaration

    Swift

    public var flags: Flags? { get }