Struct inkwell::module::Module

pub struct Module { /* fields omitted */ }

Represents a reference to an LLVM Module. The underlying module will be disposed when dropping this object.

Methods

impl Module

pub fn create(name: &str) -> Self

Creates a named Module. Will be automatically assigned the global context.

To use your own Context, see inkwell::context::create_module()

Example

use inkwell::context::Context;
use inkwell::module::Module;

let context = Context::get_global();
let module = Module::create("my_module");

assert_eq!(module.get_context(), context);

pub fn add_function(
    &self,
    name: &str,
    ty: FunctionType,
    linkage: Option<Linkage>
) -> FunctionValue

Creates a function given its name and ty, adds it to the Module and returns it.

An optional linkage can be specified, without which the default value Linkage::ExternalLinkage will be used.

Example

use inkwell::context::Context;
use inkwell::module::{Module, Linkage};

let context = Context::get_global();
let module = Module::create("my_module");

let fn_type = context.f32_type().fn_type(&[], false);
let fn_val = module.add_function("my_function", fn_type, None);

assert_eq!(fn_val.get_name().to_str(), Ok("my_function"));
assert_eq!(fn_val.get_linkage(), Linkage::External);

pub fn get_context(&self) -> ContextRef

Gets the Context from which this Module originates.

Example

use inkwell::context::{Context, ContextRef};
use inkwell::module::Module;

let global_context = Context::get_global();
let global_module = Module::create("my_global_module");

assert_eq!(global_module.get_context(), global_context);

let local_context = Context::create();
let local_module = local_context.create_module("my_module");

assert_eq!(*local_module.get_context(), local_context);
assert_ne!(local_context, *global_context);

pub fn get_first_function(&self) -> Option<FunctionValue>

Gets the first FunctionValue defined in this Module.

Example

use inkwell::context::Context;
use inkwell::module::Module;

let context = Context::create();
let module = context.create_module("my_mod");

assert!(module.get_first_function().is_none());

let void_type = context.void_type();
let fn_type = void_type.fn_type(&[], false);
let fn_value = module.add_function("my_fn", fn_type, None);

assert_eq!(fn_value, module.get_first_function().unwrap());

pub fn get_last_function(&self) -> Option<FunctionValue>

Gets the last FunctionValue defined in this Module.

Example

use inkwell::context::Context;
use inkwell::module::Module;

let context = Context::create();
let module = context.create_module("my_mod");

assert!(module.get_last_function().is_none());

let void_type = context.void_type();
let fn_type = void_type.fn_type(&[], false);
let fn_value = module.add_function("my_fn", fn_type, None);

assert_eq!(fn_value, module.get_last_function().unwrap());

pub fn get_function(&self, name: &str) -> Option<FunctionValue>

Gets a FunctionValue defined in this Module by its name.

Example

use inkwell::context::Context;
use inkwell::module::Module;

let context = Context::create();
let module = context.create_module("my_mod");

assert!(module.get_function("my_fn").is_none());

let void_type = context.void_type();
let fn_type = void_type.fn_type(&[], false);
let fn_value = module.add_function("my_fn", fn_type, None);

assert_eq!(fn_value, module.get_function("my_fn").unwrap());

pub fn get_type(&self, name: &str) -> Option<BasicTypeEnum>

Gets a BasicTypeEnum of a named type in a Module.

Example

use inkwell::context::Context;

let context = Context::create();
let module = context.create_module("my_module");

assert!(module.get_type("foo").is_none());

let opaque = context.opaque_struct_type("foo");

assert_eq!(module.get_type("foo").unwrap(), opaque.into());

pub fn set_target(&self, target: &Target)

Sets a Target to this Module.

Example

use inkwell::context::Context;
use inkwell::targets::Target;

Target::initialize_x86(&Default::default());

let context = Context::create();
let module = context.create_module("mod");
let target = Target::from_name("x86-64").unwrap();

assert!(module.get_target().is_none());

module.set_target(&target);

assert_eq!(module.get_target().unwrap(), target);

pub fn get_target(&self) -> Option<Target>

Gets the Target assigned to this Module, if any.

Example

use inkwell::context::Context;
use inkwell::targets::Target;

Target::initialize_x86(&Default::default());

let context = Context::create();
let module = context.create_module("mod");
let target = Target::from_name("x86-64").unwrap();

assert!(module.get_target().is_none());

module.set_target(&target);

assert_eq!(module.get_target().unwrap(), target);

pub fn create_execution_engine(&self) -> Result<ExecutionEngine, LLVMString>

Creates an ExecutionEngine from this Module.

Example

use inkwell::context::Context;
use inkwell::module::Module;
use inkwell::targets::{InitializationConfig, Target};

Target::initialize_native(&InitializationConfig::default()).expect("Failed to initialize native target");

let context = Context::get_global();
let module = Module::create("my_module");
let execution_engine = module.create_execution_engine().unwrap();

assert_eq!(module.get_context(), context);

pub fn create_interpreter_execution_engine(
    &self
) -> Result<ExecutionEngine, LLVMString>

Creates an interpreter ExecutionEngine from this Module.

Example

use inkwell::context::Context;
use inkwell::module::Module;
use inkwell::targets::{InitializationConfig, Target};

Target::initialize_native(&InitializationConfig::default()).expect("Failed to initialize native target");

let context = Context::get_global();
let module = Module::create("my_module");
let execution_engine = module.create_interpreter_execution_engine().unwrap();

assert_eq!(module.get_context(), context);

pub fn create_jit_execution_engine(
    &self,
    opt_level: OptimizationLevel
) -> Result<ExecutionEngine, LLVMString>

Creates a JIT ExecutionEngine from this Module.

Example

use inkwell::OptimizationLevel;
use inkwell::context::Context;
use inkwell::module::Module;
use inkwell::targets::{InitializationConfig, Target};

Target::initialize_native(&InitializationConfig::default()).expect("Failed to initialize native target");

let context = Context::get_global();
let module = Module::create("my_module");
let execution_engine = module.create_jit_execution_engine(OptimizationLevel::None).unwrap();

assert_eq!(module.get_context(), context);

pub fn add_global<T: BasicType>(
    &self,
    type_: T,
    address_space: Option<AddressSpace>,
    name: &str
) -> GlobalValue

Creates a GlobalValue based on a type in an address space.

Example

use inkwell::AddressSpace;
use inkwell::context::Context;

let context = Context::create();
let module = context.create_module("mod");
let i8_type = context.i8_type();
let global = module.add_global(i8_type, Some(AddressSpace::Const), "my_global");

assert_eq!(module.get_first_global().unwrap(), global);
assert_eq!(module.get_last_global().unwrap(), global);

pub fn write_bitcode_to_path(&self, path: &Path) -> bool

Writes a Module to a Path.

Example

use inkwell::context::Context;

use std::path::Path;

let mut path = Path::new("module.bc");

let context = Context::create();
let module = context.create_module("my_module");
let void_type = context.void_type();
let fn_type = void_type.fn_type(&[], false);

module.add_function("my_fn", fn_type, None);
module.write_bitcode_to_path(&path);

pub fn write_bitcode_to_file(
    &self,
    file: &File,
    should_close: bool,
    unbuffered: bool
) -> bool

write_bitcode_to_path should be preferred over this method, as it does not work on all operating systems.

pub fn write_bitcode_to_memory(&self) -> MemoryBuffer

Writes this Module to a MemoryBuffer.

Example

use inkwell::context::Context;

let context = Context::create();
let module = context.create_module("mod");
let void_type = context.void_type();
let fn_type = void_type.fn_type(&[], false);
let f = module.add_function("f", fn_type, None);
let basic_block = f.append_basic_block("entry");
let builder = context.create_builder();

builder.position_at_end(&basic_block);
builder.build_return(None);

let buffer = module.write_bitcode_to_memory();

pub fn verify(&self) -> Result<(), LLVMString>

Ensures that the current Module is valid, and returns a Result that describes whether or not it is, returning a LLVM allocated string on error.

Remarks

See also: http://llvm.org/doxygen/Analysis_2Analysis_8cpp_source.html

pub fn get_data_layout(&self) -> Ref<DataLayout>

Gets a smart pointer to the DataLayout belonging to a particular Module.

Example

use inkwell::OptimizationLevel;
use inkwell::context::Context;
use inkwell::targets::{InitializationConfig, Target};

Target::initialize_native(&InitializationConfig::default()).expect("Failed to initialize native target");

let context = Context::create();
let module = context.create_module("sum");
let execution_engine = module.create_jit_execution_engine(OptimizationLevel::None).unwrap();
let target_data = execution_engine.get_target_data();
let data_layout = target_data.get_data_layout();

module.set_data_layout(&data_layout);

assert_eq!(*module.get_data_layout(), data_layout);

pub fn set_data_layout(&self, data_layout: &DataLayout)

Sets the DataLayout for a particular Module.

Example

use inkwell::OptimizationLevel;
use inkwell::context::Context;
use inkwell::targets::{InitializationConfig, Target};

Target::initialize_native(&InitializationConfig::default()).expect("Failed to initialize native target");

let context = Context::create();
let module = context.create_module("sum");
let execution_engine = module.create_jit_execution_engine(OptimizationLevel::None).unwrap();
let target_data = execution_engine.get_target_data();
let data_layout = target_data.get_data_layout();

module.set_data_layout(&data_layout);

assert_eq!(*module.get_data_layout(), data_layout);

pub fn print_to_stderr(&self)

Prints the content of the Module to stderr.

pub fn print_to_string(&self) -> LLVMString

Prints the content of the Module to a string.

pub fn print_to_file<P: AsRef<Path>>(&self, path: P) -> Result<(), LLVMString>

Prints the content of the Module to a file.

pub fn set_inline_assembly(&self, asm: &str)

Sets the inline assembly for the Module.

pub fn add_global_metadata(&self, key: &str, metadata: &MetadataValue)

Appends a MetaDataValue to a global list indexed by a particular key.

Example

use inkwell::context::Context;
use inkwell::values::MetadataValue;

let context = Context::create();
let module = context.create_module("my_module");
let bool_type = context.bool_type();
let f32_type = context.f32_type();
let bool_val = bool_type.const_int(0, false);
let f32_val = f32_type.const_float(0.0);

assert_eq!(module.get_global_metadata_size("my_md"), 0);

let md_string = MetadataValue::create_string("lots of metadata here");
let md_node = MetadataValue::create_node(&[&bool_val, &f32_val]);

module.add_global_metadata("my_md", &md_string);
module.add_global_metadata("my_md", &md_node);

assert_eq!(module.get_global_metadata_size("my_md"), 2);

let global_md = module.get_global_metadata("my_md");

assert_eq!(global_md.len(), 2);

let (md_0, md_1) = (global_md[0].get_node_values(), global_md[1].get_node_values());

assert_eq!(md_0.len(), 1);
assert_eq!(md_1.len(), 2);
assert_eq!(md_0[0].as_metadata_value().get_string_value(), md_string.get_string_value());
assert_eq!(md_1[0].as_int_value(), &bool_val);
assert_eq!(md_1[1].as_float_value(), &f32_val);

pub fn get_global_metadata_size(&self, key: &str) -> u32

Obtains the number of MetaDataValues indexed by a particular key.

Example

use inkwell::context::Context;
use inkwell::values::MetadataValue;

let context = Context::create();
let module = context.create_module("my_module");
let bool_type = context.bool_type();
let f32_type = context.f32_type();
let bool_val = bool_type.const_int(0, false);
let f32_val = f32_type.const_float(0.0);

assert_eq!(module.get_global_metadata_size("my_md"), 0);

let md_string = MetadataValue::create_string("lots of metadata here");
let md_node = MetadataValue::create_node(&[&bool_val, &f32_val]);

module.add_global_metadata("my_md", &md_string);
module.add_global_metadata("my_md", &md_node);

assert_eq!(module.get_global_metadata_size("my_md"), 2);

let global_md = module.get_global_metadata("my_md");

assert_eq!(global_md.len(), 2);

let (md_0, md_1) = (global_md[0].get_node_values(), global_md[1].get_node_values());

assert_eq!(md_0.len(), 1);
assert_eq!(md_1.len(), 2);
assert_eq!(md_0[0].as_metadata_value().get_string_value(), md_string.get_string_value());
assert_eq!(md_1[0].as_int_value(), &bool_val);
assert_eq!(md_1[1].as_float_value(), &f32_val);

pub fn get_global_metadata(&self, key: &str) -> Vec<MetadataValue>

Obtains the global MetaDataValue node indexed by key, which may contain 1 string or multiple values as its get_node_values()

Example

use inkwell::context::Context;
use inkwell::values::MetadataValue;

let context = Context::create();
let module = context.create_module("my_module");
let bool_type = context.bool_type();
let f32_type = context.f32_type();
let bool_val = bool_type.const_int(0, false);
let f32_val = f32_type.const_float(0.0);

assert_eq!(module.get_global_metadata_size("my_md"), 0);

let md_string = MetadataValue::create_string("lots of metadata here");
let md_node = MetadataValue::create_node(&[&bool_val, &f32_val]);

module.add_global_metadata("my_md", &md_string);
module.add_global_metadata("my_md", &md_node);

assert_eq!(module.get_global_metadata_size("my_md"), 2);

let global_md = module.get_global_metadata("my_md");

assert_eq!(global_md.len(), 2);

let (md_0, md_1) = (global_md[0].get_node_values(), global_md[1].get_node_values());

assert_eq!(md_0.len(), 1);
assert_eq!(md_1.len(), 2);
assert_eq!(md_0[0].as_metadata_value().get_string_value(), md_string.get_string_value());
assert_eq!(md_1[0].as_int_value(), &bool_val);
assert_eq!(md_1[1].as_float_value(), &f32_val);

pub fn get_first_global(&self) -> Option<GlobalValue>

Gets the first GlobalValue in a module.

Example

use inkwell::AddressSpace;
use inkwell::context::Context;

let context = Context::create();
let i8_type = context.i8_type();
let module = context.create_module("mod");

assert!(module.get_first_global().is_none());

let global = module.add_global(i8_type, Some(AddressSpace::Const), "my_global");

assert_eq!(module.get_first_global().unwrap(), global);

pub fn get_last_global(&self) -> Option<GlobalValue>

Gets the last GlobalValue in a module.

Example

use inkwell::AddressSpace;
use inkwell::context::Context;

let context = Context::create();
let module = context.create_module("mod");
let i8_type = context.i8_type();

assert!(module.get_last_global().is_none());

let global = module.add_global(i8_type, Some(AddressSpace::Const), "my_global");

assert_eq!(module.get_last_global().unwrap(), global);

pub fn get_global(&self, name: &str) -> Option<GlobalValue>

Gets a named GlobalValue in a module.

Example

use inkwell::AddressSpace;
use inkwell::context::Context;

let context = Context::create();
let module = context.create_module("mod");
let i8_type = context.i8_type();

assert!(module.get_global("my_global").is_none());

let global = module.add_global(i8_type, Some(AddressSpace::Const), "my_global");

assert_eq!(module.get_global("my_global").unwrap(), global);

pub fn parse_bitcode_from_buffer(
    buffer: &MemoryBuffer
) -> Result<Self, LLVMString>

Creates a new Module from a MemoryBuffer.

Example

use inkwell::context::Context;
use inkwell::module::Module;
use inkwell::memory_buffer::MemoryBuffer;
use std::path::Path;

let path = Path::new("foo/bar.bc");
let buffer = MemoryBuffer::create_from_file(&path).unwrap();
let module = Module::parse_bitcode_from_buffer(&buffer);

assert_eq!(module.unwrap().get_context(), Context::get_global());

pub fn parse_bitcode_from_buffer_in_context(
    buffer: &MemoryBuffer,
    context: &Context
) -> Result<Self, LLVMString>

Creates a new Module from a MemoryBuffer.

Example

use inkwell::context::Context;
use inkwell::module::Module;
use inkwell::memory_buffer::MemoryBuffer;
use std::path::Path;

let path = Path::new("foo/bar.bc");
let context = Context::create();
let buffer = MemoryBuffer::create_from_file(&path).unwrap();
let module = Module::parse_bitcode_from_buffer_in_context(&buffer, &context);

assert_eq!(module.unwrap().get_context(), Context::get_global());

pub fn parse_bitcode_from_path<P: AsRef<Path>>(
    path: P
) -> Result<Self, LLVMString>

A convenience function for creating a Module from a file.

Example

use inkwell::context::Context;
use inkwell::module::Module;
use std::path::Path;

let path = Path::new("foo/bar.bc");
let module = Module::parse_bitcode_from_path(&path);

assert_eq!(module.unwrap().get_context(), Context::get_global());

pub fn parse_bitcode_from_path_in_context<P: AsRef<Path>>(
    path: P,
    context: &Context
) -> Result<Self, LLVMString>

A convenience function for creating a Module from a file for a given context.

Example

use inkwell::context::Context;
use inkwell::module::Module;
use std::path::Path;

let path = Path::new("foo/bar.bc");
let context = Context::create();
let module = Module::parse_bitcode_from_path_in_context(&path, &context);

assert_eq!(*module.unwrap().get_context(), context);

pub fn get_name(&self) -> &CStr

Gets the name of this Module.

Example

use inkwell::context::Context;
use std::ffi::CString;

let context = Context::create();
let module = context.create_module("my_module");

assert_eq!(*module.get_name(), *CString::new("my_mdoule").unwrap());

pub fn set_name(&self, name: &str)

Assigns the name of this Module.

Example

use inkwell::context::Context;
use std::ffi::CString;

let context = Context::create();
let module = context.create_module("my_module");

module.set_name("my_module2");

assert_eq!(*module.get_name(), *CString::new("my_module2").unwrap());

pub fn get_source_file_name(&self) -> &CStr

Gets the source file name. It defaults to the module identifier but is separate from it.

Example

use inkwell::context::Context;
use std::ffi::CString;

let context = Context::create();
let module = context.create_module("my_mod");

assert_eq!(*module.get_source_file_name(), *CString::new("my_mod").unwrap());

module.set_source_file_name("my_mod.rs");

assert_eq!(*module.get_name(), *CString::new("my_mod").unwrap());
assert_eq!(*module.get_source_file_name(), *CString::new("my_mod.rs").unwrap());

pub fn set_source_file_name(&self, file_name: &str)

Sets the source file name. It defaults to the module identifier but is separate from it.

Example

use inkwell::context::Context;
use std::ffi::CString;

let context = Context::create();
let module = context.create_module("my_mod");

assert_eq!(*module.get_source_file_name(), *CString::new("my_mod").unwrap());

module.set_source_file_name("my_mod.rs");

assert_eq!(*module.get_name(), *CString::new("my_mod").unwrap());
assert_eq!(*module.get_source_file_name(), *CString::new("my_mod.rs").unwrap());

pub fn link_in_module(&self, other: Self) -> Result<(), LLVMString>

Links one module into another. This will merge two Modules into one.

Example

use inkwell::context::Context;

let context = Context::create();
let module = context.create_module("mod");
let module2 = context.create_module("mod2");

assert!(module.link_in_module(module2).is_ok());

pub fn get_or_insert_comdat(&self, name: &str) -> Comdat

Gets the Comdat associated with a particular name. If it does not exist, it will be created. A new Comdat defaults to a kind of ComdatSelectionKind::Any.

pub fn get_flag(&self, key: &str) -> Option<MetadataValue>

Gets the MetadataValue flag associated with the key in this module, if any. If a BasicValue was used to create this flag, it will be wrapped in a MetadataValue when returned from this function.

pub fn add_metadata_flag(
    &self,
    key: &str,
    behavior: FlagBehavior,
    flag: MetadataValue
)

Append a MetadataValue as a module wide flag. Note that using the same key twice will likely invalidate the module.

pub fn add_basic_value_flag<BV: BasicValue>(
    &self,
    key: &str,
    behavior: FlagBehavior,
    flag: BV
)

Append a BasicValue as a module wide flag. Note that using the same key twice will likely invalidate the module.

Trait Implementations

impl PassManagerSubType for Module

type Input = ()

unsafe fn create<I: Borrow<Self::Input>>(_: I) -> LLVMPassManagerRef

unsafe fn run_in_pass_manager(&self, pass_manager: &PassManager<Self>) -> bool

impl Eq for Module

impl Drop for Module

fn drop(&mut self)

Executes the destructor for this type.

impl Clone for Module

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl PartialEq<Module> for Module

fn eq(&self, other: &Module) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Module) -> bool

This method tests for !=.

impl Debug for Module

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.