nybl-compile
Ahead-of-time Nybl → Rust transpiler.
Given Nybl source, nybl-compile::transpile produces human-readable Rust source
that links against nybl-lang and compiles
via cargo to native code. Standalone generated binaries also use
nybl-sys; library-shaped output can use
your own host without that dependency. This is the fastest of Nybl's three
engines.
When to reach for the AOT
- Scripts you'll run repeatedly — builds once, runs at native speed forever after.
- Performance-sensitive workloads — where even the bytecode VM's 2–3× speedup isn't enough.
- Deploying a script as a self-contained binary —
nybl compile script.nybland ship the resulting executable.
For scripts you compile at the host's runtime, the bytecode VM in nybl-vm is the right choice instead — AOT needs rustc on the target machine, which embedded hosts typically can't rely on.
CLI usage (the common path)
Most users never call nybl-compile directly; they use nybl-cli:
Library usage
When you want to wire the transpiler into your own build pipeline (a build.rs, a custom tool, a CI job):
[]
= "0.5"
use ;
let rust_source = transpile?;
// write rust_source to src/main.rs and run `cargo build`…
Options controls the output shape: standalone program vs. library, module name wrapping, sandbox mode for step, memory, call-depth, and nesting enforcement (module loads share the budgets and cost one step per token, as in the walker and VM), and the module resolver callback for use statements.
Persistent sandboxed output
Sandbox mode can generate a stateful library surface for plugin-style AOT
embedding. Mark direct root entries with pub fn, disable main, and compile
the generated Rust into the host application:
let rust_source = transpile?;
The generated module exposes NyblInstance::load(host, limits),
entry_points(), call(name, args, host), and
call_value(callback, args, host). It retains program and module state across
calls and enforces instance affinity, re-entry, and resource limits.
The persistent API is sandbox-only. Unsandboxed generated output retains its
one-shot run API. See the stateful embedding
guide for the
full lifecycle contract.
Generated Rust preserves Nybl's transactional ref semantics in both sandboxed
and unsandboxed output: explicit parameter modes, valid-target checks,
copy-in/copy-out staging, multi-target commit, error rollback, forwarding, and
mutating receiver behavior match the walker and VM. Generated persistent
NyblInstance calls remain value-only. See the reference-parameters
guide.
User-defined ref self receivers share that transaction with any explicit ref
arguments, while ordinary self receivers are read-only.
Selling points
- Native-speed scripts. The transpiled output is ordinary Rust — rustc optimises it the same way it optimises hand-written code.
- Human-readable output. User-defined Nybl functions become top-level Rust fns with reasonable names, so the generated code is debuggable.
- Same semantics as walker + VM. The three-engine differential suite exercises hundreds of programs to catch any behavioural drift.
- Same
NyblHostsurface. The generated binary usesnybl-sys::StdHostby default, so your custom hosts work without changes.
Features
| feature | default | what it does |
|---|---|---|
nybl-std |
yes | forwards to nybl-lang's nybl-std feature (bundles the Nybl stdlib). Turn off with default-features = false when building a truly minimal AOT pipeline. |
Related crates
nybl-lang— the language core the generated code depends onnybl-sys— the standard host the generatedmain()wires upnybl-cli— thenybl compilecommand-line drivernybl-vm— bytecode VM, for when you need speed at the host's runtime rather than AOT
License
Dual-licensed under MIT or Apache 2.0, at your option.