zplugin
Define a Rust trait, implement it in a cdylib, and call it through a typed host
proxy. zplugin uses a frozen target-platform C ABI, cached function tables, and
explicit library lifetimes. The default runtime is no_std, needs no allocator,
and has zero third-party runtime dependencies.
The same interface also generates C/C++ headers; Zig imports a module translated
from those headers. Additive
extension records support checked structs/enums, owned resources, callbacks,
and cross-library tasks that the Rust host can .await.
For untrusted plugins, enable the separate wasm backend: validated Wasm32
bytecode, no host imports, finite execution fuel, and bounded guest memory.
Native .so/.dylib/.dll loading still requires trusted code.
Rust 1.85.0 or newer; edition 2024. Development toolchain: 1.100.0, the stable release published on 2026-11-12. Native loading targets Linux, macOS, and Windows; see the 0.2.0 delivery record for tested machines and compiler combinations. This is a library of primitives, with no background watcher, runtime, transport, or plugin discovery service. The optional Wasm host needs Rust 1.86 or newer; native/default features retain Rust 1.85. Wasm guest code can use the default allocator-free crate.
Install
Shared interface crate:
[]
= { = "0.3.0", = ["macros"] }
Plugin and host crates can enable std independently. The interface itself may
remain no_std. The optional procedural macro depends on syn, quote, and
proc-macro2 at compile time; these are not linked into the runtime.
Define an interface
The macro generates CalculatorApi, CalculatorBinding, CalculatorProxy, and
CalculatorExport<T>. Argument names may change; method order, names, receiver
kind, types, and results define the frozen interface. Change its version when
changing that contract.
Implement a plugin
Use the shared interface crate as a dependency and configure the plugin:
[]
= ["cdylib"]
[]
= { = "0.3.0", = ["std", "macros"] }
= { = "../calculator-api" }
use ;
use ;
;
export!;
The pinned policy keeps the image resident until process exit. To opt into
cooperative unloading, implement the unsafe zplugin::export::UnloadSafe contract
for the implementation, use unload = cooperative, and select the same policy
when loading. The complete runnable example contains that implementation.
Load and call
use CalculatorApi;
use ;
// SAFETY: this file and its dependencies are trusted, and obey the v1 ABI.
let library = unsafe ;
let mut calculator = create?;
assert_eq!;
let mut output = ;
let count = calculator.copy?;
assert_eq!;
# Ok::
Use .dylib on macOS and .dll on Windows. load_path preserves native Unicode
paths. Without std, Plugin::load(&CStr) is available; on Windows its narrow
path uses the ANSI code page, and Plugin::load_wide accepts UTF-16 without alloc.
The proxy borrows its library, so Rust rejects dropping that library first. For an
independent owning proxy, enable alloc, put the plugin in Rc<Plugin>, and call
CalculatorApi::wrap(Plugin::create_owned(&library, CalculatorApi::SPEC)?).
Cloning occurs when acquiring resources; ordinary calls do not clone a lease.
Run the complete example
The repository includes separate interface, plugin, and host crates:
On macOS substitute libdemo_plugin.dylib; on Windows use demo_plugin.dll.
See examples/README.md for the directory structure, full
Cargo configuration, explicit snapshot/restore, and owned outputs.
Supported boundaries
| Rust interface type | Boundary representation |
|---|---|
u8/u16/u32/u64, i8/i16/i32/i64, f32/f64 |
Fixed-width C ABI scalar |
&[u8], &mut [u8] |
Pointer and native size_t length; one call only |
&str |
Validated UTF-8 view; one call only |
Result<T, zplugin::Error> / zplugin::Result<T> |
Signed status plus initialized success output |
() or scalar success |
No output or fixed-width result record |
zplugin::OwnedBytes success |
Buffer, origin release callback, independent library lease |
| Plugin object | Opaque plugin allocation and matching destroy function |
#[zplugin::abi_type] struct or enum |
Recursive C-layout record or checked tag/payload; independent of Rust layout |
zplugin::OwnedResource success |
Versioned opaque resource with call/release table and independent library lease |
zplugin::CallbackRef<'_> input |
Borrowed callback with explicit retain/invoke/release protocol |
zplugin::OwnedTask<T> success |
Task handle with poll/cancel/release; host receives Task<T>: Future with alloc |
Unsupported signatures produce compile errors: generics, direct async fn, default methods,
associated types, conditional methods, usize/isize, bool/char, 128-bit
integers, unannotated structs, native String/Vec/Box/Arc, and native Future layouts.
Stable values require Copy + Clone; reference, owned, generic and array fields
are excluded. Task outputs use AbiValue, including nested structs/enums and unit.
Plugin internals may use ordinary Rust facilities and dependencies.
Asynchronous and cross-language plugins
The interface declares a task factory, so borrowed input ends at the factory call:
#
;
#
The generated host proxy returns a lease-owning Task<u64>: use
jobs.start(41)?.await?, or cancel() for cooperative cancellation. Polling,
cancelling and destruction stay on the creating thread; retained wakers support
concurrent notification. No native Future or Waker layout crosses the boundary.
The plugin manages any runtime it needs. Dropping a future does not implicitly
shut down an external executor; cooperative unloading requires workers and
callback return paths to be fully joined/drained.
JobsApi::write_c_header(&mut writer) emits the exact argument layouts, method
signatures and descriptor helpers. C11 and C++17 include the header; Zig
uses its automatically translated module. The generator itself writes through
core::fmt::Write without needing an allocator.
See the async three-crate example, the complete C/C++/Zig example, and the extension protocol and ownership rules.
Features
| Feature | Additional capability | Runtime dependency |
|---|---|---|
| default: none | ABI, native loader, borrowed instances, manual resource/factory contracts | core and platform loader |
alloc |
Factories, Rc leases, owned bytes/resources, closure callbacks, Future/Waker adapters |
Rust allocator |
std |
Native paths, error integration, panic containment | std, implies alloc |
macros |
Trait-to-ABI generation | Compilation-only macro crate |
hot-reload |
Bounded generations and request leases | alloc |
wasm |
Import-free, fuel-metered Wasm32 sandbox; separate byte-buffer protocol | alloc + Wasmi 2.0 and its dependencies; Rust 1.86+ |
For allocator-free plugins, implement the public ABI with application-owned
object storage. export::Object<T> and the entrypoint guards also work without
an allocator. Convenience export! factories deliberately require alloc.
Untrusted Wasm plugins
The host opts in explicitly; the default native runtime stays dependency-free:
[]
= { = "0.3.0", = ["wasm"] }
use ;
let interface = Interface ;
// bytes is an untrusted binary Wasm module; this API is safe to call.
let mut plugin = new?;
let mut output = ;
let written = plugin.call?;
assert_eq!;
# Ok::
Implement wasm_guest::Guest, export it with export_wasm!, and compile for
wasm32-unknown-unknown. The complete guest and
host run with:
Wasm calls use numeric operations and bounded byte buffers. Input/output are
copied across the memory boundary; native trait proxies, handles, callbacks,
and async tasks are not forwarded into the sandbox. No WASI, filesystem,
network, environment, clock or process capabilities are granted. Module imports
and start sections are rejected. A trap exhausts/invalidates that instance, not
the native host's call stack; subsequent use returns Poisoned.
This is an in-process Wasm sandbox whose isolation depends on the engine. Guest-memory limits do not cap process RSS, and fuel is not a compilation-time deadline. Use additional OS process isolation for strict total-memory/time bounds or protection against engine vulnerabilities. See protocol, policy and evidence. Reproducible sandbox timings and allocation measurements are in the 0.3.0 Wasm performance report.
Multiple interfaces and hot switching
export_interfaces! exports independently versioned interfaces through one entry:
export_interfaces!;
With hot-reload, hot::Generations::new(plugin, maximum_retired) tracks the
current image and old generations. current() acquires a request/session lease.
reload or reload_path loads an independent image, runs your creation/restore
closure, and switches only on success. Old objects continue using their old code.
Use an explicitly versioned byte snapshot for state migration. collect() asks
unreferenced cooperative generations to retire; Busy generations remain and
count toward the limit. No timeout forces an unload.
Safety and performance
Loading trusted native code remains unsafe: initializers and methods execute
with the host's privileges. ABI checks detect incompatible metadata; native code
must still honor memory validity, ownership, and unwind contracts. Proxies are
neither Send nor Sync; all calls, including shared trait methods, require a
mutable proxy. Same-object raw reentry returns Busy before a second borrow.
Under std and an unwind-enabled plugin build, adapters catch Rust panics on the
plugin side and poison that instance. panic=abort, foreign exceptions, and
native crashes retain their process-level behavior. C++ plugins contain their
own exceptions before returning; the C++ example includes that boundary.
Task/callback extensions use independent size/version-prefixed tables. Failed
resource cleanup prevents cooperative unloading, including a future or callback
capture destructor that panics.
Steady native borrowed calls use cached function pointers without forced allocation,
serialization, symbol lookup, or per-call reference counting. Actual comparisons
against inline/noinline calls, cached C pointers and cached libloading symbols
are in the 0.2.0 performance report, including
three raw runs, task initialization, reused/changed wakers, and worker shutdown.
An inline static call remains a distinct, cheaper baseline for tiny functions.
Validation and release
CI runs actual hosts and dynamic libraries on Linux, macOS, and Windows, plus
Rust 1.85.0/stable, core-only embedded/WASM compilation, negative macro fixtures,
and release transaction tests. Wasm also runs on all three native host platforms,
with Rust 1.86 engine-MSRV/no_std checks and independently built guest/host pairs.
The manual release workflow supports
patch/minor/major/custom, dry_run, exact-commit validation, dependency-ordered
publication, and recovery after a partial upload. It uses the step-scoped
CARGO_REGISTRY_TOKEN secret. See release operations.
Further detail: ABI and ownership, validation evidence, changelog. Licensed MIT OR Apache-2.0.