Crate ruka_mir

Source
Expand description

§MIR (Current)

This module defines the MIR used by the compiler today.

§Where MIR Sits in the Pipeline

Current flow:

  1. Parse source (ruka_syntax)
  2. Expand meta
  3. Elaborate/check types
  4. Lower checked HIR to MIR (ruka_mir_lower)
  5. Lower MIR to Rust (ruka_codegen_rust) and/or WASM (ruka_codegen_wasm)

Execution is backend-driven. There is no MIR interpreter.

§Core MIR Shape

MIR is CFG-backed and local-slot oriented:

MirStmt is a structured lowering helper used before final CFG assembly. The canonical stored form is MirFunction { entry, blocks, ... }.

§Locals, Slots, and Semantics

Every value/place in MIR flows through a MirLocalId slot with metadata in LocalInfo:

  • kind (Param, Binding, Temp) = provenance
  • ty = semantic type
  • repr = runtime representation

Representation is explicit via MirLocalRepr:

  • Value: direct runtime value
  • SharedPlace: read-only place/reference
  • MutablePlace: mutable place/reference

Important: local names are debug/viewer/backend identifiers only. Semantics come from ty + repr + producing instructions, not from the spelling.

§Naming Scheme (p_, v_, t_)

Stable naming is produced by ruka_mir::naming::FunctionNames:

  • params -> p_<name> or p_<local-index>
  • source bindings -> v_<name> or v_<local-index>
  • compiler temps -> t_<name> or t_<local-index>

Names are sanitized to Rust identifiers and uniqued (_2, _3, …).

So a name like v_1 means:

  • this slot is categorized as a binding-style local (v_ prefix), and
  • fallback naming used local index 1 (or sanitized source text produced 1).

It does not imply ownership or mutability by itself.

§How Lowering Builds MIR

Lowering is implemented in ruka_mir_lower.

High-level strategy:

  1. Predeclare function IDs in MirProgram.
  2. Lower each checked HIR function with FunctionLowerer.
  3. Build structured MirStmt trees for control flow.
  4. Convert structured form to final CFG blocks/terminators.

Per-function lowering tracks lexical scopes with name -> MirLocalId maps and scope-owned locals for release scheduling.

§Key Lowering Decisions

  • let @x = expr creates a value local.
  • let x = ident aliases existing local slot when possible.
  • let x = place_expr can produce a shared place local.
  • let &x = place_expr produces a mutable place local.
  • <- lowering emits moves from named bindings.

Borrowable place expressions lower through borrow instructions:

  • IndexBorrowRo/Mut
  • SliceBorrowRo/Mut
  • FieldBorrowRo/Mut
  • PointerBorrowRo/Mut

Plain reads from place locals use DerefCopy when a value is needed.

§Ownership and Lifetime Ops Inserted in MIR

Lowering inserts explicit ownership instructions where needed:

  • ReleaseHeap before overwrite and at scope exit

This gives both backends a shared ownership intent model.

§What a Local Name Lowers To in Backends

§Rust backend

ruka_codegen_rust uses FunctionNames directly, so MIR local names appear as Rust local identifiers (for example, v_counter, t_7).

  • value locals lower to ordinary Rust values
  • place locals lower to Rust reference-shaped values (&T/&mut T behavior)
  • unread temporaries may lower to let _ = ... discard bindings

§WASM backend

ruka_codegen_wasm does not preserve textual local names in generated code. Instead, it maps each MirLocalId to:

  • a runtime wasm local index (LocalId) and value type (ValType), or
  • no runtime local for unit-typed locals

Place locals lower as pointer-sized runtime values (i32), with additional handling for passthrough place params and shadow-stack aggregate storage.

So v_1 in MIR/debug views corresponds to an internal slot identity that can become a Rust local name, but in WASM it becomes an index-based runtime local.

§Instruction Surface (Current)

See MirInstr for the complete list. Families include:

  • constants and aggregate construction
  • copy/move/assign/store/deref operations
  • place borrow operations (index/slice/field/pointer)
  • call/external call/intrinsic calls
  • enum/struct field operations
  • integer arithmetic and comparisons
  • explicit ownership ops (ReleaseHeap)

§Testing Coverage

Current tests validate that:

  • HIR-to-MIR lowering succeeds across fixtures and targeted cases
  • control flow lowers into valid CFG form
  • borrow/place operations are emitted for index/slice/field/pointer paths
  • Rust/WASM codegen accepts current MIR and passes smoke/runtime tests

Modules§

browser_graph
Browser-friendly MIR graph rendering for interactive viewers.
cfg 🔒
ids 🔒
instr 🔒
naming
Stable naming helpers for MIR-based outputs. Stable naming helpers used by MIR browser graphs and backends.
types 🔒

Structs§

LocalInfo
Metadata tracked for each MIR local.
MirAggregateArg
Single aggregate construction argument with explicit ownership mode.
MirBlock
Basic block in MIR CFG.
MirBlockId
Basic block identifier in function-local MIR block storage.
MirCallArg
Single call argument with explicit ownership mode.
MirCallArgBinding
Shared call-argument query object used by validation and backends.
MirEnumDecl
Enum declaration retained for backend aggregate emission.
MirEnumVariant
Enum variant declaration for a MIR enum type.
MirFuncId
Function identifier in MIR program storage.
MirFunction
Function-level MIR in CFG form.
MirLocalId
Local identifier for MIR values/bindings/temps.
MirParamBinding
Shared parameter query object used by lowering and backends.
MirProgram
Whole-program MIR container.
MirSourcePos
Source position metadata captured for MIR instructions.
MirStructDecl
Struct declaration retained for backend aggregate emission.
MirStructField
Named field declaration for a MIR struct type.

Enums§

LocalKind
Local provenance category.
MirArgMode
Ownership mode used at MIR call sites.
MirHeapOwnership
Heap ownership policy carried by one MIR local.
MirInstr
MIR instruction set used by lowering and codegen.
MirIntrinsic
Builtin intrinsic operation invoked directly by generated code.
MirLocalRepr
Runtime/storage representation tracked for one MIR local.
MirOwnershipMode
Ownership mode carried into MIR from source function signatures.
MirStmt
Structured lowering helper form.
MirTerminator
Block terminator defining control-flow edges.
MirTypeExpr
Type syntax retained in MIR for emitted aggregate declarations.

Functions§

infer_heap_ownership
Infer heap ownership policy from one local type and representation.