Crate boomslang_hostgen

Code generator for typed boomslang host extensions.

An extension declares host functions that Python code (running on CPython compiled to WASM) can call into the embedding Java or Rust host. The declaration lives in the extension crate’s build.rs, written with the builder DSL in this crate: ExtensionSpec describes the extension and its functions, and Build selects which artifacts to emit before Build::generate writes them out. The primary artifacts are a Rust guest module (PyO3 wrappers plus WASM imports, written to OUT_DIR) and an ABI JSON contract; the ABI JSON in turn drives host adapter generation — either via the boomslang-hostgen CLI or the generate_java / generate_rust_host functions — so hosts can be regenerated without rebuilding the guest.

Examples

A typical build.rs:

use boomslang_hostgen::{Build, ExtensionSpec, Type};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let ext = ExtensionSpec::new("myext")
        .wasm_module("myext")
        .prewarm(["myext_support"])
        .function("do_thing", |f| {
            f.param("input", Type::String).returns(Type::String)
        });

    Build::new(ext).emit().generate()
}

The extension crate then consumes the generated guest module with include!(concat!(env!("OUT_DIR"), "/ext_myext.rs")); and calls the included register() function to add the Python module to CPython’s init table.

Structs

Build

Selects which artifacts to generate from an ExtensionSpec.

Extension

Extension-level metadata within a Manifest.

ExtensionSpec

Builder for an extension Manifest, used from build.rs.

Function

A single host function exposed to Python.

FunctionSpec

Builder for a single Function, used inside ExtensionSpec::function.

Manifest

The full extension contract: ABI version, extension metadata, and the list of host functions.

Param

A typed parameter of a Function.

Enums

Type

Value types supported across the guest/host boundary.

Functions

generate_java

Generates Java (Chicory) host function bindings from an ABI JSON file.

generate_java_code

Renders the Java (Chicory) host adapter source for a manifest: a <Name>HostFunctions class in the given package, with typed handler interfaces and Chicory HostFunction registrations. Unlike generate_java, this function does not validate the manifest.

generate_rust_code

Renders the Rust guest module source for a manifest: WASM import declarations, PyO3 wrapper functions, and the register()/prewarm() entry points. Build::emit_rust_guest writes this to $OUT_DIR/ext_<name>.rs; unlike Build::generate, this function does not validate the manifest.

generate_rust_host

Generates Rust (Wasmtime) host function bindings from an ABI JSON file.

generate_rust_host_code

Renders the Rust (Wasmtime) host adapter source for a manifest: a <Name>HostFunctions struct with a builder for wiring typed handler closures into a Wasmtime linker. Validates the manifest first.

read_abi

Reads and validates an ABI JSON file (see Manifest for the validation rules, including the exact ABI version check).