Module plugin_host 

plugin_host submodule — native (Rust) plugin loader (zmodload -R). Native (Rust) plugin host — extension; no zsh C counterpart.

zsh’s Src/module.c dlopens C .so modules that call addbuiltin against the shell’s own symbols. zshrs generalises that into a stable, versioned C ABI (znative crate) so third parties ship a compiled cdylib and load it at runtime with zmodload -R <path> — no zshrs recompile, no zsh script glue. This is the first compiled Unix shell hosting native compiled-language plugins.

Where plugin commands resolve

fusevm compiles command names it does not recognise as builtins into external execution. A freshly-loaded plugin command is therefore unknown at compile time and arrives at crate::vm_helper’s execute_external_bg, which consults [dispatch] BEFORE spawning a process — the same slot zsh uses for zmodload -ab autoloaded builtins (resolvebuiltin). Plugins thus resolve after real builtins and functions, before PATH lookup.

ABI safety

Everything crossing the boundary is #[repr(C)]. The host verifies the plugin’s abi_version matches znative::ABI_VERSION before trusting any pointer it returns; a mismatch is refused (a wrong struct layout would be undefined behaviour). The loaded libloading::Library is kept alive for the process lifetime — its Drop is a dlclose, which would invalidate the still-registered function pointers, so unload explicitly purges the registry first.

Functions

dispatch

Command-resolution hook. Called from execute_external_bg for bare command names. Returns Some(exit_status) if a plugin owns cmd, else None (let PATH lookup proceed).

flush_pending_completions

Install any completion wirings that plugins requested but that have not yet been bound into compsys. Called at the top of the completion pipeline (do_completion) — a safe point where compsys itself evals, unlike plugin-init (deep in the zmodload call stack, where evaling hangs the VM). Idempotent: each pending entry is installed once, then moved to installed_completions.

is_plugin_command

True if name is a live plugin command. Used where callers want to know whether a name resolves to a plugin without invoking it.

list

(name, version, path) for each loaded plugin, for zmodload -R listing. Sorted by name for stable output.

load

Load a plugin cdylib from path. Returns the plugin’s name on success. Idempotent-ish: loading a plugin whose name is already present is refused (unload first).

unload

Unload a plugin by name: purge its command registrations FIRST (so no live function pointer survives), then drop the Library (dlclose).

zmodload_rust_cmd

zmodload -R native-plugin management, dispatched from crate::ported::module::bin_zmodload (kept out of src/ported/ because it is a zshrs extension, not a C port).