Skip to content

PLUGIN_GUIDE.md

Latest commit

 

History

History
109 lines (77 loc) · 2.87 KB

PLUGIN_GUIDE.md

File metadata and controls

109 lines (77 loc) · 2.87 KB
Raw

Mumei Emitter Plugin Guide

Mumei can load external code-generation emitters at runtime from dynamic libraries. A plugin implements mumei_core::emitter::Emitter, exports the expected ABI symbols, and is installed under ~/.mumei/emitters/<name>/.

Cargo template

[package]
name = "mumei-emit-noop"
version = "0.1.0"
edition = "2021"

[lib]
crate-type = ["cdylib"]

[dependencies]
mumei-core = { git = "https://github.com/mumei-lang/mumei", package = "mumei-core" }

When developing against a local checkout, replace the dependency with:

mumei-core = { path = "../mumei/mumei-core" }

Required exports

Every plugin must export:

  • mumei_emitter_abi_version() -> u32
  • mumei_create_emitter() -> EmitterPluginHandle

The ABI version must match mumei_core::emitter::EMITTER_ABI_VERSION.

No-op sample plugin

use mumei_core::emitter::{Artifact, BoxedEmitter, Emitter, EmitterPluginHandle, EMITTER_ABI_VERSION};
use mumei_core::hir::HirAtom;
use mumei_core::parser::ExternBlock;
use mumei_core::verification::{ModuleEnv, MumeiResult};
use std::path::Path;

struct NoopEmitter;

impl Emitter for NoopEmitter {
    fn emit(
        &self,
        _hir_atom: &HirAtom,
        _output_path: &Path,
        _module_env: &ModuleEnv,
        _extern_blocks: &[ExternBlock],
    ) -> MumeiResult<Vec<Artifact>> {
        Ok(Vec::new())
    }
}

#[no_mangle]
pub extern "C" fn mumei_emitter_abi_version() -> u32 {
    EMITTER_ABI_VERSION
}

#[no_mangle]
pub extern "C" fn mumei_create_emitter() -> EmitterPluginHandle {
    let emitter: BoxedEmitter = Box::new(NoopEmitter);
    EmitterPluginHandle::from_boxed(emitter)
}

EmitterPluginHandle is a #[repr(C)] two-pointer handle carrying the trait object's data and vtable pointers explicitly. Do not export *mut dyn Emitter directly across the C ABI boundary.

Build and install

Build the plugin:

cargo build --release

Install it into the emitter directory matching the --emit name:

mkdir -p ~/.mumei/emitters/noop

# Linux
cp target/release/libmumei_emit_noop.so ~/.mumei/emitters/noop/

# macOS
cp target/release/libmumei_emit_noop.dylib ~/.mumei/emitters/noop/

# Windows
copy target\release\mumei_emit_noop.dll %USERPROFILE%\.mumei\emitters\noop\

Run Mumei with the plugin:

mumei build src/main.mm --emit noop

For --emit <name>, Mumei searches:

  • Linux: ~/.mumei/emitters/<name>/libmumei_emit_<name>.so
  • macOS: ~/.mumei/emitters/<name>/libmumei_emit_<name>.dylib
  • Windows: ~/.mumei/emitters/<name>/mumei_emit_<name>.dll

Runtime safety

The host loads an external emitter once per mumei build invocation and reuses that object for every atom emitted in the build. It keeps the dynamic library loaded while the emitter object is alive. emit() calls are wrapped in a panic catcher, so plugin panics become MumeiError diagnostics instead of unwinding through Mumei.