format 插件模板(VDE 微内核 SDK 模板包)
纯 C ABI 最小格式插件:实现
VdeFormatPlugin(probe/read/write),演示宿主服务表、 跨 ABI 内存所有权与错误约定。不加入 VDE 默认构建,独立 CMake 工程。
目录
| 文件 | 说明 |
|---|---|
format_plugin.cpp |
插件实现(vde_plugin_query / vde_plugin_init / vde_plugin_shutdown + VdeFormatPlugin) |
vde-plugin.json |
清单:id/version/kind/abi/entry/capabilities(部署时与 DLL 同目录) |
CMakeLists.txt |
独立构建脚本(只依赖 include/vde/plugin/vde_plugin_api.h) |
README.md |
本文件 |
构建
# 在 VDE 源码树根目录(或任意目录,路径换成绝对路径):
cmake -S plugins/templates/format_plugin -B build/template_format \
-G Ninja -DCMAKE_BUILD_TYPE=Release \
-DVDE_SDK_DIR=<VDE 源码根目录或安装前缀>
cmake --build build/template_format
# 产物:build/template_format/plugin/{vde_template_format.dll, vde-plugin.json}
说明:
VDE_SDK_DIR指向 VDE 源码根(<dir>/include/vde/plugin/vde_plugin_api.h)或安装前缀(<dir>/include/...);不传时按本模板在源码树的相对位置自动推断;- 插件只 include
vde/plugin/vde_plugin_api.h,不链接 VDE 内核库; - Windows 产物无
lib前缀(CMake 已设置PREFIX ""),清单entry.windows与之对应。
自检(vde_plugin_tool)
# 构建产物目录同时有 DLL + vde-plugin.json:
<VDE>/build/.../vde_plugin_tool --check build/template_format/plugin
<VDE>/build/.../vde_plugin_tool --list build/template_format/plugin
--check 校验清单必填字段、kind/ABI 与插件 vde_plugin_query 一致性、ABI 与宿主兼容性、
以及声明的 artifacts SHA-256;--list 应与 --inspect 一样识别本插件。
部署与加载
- 把
plugin/目录整体拷到宿主插件搜索路径,例如<VDE 构建>/plugins/或安装前缀的lib/vde/plugins/com.example.vde.format/; - 宿主
PluginManager:
auto& pm = vde::plugin::PluginManager::instance();
pm.set_host_services(vde::plugin::make_geometry_host_services());
pm.add_search_path("<plugin-parent-dir>");
pm.scan_search_paths();
std::string error;
pm.load("com.example.vde.format", &error);
// 通过格式能力导入/导出(.example 文本格式):
// auto r = pm.import_file("part.example", &result);
- 也可以把模板代码拷进自己的插件工程,改
id/entry/format_id/extensions与读写逻辑。
格式与实现要点
- 本模板的
.example文本格式:VDE-EXAMPLE 1+box <sx> <sy> <sz>;读取时调用host->body_create_box创建实体,写入时取实体 bbox 输出同样两行; - 所有输出数组/缓冲区用
host->alloc分配,宿主用free_buffer/free释放; - 失败返回负错误码并
host->set_error,不跨 C ABI 抛异常; probe返回 0–100 置信度,供import_cad分派(扩展名匹配优先);- ABI 版本:
VDE_PLUGIN_ABI_MAJOR.MINOR = 1.3(manifestabi.minor=3);旧宿主按VdePluginHost.struct_size判空,不要调用不存在的服务。
下一步
- 换掉
probe/read_*/write_*为真实格式解析(可参考plugins/official/*); - 在真实文件上验证读→写→再读一致性;
- 用
vde_plugin_tool --check+ 宿主PluginManager加载/卸载回归; - 如需签名与 artifacts:在清单声明
artifacts[{path,sha256}],--check会校验哈希。