llvmpy/docs/source/doc/llvm.core.Module.md

---
layout: page
title: Module (llvm.core)
---

Modules are top-level container objects. You need to create a module
object first, before you can add global variables, aliases or functions.
Modules are created using the static method `Module.new`:

{% highlight python %}
#!/usr/bin/env python

from llvm import *
from llvm.core import *

# create a module
my_module = Module.new('my_module')
{% endhighlight %}

The constructor of the Module class should _not_ be used to instantiate
a Module object. This is a common feature for all llvm-py classes.

> **Convention**
>
> *All* llvm-py objects are instantiated using static methods of
> corresponding classes. Constructors _should not_ be used.
>
> The argument `my_module` is a module identifier (a plain string). A
> module can also be constructed via deserialization from a bit code file,
> using the static method `from_bitcode`. This method takes a file-like
> object as argument, i.e., it should have a `read()` method that returns
> the entire data in a single call, as is the case with the builtin file
> object. Here is an example:

{% highlight python %}
# create a module from a bit code file
bcfile = file("test.bc")
my_module = Module.from_bitcode(bcfile)
{% endhighlight %}

There is corresponding serialization method also, called `to_bitcode`:

{% highlight python %}
# write out a bit code file from the module
bcfile = file("test.bc", "w")
my_module.to_bitcode(bcfile)
{% endhighlight %}

Modules can also be constructed from LLVM assembly files (`.ll` files).
The static method `from_assembly` can be used for this. Similar to the
`from_bitcode` method, this one also takes a file-like object as
argument:

{% highlight python %}
# create a module from an assembly file
llfile = file("test.ll")
my_module = Module.from_assembly(llfile)
{% endhighlight %}

Modules can be converted into their assembly representation by
stringifying them (see below).

* * *


# llvm.core.Module

* This will become a table of contents (this text will be scraped).
{:toc}

## Static Constructors

### `new(module_id)`

Create a new `Module` instance with given `module_id`. The `module_id`
should be a string.

### `from_bitcode(fileobj)`

Create a new `Module` instance by deserializing the bitcode file
represented by the file-like object `fileobj`.

### `from_assembly(fileobj)`

Create a new `Module` instance by parsing the LLVM assembly file
represented by the file-like object `fileobj`.

## Properties

### `data_layout`

A string representing the ABI of the platform.

### `target`

A string like `i386-pc-linux-gnu` or `i386-pc-solaris2.8`.

### `pointer_size`
\[read-only\]

The size in bits of pointers, of the target platform. A value of
zero represents `llvm::Module::AnyPointerSize`.

### `global_variables`
\[read-only\]

An iterable that yields [GlobalVariable][llvm.core.GlobalVariable] objects,
that represent the global variables of the module.

### `functions`
\[read-only\]

An iterable that yields [Function][llvm.core.Function] objects,
that represent functions in the module.

### `id`

A string that represents the module identifier (name).

## Methods

### `get_type_named(name)`

Return a [StructType][llvm.core.StructType] object for the given name.

The definition of this method was changed to work with LLVM 3.0+, in which
the type system was rewritten.
See [LLVM Blog](http://blog.llvm.org/2011/11/llvm-30-type-system-rewrite.html).

{% comment %}
++++++++REMOVED+++++++++++
### `add_type_name(name, ty)`

Add an alias (typedef) for the type `ty` with the name `name`.

### `delete_type_name(name)`

Delete an alias with the name `name`.
++++++++END-REMOVED+++++++++++
{% endcomment %}

### `add_global_variable(ty, name)`

Add a global variable of the type `ty` with the name `name`.
Returns a [GlobalVariable][llvm.core.GlobalVariable] object.

### `get_global_variable_named(name)`

Get a [GlobalVariable][llvm.core.GlobalVariable] object corresponding to
the global variable with the name `name`.
Raises `LLVMException` if such a variable does not exist.

### `add_library(name)`

Add a dependent library to the Module. This only adds a name to a list of
dependent library. **No linking is performed**.

### `add_function(ty, name)`

Add a function named `name` with the function type `ty`. `ty` must
of an object of type [FunctionType][llvm.core.FunctionType].

### `get_function_named(name)`

Get a [Function][llvm.core.Function] object corresponding to the function with
the name `name`. Raises `LLVMException` if such a function does not exist.

### `get_or_insert_function(ty, name)`

Like `get_function_named`, but adds the function first, if not
present (like `add_function`).

### `verify()`

Verify the correctness of the module. Raises `LLVMException` on
errors.

### `to_bitcode(fileobj)`

Write the bitcode representation of the module to the file-like
object `fileobj`.

### `link_in(other)`

Link in another module `other` into this module. Global variables,
functions etc. are matched and resolved. The `other` module is no
longer valid and should not be used after this operation. This API
might be replaced with a full-fledged Linker class in the future.

## Special Methods


### `__str__`

`Module` objects can be stringified into it's LLVM assembly language
representation.

### `__eq__`

`Module` objects can be compared for equality. Internally, this
converts both arguments into their LLVM assembly representations and
compares the resultant strings.

> **Convention**
>
> *All* llvm-py objects (where it makes sense), when stringified, return
> the LLVM assembly representation. `print module_obj` for example,
> prints the LLVM assembly form of the entire module.
>
> Such objects, when compared for equality, internally compare these
> string representations.

[llvm.core.Function]: llvm.core.Function.html
[llvm.core.FunctionType]: llvm.core.FunctionType.html
[llvm.core.GlobalVariable]: llvm.core.GlobalVariable.html
[llvm.core.BasicBlock]: llvm.core.BasicBlock.html
[llvm.core.Type]: llvm.core.Type.html
[llvm.core.StructType]: llvm.core.StructType.html