ilusm.dev

emit

Unified compiler output layer - takes a compiled ilusm program object and writes it to disk in one of several formats: ILBC bytecode blob, C source via cgen, human-readable disassembly text, Graphviz DOT AST graph, or raw JSON.

Load with: use emit

What this module does

emit is the final stage of the ilusm compilation pipeline. After the parser produces an AST and the compiler lowers it to a program object {cd, cs, nm, df}, emit provides the output adapters that materialise that program as files or strings in different formats.

  • ILBC - binary bytecode blob via mcdpa, written to disk.
  • C source - human-readable C via cgen.prog, written to disk.
  • Assembly text - disassembly of the bytecode instruction stream, left-padded with program counters.
  • DOT - Graphviz digraph of the AST node tree, useful for visualising compiler output.
  • JSON - raw JSON encoding of the program object.

Quick example

use emit
use cmp_prs   # or your compiler pipeline

prog = compile_to_prog("src/main.ilu")

# Write ILBC bytecode
r = emit.ilbc(prog, "out/main.ilbc")
prn(r.sz)  # bytes written

# Write C source
r = emit.c(prog, "out/main.c")

# Print disassembly to stdout
prn(emit.asm_text(prog))

# Visualise AST as DOT
fs.wr("out/ast.dot", emit.dot(prog))

# Dump as JSON
prn(emit.json(prog))

Functions

File output

emit.ilbc(prog, path)

Packs the program object into ILBC binary format using mcdpa and writes it to path via host.write. Returns {ok: tru, path, sz} where sz is the blob size in bytes.

emit.c(prog, path)

Generates C source from the program's AST using cgen.prog and writes it to path. Returns {ok: tru, path, sz}. Requires the cgen module to be loaded.

String output

emit.asm_text(prog)

Disassembles the bytecode instruction stream in prog.cd. Each instruction is formatted as a right-padded program counter followed by the opcode mnemonic and optional 16-bit operand (little-endian). Returns the full disassembly as a newline-separated string.

emit.dot(prog)

Walks the AST recursively and emits a Graphviz digraph AST { ... } string with box-shaped nodes labelled by node type and optional name field. Child edges are drawn for st, bd, th, el, l, r, v, fn, and ar fields.

emit.json(prog)

Returns the program object encoded as a JSON string using host.json_enc.

Notes

  • emit.ilbc requires the mcd (bytecode) module. emit.c requires the cgen module. Both must be loaded before calling the corresponding emit function.
  • Requires trl and host.