ilusm.dev

boot

Bootstrap orchestrator - compile ilusm source to ILBC bytecode or C, verify ILBC blobs, run programs via the VM, self-test the toolchain, and generate a minimal standalone C loader.

Load with: use boot

What this module does

boot is the top-level entry point for self-hosting ilusm. It bundles the full compilation pipeline - linking, IR optimisation, bytecode or C emission - into a handful of straightforward calls.

Compile to ILBC: bundles all sources under lib_root via link.bundle, runs IR optimisation, emits the ILBC binary, and writes it to ilusm.ilbc.

Compile to C: same pipeline but emits a standalone C source file instead of bytecode - useful for embedding ilusm in C projects or compiling with a native C compiler.

Verify: reads an ILBC blob, decodes it with mcdun, validates with mcdok, and reports opcode and constant counts.

Stub: generates the source text of a minimal C ILBC loader - a self-contained 200-line C program with a value type, syscall stubs, an ILBC parser, and a tiny stack-machine interpreter.

Quick example

use boot
use prs  # your parser

# Compile the whole stdlib to ILBC
r = boot.compile("/path/to/lib", prs.prs_src_at)
# boot: compiled 8241 stmts -> 131072 bytes -> ilusm.ilbc

# Verify the result
v = boot.verify("ilusm.ilbc")
# boot: verified ilusm.ilbc (2048 opcodes, 512 consts)

# Run via VM
boot.run("ilusm.ilbc", "main", "/path/to/lib")

# Full self-test (compile + verify + smoke test)
boot.self_test(prs.prs_src_at)

# Get a minimal C stub loader as a string
c_src = boot.stub()
fs.wr("loader.c", c_src)

Functions

Compilation

boot.compile(lib_root, parse_fn)

Full pipeline to ILBC. Calls link.bundle(lib_root, parse_fn), optimises with ir.opt, emits bytecode with ir.to_bc, and packs to ilusm.ilbc with emit.ilbc. Prints compiled statement count and output size. Returns {sz, path}.

boot.compile_to_c(lib_root, parse_fn)

Full pipeline to C source. Bundles and optimises as above, then emits standalone C to ilusm.c with emit.c. Returns {path, sz}.

Verification and execution

boot.verify(ilbc_path)

Reads an ILBC blob from disk via host.read, decodes with mcdun, validates with mcdok. Prints opcode and constant counts. Returns {ok: tru, prog}. Errors if the file cannot be read or the blob is empty.

boot.run(ilbc_path, entry_fn, lib_root)

Verifies then executes the program via vmrun(prog, entry_fn).

Self-test

boot.self_test(parse_fn)

Runs a full smoke test: compiles from __ilusm_lib, verifies the resulting ILBC, and reports pass/fail. Returns {ok: tru} on success.

C loader stub

boot.stub()

Returns a string containing a complete, self-contained C program (~180 lines) that:

  • Defines ilusm value types (nil, num, str, bool, list, obj, fun, builtin)
  • Implements host syscalls: read/write file, stdout, argv, time, exit
  • Parses the ILBC header (magic "ILBC", 56-byte header)
  • Runs a simple stack-machine VM (STACK_MAX 65536) with NOP, NIL, TRU, FLS, HLT opcodes
Write this to a .c file and compile with any C compiler to get a minimal ilusm ILBC runner.

Notes

  • parse_fn must have the signature fn(src, path) -> {ok, pr, er}.
  • __ilusm_lib is a host native that returns the stdlib root path.
  • The stub VM only implements 5 opcodes - it is a skeleton, not a full runtime.
  • Requires trl, txt, host, link, ir, and emit.