bcgen-lang 0.2.0

The model

• compile takes a resolved hir_lang::Hir and the interner its names came from, and returns a Compiled: the LSB module, its entry function, and an origin table mapping every instruction to its HIR node.
• Compiler adds Options (array semantics, key coercion, what the module body compiles to, hooks, budgets) and a Locate for real line numbers in the line tables (LineIndex for one source file).
• CompileError says why a unit does not compile, naming the HIR node and its span; Unsupported names the forms planned for later releases.

What it guarantees, and how each guarantee is checked:

Installation

[dependencies]

bcgen-lang = "0.2"

Without the standard library:

[dependencies]

bcgen-lang = { version = "0.2", default-features = false }

Quick start

Compile a unit and run it on bvm-lang:

use bvm_lang::{Host, Program, Value, Vm};
use hir_lang::{Builder, Name, OpKind};
use intern_lang::Interner;

// fn add(a, b) { a + b }
let mut names = Interner::new();
let mut b = Builder::new();
let (pa, a) = b.local_param(Name::new(names.intern("a")));
let (pb, bb) = b.local_param(Name::new(names.intern("b")));
let (ua, ub) = (b.use_binder(a), b.use_binder(bb));
let sum = b.op(OpKind::Add, &[ua, ub]);
let body = b.block(&[], Some(sum));
let add = b.func(Name::new(names.intern("add")), &[pa, pb], body);
let root = b.module(None, &[add]);
let hir = b.finish(root)?;

let out = bcgen_lang::compile(&hir, &names)?;
let func = out.function(add).unwrap();
let program = Program::load(out.into_module(), &Host::new())?;
let mut vm = Vm::new(&program);
assert_eq!(vm.run(func, &[Value::Int(2), Value::Int(3)])?, Value::Int(5));
# Ok::<(), Box<dyn std::error::Error>>(())

Scripts, host functions, and source lines

A module body runs in the module's start function and the entry function returns its value. Host symbols (Res::Extern) become LSB imports:

use bcgen_lang::{Compiler, LineIndex, Options};
use bvm_lang::{Host, Program, Value, Vm};
use hir_lang::{Builder, Effects, Expr, Item, ItemKind, List, Name, Ns, Path, Res, Segment};
use intern_lang::Interner;

// echo("hello"); 42
let mut names = Interner::new();
let mut b = Builder::new();
let echo = names.intern("echo");
let seg = Segment::new(Name::new(echo), b.origin());
let segs = b.list(&[seg]);
let path = b.path(Path { res: Res::Extern(echo), ..Path::new(segs, Ns::Value) });
let callee = b.expr(Expr::Path(path));
let hello = b.str_lit("hello");
let call = b.call(callee, &[hello]);
let stmt = b.expr_stmt(call);
let answer = b.int(42);
let body = b.block(&[stmt], Some(answer));
let module = ItemKind::Module { items: List::EMPTY, body: Some(body), effects: Effects::NONE };
let root = b.item(Item::new(None, module));
let hir = b.finish(root)?;

let lines = LineIndex::new("hello.mox", 0, "echo(\"hello\"); 42\n");
let out = Compiler::new(Options::new()).with_locator(&lines).compile(&hir, &names)?;

let mut host = Host::new();
host.register("host", "echo", |ctx, args| {
    assert_eq!(ctx.str_bytes(args[0]), Some(&b"hello"[..]));
    Ok(Value::Nil)
});
let program = Program::load(out.module().clone(), &host)?;
assert_eq!(Vm::new(&program).run(out.entry(), &[])?, Value::Int(42));
# Ok::<(), Box<dyn std::error::Error>>(())

The full reference, including the calling convention, the dynamic semantics of every form, and what each option changes, is in docs/API.md.

Performance

Release build on the development machine (Windows 11), criterion medians from benches/bench.rs. Compile figures are library-only (HIR in memory to an LSB module, no encoding); run figures are bvm-lang 2.0.0-alpha.1 executing the compiled module (VM instance creation included).

"Nodes" counts items, expressions, statements, patterns, paths, and parameters. Compile time is linear: tests/scaling.rs measures 150 to 170 ns per node from 146k to 2.3M nodes (the criterion spread above is allocator noise around that). The last row is the cost of PHP nested-write separation: LSB cannot ask whether an inner array is shared, so every nested write copies the inner array's store while the old copy is uncollected (about 28 times the plain-append case here). An LSB instruction that separates only when shared is requested from the spec owners.

Contributing

See dev/DIRECTIVES.md for engineering standards and the definition of done. Before a PR: cargo fmt --all, cargo clippy --all-targets --all-features -- -D warnings, and cargo test --all-features must be clean.