llvm-ir

Unlike FFI-heavy bindings like inkwell, llvm-ir is designed for consumption and analysis of LLVM IR.

It uses the LLVM API (via llvm-sys) only during the initial parsing step to construct a rich, native Rust representation. Once the Module is created, all FFI objects are dropped, allowing you to work with the IR in pure, safe Rust.

Key Abstractions:

• Instruction: An enum with variants like Add, Call, and Store (rather than an opaque type).
• BasicBlock, Function, Module: Rust structs containing complete IR information.
• HasDebugLoc: A trait used to access DebugLoc on Instructions, Terminators, GlobalVariables, and Functions (requires -g during IR generation).

Add llvm-ir to your Cargo.toml. You must select exactly one LLVM version feature flag corresponding to the LLVM library installed on your system. Supported versions include llvm-9 through llvm-19.

[dependencies]
llvm-ir = { version = "0.11.3", features = ["llvm-19"] }

When developing or debugging, you may need text-format (*.ll) files or bitcode with debug information.

For C/C++ sources (using clang):

• Bitcode: clang -c -emit-llvm source.c -o source.bc
• Text IR: clang -S -emit-llvm source.c -o source.ll
• Bitcode with debuginfo: Add the -g flag to the commands above.

For Rust sources (using rustc):

• Bitcode: rustc --emit=llvm-bc source.rs
• Text IR: rustc --emit=llvm-ir source.rs
• Bitcode with debuginfo: Add the -g flag to the command.

# Generate bitcode from C
clang -c -emit-llvm source.c -o source.bc

# Generate text IR from C
clang -S -emit-llvm source.c -o source.ll

A TypeRef is a lightweight, reference-counted handle (Arc<Type>) to an LLVM Type.

Instead of passing around owned Type objects, you should use TypeRef. Cloning a TypeRef is a cheap operation that only increments a reference count, making it suitable for frequent use in IR construction. It implements Deref<Target = Type>, allowing you to access the underlying Type methods directly.

LLVM allows constant expressions where operations are applied to other constants. The Constant enum provides variants for these operations, such as:

Integer Arithmetic:

• Add, Sub, Mul, UDiv, SDiv, URem, SRem (Note: division/remainder availability depends on LLVM version).

Bitwise Operations:

• And, Or, Xor, Shl, LShr, AShr.

Floating-Point Operations:

• FAdd, FSub, FMul, FDiv, FRem.

Vector Operations:

• ExtractElement, InsertElement, ShuffleVector.

Conversion Operations:

• Trunc, ZExt, SExt, FPTrunc, FPExt, FPToUI, FPToSI, UIToFP, SIToFP, PtrToInt, IntToPtr, BitCast, AddrSpaceCast.

Most of these operations are implemented as structs containing ConstantRef operands.

The metadata module provides Rust data structures that map to LLVM Metadata nodes and Debug Information (DI) types. It allows for the representation of complex debug structures like compile units, types, variables, and scopes in a type-safe manner.

Key abstractions include:

• Metadata: The top-level container for metadata, which can be a String, a Node (referencing a MetadataNode), or a Value (an Operand).
• MetadataNode: Represents specific LLVM metadata nodes such as Tuple, Expression, Location, or DINode.
• MetadataRef<T>: A wrapper used to handle metadata references, allowing for either a direct MetadataNodeID or an Inline value.
• DIType: Represents debug types, categorized into Basic, Composite, Derived, or Subroutine types.

A Module is the top-level container for an LLVM IR program. Its primary components include:

• name: The module identifier.
• source_file_name: The source filename.
• data_layout: Information about the target's data layout.
• target_triple: The target architecture triple (e.g., x86_64-pc-linux-gnu).
• functions: A list of defined Functions.
• func_declarations: A list of declared (but not defined) FunctionDeclarations.
• global_vars: A list of GlobalVariables.
• global_aliases: A list of GlobalAliases.
• global_ifuncs: A list of GlobalIFuncs.
• inline_assembly: Module-level inline assembly code.
• types: A Types object facilitating lookups for all types used in the module.

The MetadataNode enum represents the various types of metadata nodes defined in LLVM. Use these to construct or inspect debug information.

Available variants:

• Tuple(Vec<Option<Metadata>>): A collection of metadata (where None is null).
• Expression(DIExpression): A debug expression (a vector of DWOp).
• GlobalVariableExpression(DIGlobalVariableExpression): Links a global variable to an expression.
• Location(DILocation): Represents source code location (line/column/scope).
• MacroNode(DIMacroNode): Represents macro definitions or macro files.
• Node(DINode): A generic node containing specific debug entities like Enumerator, ImportedEntity, Scope, Subprogram, or Variable.

A ConstantRef is a lightweight, reference-counted handle to a Constant using Arc. It is used throughout the library to avoid expensive cloning of large constant structures.

ConstantRef implements:

• AsRef<Constant>: To access the underlying constant.
• Deref<Target = Constant>: To use the constant directly.
• Typed: To retrieve the TypeRef of the constant.
• Display: To get the LLVM IR string representation.

Use ConstantRef::new(constant) to wrap an owned Constant into a reference.

use llvm_ir::Constant;
use llvm_ir::ConstantRef;

let c = Constant::Int { bits: 32, value: 100 };
let c_ref = ConstantRef::new(c);

// You can deref c_ref to access Constant methods
println!("{}", *c_ref);