PickleIR

The typed, block-structured IR the backend consumes, with real output.

vlatest

Compilation lowers a checked module to PickleIR, and the backend lowers that to machine code. PickleIR is deliberately small: it is a flat list of functions, each a list of basic blocks, each block a list of instructions and exactly one terminator.

A worked example

Given this module:

fn add(a: int, b: int) -> int {
    return a + b
}

fn main() {
    println(add(2, 3))
}

pickle ir prints:

fn add(a: int64, b: int64) -> int64 @pkl_add
  @entry:
    t0 = load slot s0
    t1 = load slot s1
    t2 = binop.add t0, t1
    return t2

  @1:
    unreachable

main fn main() -> unit @pickle_main
  @entry:
    t0 = const 2
    t1 = const 3
    t2 = call fn#0(t0, t1)
    call extern#0(t2)
    call extern#1()
    t3 = const 0
    return

Things worth reading off that output:

  • Types are lowered. int is already int64 at this point, and main is -> unit.
  • Symbols are mangled. add becomes @pkl_add; the backend needs a collision-free symbol, not a source name.
  • Parameters arrive in slots. s0 and s1 are the incoming arguments, and load slot reads them.
  • Values are SSA-style temporaries. Every result is a fresh tN. There is no reassignment of a temporary.
  • Blocks are explicit and unstructured. @entry is the entry block and @1 is a numbered block, with no loop or while concept. Control flow is unreachable at the end of a block that always returns.
  • Calls name their callee. call fn#0 is a module function; call extern#N is a runtime symbol. println is two externs here, one per argument it formats.

The type set is seven types wide

This is the single most important fact about PickleIR:

enum IrTy {
    Bool
    Char
    Int
    Float
    Str
    Unit
    Ptr
}

There is no List, no Map, no class, no struct, no tuple and no option type in the IR. Every aggregate is a Ptr. That is the mechanical reason lists, maps, class instances and structs have reference semantics and identity == in the language above, by the time a value reaches the backend, "list" and "map" and "class instance" are all just an address.

Temporaries, slots and blocks

Values are referred to by plain integer index rather than by a typed handle:

Reference What it identifies
A temporary index An SSA value inside a function
A slot index A parameter or local that outlives a single expression
A block index A label, with @entry and @N naming them in the text form
An index into IrModule.strings An interned string
An index into IrModule.funcs A function in the module
An index into IrModule.externs A runtime symbol

Constants

enum IrConst {
    Int(v: int)
    Float(v: float)
    Bool(b: bool)
    Char(c: char)
    Null
    Str(id: int)
}

Str holds an index into the module's string table, so the same literal lowered twice refers to one entry. Null is the only non-value constant and stands for the absence of a value.

Instructions and terminators

The whole instruction set:

Const  UnOp  BinOp  Copy  Itof  Ftoi  Chartoi  Itochar
LoadSlot  StoreSlot  LocalAddr  LoadRaw  StoreRaw  Call  CallInd

and the whole terminator set:

Branch  BranchIf  Return  Unreachable

UnOp is Neg, Not, BitNot. BinOp is Add, Sub, Mul, Div, Mod, Shl, Shr, BitAnd, BitOr, BitXor, Eq, Ne, Lt, Le, Gt, Ge, so every comparison in the language is one instruction, and there is no separate compare-and-branch.

The Raw and LocalAddr instructions are the unsafe surface: they are how &x, *p and a store through a pointer reach the backend.

Call names a Callee, which is either Func(id: int) into the module's function table or Extern(id: int) into its extern table. CallInd is the indirect form, used when the callee is a function value.

IRX: the lossless form

pickle irx writes the same IR as text with nothing thrown away, including the full extern and string tables and per-function slots, tags and entry point. Names are hex-encoded so the format is byte-exact:

irx externs 2
extern 0 7069636b6c655f7072696e745f693634
esig int64 unit
extern 1 7069636b6c655f7072696e745f6e65776c696e65
esig  unit
irx strings 0
irx funcs 2
func 0 616464 706b6c5f616464 0 0 0 int64
params 2 61 int64 62 int64
slots 2 int64 int64
tags 0
blocks 2
block 0
load 0 0
load 1 1
binop 2 add 0 1
return 2
block 1
unreachable

7069636b6c655f7072696e745f693634 is pickle_print_i64 and 7069636b6c655f7072696e745f6e65776c696e65 is pickle_print_newline, which is where the two extern calls in the ir output above come from.

pickle irx-run parses an IRX file back into a module and runs its main with the JIT. The round trip is exact, it re-parses into the same module, which is what makes IRX a stable, diffable contract you can check in CI.