lower-ir-utils

Helpers for bridging Rust types to Cranelift JIT signatures and call sites. The crate trims the boilerplate of declaring external functions, building Signatures, and lowering arguments — while keeping direct access to the underlying FunctionBuilder and Module.

Rust crates.io MIT Cranelift 0.132 proc-macro

The path from Rust to machine code

Rust fn
#[jit_export] → JitParam / JitArg
types & values — jit_signature! → Cranelift JIT
Signature · FunctionBuilder → extern "C" fn
finalized pointer

JitParam — type-level: how a Rust type expands into Cranelift AbiParams, so a &str becomes a (ptr, len) pair.

JitArg — value-level: how a Rust value lowers into one or more ir::Values. Implemented for constants, raw pointers, and &'static refs / slices.

API surface

A small trait + macro core, plus a proc-macro that generates a per-function helper module. Optional modules are gated behind features, all off by default.

TraitsJitParam · JitArg · IntoReturns

Macrosjit_signature! · jit_call! · define_jit_fn! · define_function

#[jit_export]<fn>_jit::{ register · signature · declare · try_declare · call }

disasdefine_function_with_disasm · format_disassembly — Capstone opcode dump

simSimulator · SimValue · SimResult — IR interpreter with trace & hexdump

chronoJitNaiveDate · JitNaiveTime · JitNaiveDateTime

tokiospawn_blocking_build — run the compile step off the async executor

Install

Published on crates.io. Add it plain, or turn on the optional modules.

> cargo add lower-ir-utils

> cargo add lower-ir-utils --features disas,sim,chrono,tokio

CI runs the suite on x86_64 and aarch64 across Linux, macOS, and Windows. Full API docs on docs.rs.

Design details

Tuple returns stay honest

A tuple-returning export hands back a Cranelift Inst rather than a fixed [Value; N] — multi-lane fields like &str push more than one ABI slot each, so a fixed shape would silently drop lanes.

Static references as immediates

JitArg for &'static T embeds a host reference as a single pointer immediate — preferred over raw pointers, with the 'static bound guaranteeing the pointee outlives every JIT invocation.

ABI & calling conventions

A long-form doc covers pointer passing vs. #[repr(C)], the opaque-handle pattern for non-repr(C) types, returning owned data, and the Windows-x64 fat-pointer caveat — each claim cited to its source.

← all projects github.com/glslang/lower-ir-utils ↗