How To: White-Label a Plugin Interface
This guide explains how to create a plugin interface crate that hides fidius
as an implementation detail. Plugin authors depend only on your interface
crate – they never see or import fidius directly.
Why white-label?
Section titled “Why white-label?”When building a plugin ecosystem (e.g., “Cloacina plugins”), you want plugin authors to write:
[dependencies]cloacina-plugin = "1.0"Not:
[dependencies]cloacina-plugin = "1.0"fidius = "0.1" # implementation detail leakStep 1: Create the interface crate
Section titled “Step 1: Create the interface crate”fidius init-interface cloacina-plugin --trait CloacinaPlugin --extension cloacinaStep 2: Re-export fidius and use crate = "..."
Section titled “Step 2: Re-export fidius and use crate = "..."”Edit cloacina-plugin/src/lib.rs:
// Re-export fidius so plugin crates can access it through uspub use fidius;
// Use crate = "crate" so generated code resolves fidius through// this crate's re-export, not a direct fidius dependency#[fidius::plugin_interface(version = 1, buffer = PluginAllocated, crate = "crate")]pub trait CloacinaPlugin: Send + Sync { fn execute(&self, input: String) -> String; fn version(&self) -> String;}
// Re-export the proc macros so plugin authors can use thempub use fidius::plugin_impl;pub use fidius::PluginError;The crate = "crate" attribute tells the generated companion module to resolve
fidius types through crate::fidius:: instead of fidius:: directly.
Step 3: Plugin authors use your crate only
Section titled “Step 3: Plugin authors use your crate only”A plugin author’s Cargo.toml:
[package]name = "my-cloacina-plugin"version = "0.1.0"edition = "2021"
[lib]crate-type = ["cdylib"]
[dependencies]cloacina-plugin = "1.0"Their src/lib.rs:
use cloacina_plugin::{plugin_impl, CloacinaPlugin, PluginError, __fidius_CloacinaPlugin};
pub struct MyPlugin;
#[plugin_impl(CloacinaPlugin, crate = "cloacina_plugin::fidius")]impl CloacinaPlugin for MyPlugin { fn execute(&self, input: String) -> String { format!("processed: {input}") }
fn version(&self) -> String { "1.0.0".to_string() }}
cloacina_plugin::fidius::fidius_plugin_registry!();Key points:
#[plugin_impl(CloacinaPlugin, crate = "cloacina_plugin::fidius")]tells the shim codegen to resolve fidius types through the interface crate’s re-export.cloacina_plugin::fidius::fidius_plugin_registry!()emits the registry symbol using the re-exportedfidius_plugin_registry!macro (which uses$crate::internally, so it resolves correctly).- The plugin’s
Cargo.tomlhas no directfidiusdependency.
Custom file extension
Section titled “Custom file extension”If you used --extension cloacina when scaffolding, the fidius.toml in
your interface crate propagates the extension to plugins via init-plugin.
When plugins are packed with fidius package pack, the archive uses
.cloacina instead of .fid.
See Also
Section titled “See Also”- Macro Reference –
crateattribute onplugin_interfaceandplugin_impl - Package Manifest Reference –
extensionfield - ABI Specification – argument tuple encoding