Use in Rust projects

pd-vm is the RustScript virtual machine and compiler toolchain. An embedding application controls which host functions are registered and executes compiled RSS through the VM.

Add dependencies

The RustScript README provides these dependency declarations:

rustscript = "0.22.2"
pd-vm = { git = "https://github.com/rustscript-lang/rustscript", package = "pd-vm" }
pd-host-function = { git = "https://github.com/rustscript-lang/rustscript", package = "pd-host-function" }

Compile and execute

This complete Rust program compiles an inline RustScript program, runs it until it halts, and reads the result from the VM stack:

use rustscript::{Value, Vm, VmStatus, compile_source};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let compiled = compile_source(
        r#"
        let answer: int = 40 + 2;
        answer;
        "#,
    )?;
    let mut vm = Vm::new(compiled.program);

    loop {
        match vm.run()? {
            VmStatus::Halted => break,
            VmStatus::Yielded => continue,
            VmStatus::Waiting(_) => vm.wait_for_host_op_blocking()?,
        }
    }

    assert_eq!(vm.stack(), [Value::Int(42)]);
    println!("RustScript result: {:?}", vm.stack());
    Ok(())
}

Running it with cargo run prints RustScript result: [Int(42)].

An embedding application follows this boundary:

1. Compile RSS source with pd-vm. 2. Install only the host modules the application wants to expose, using an ordered HostModuleDescriptor. 3. Create a VM or store with the compiled program. 4. Run or resume execution and handle the returned status.

The host functions document descriptors, typed resource effects, hidden host state, named structs, namespaces, and the compatibility window. Use runtime controls for fuel, epoch interruption, recording, VMBC, JIT, WebAssembly, and no_std modes.

Compatibility frontends

RustScript is the built-in .rss frontend. JavaScript and Lua use source-plugin crates and are compiled from an embedding application through CompileSourceFileOptions and its with_source_plugin(...) builder method.