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.4"
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 enforcement, 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.