Files

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 一样识别本插件。

部署与加载

  1. 把 plugin/ 目录整体拷到宿主插件搜索路径,例如 <VDE 构建>/plugins/ 或安装前缀的 lib/vde/plugins/com.example.vde.format/;
  2. 宿主 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);
  1. 也可以把模板代码拷进自己的插件工程,改 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(manifest abi.minor=3);旧宿主按 VdePluginHost.struct_size 判空,不要调用不存在的服务。

下一步

  • 换掉 probe/read_*/write_* 为真实格式解析(可参考 plugins/official/*);
  • 在真实文件上验证读→写→再读一致性;
  • 用 vde_plugin_tool --check + 宿主 PluginManager 加载/卸载回归;
  • 如需签名与 artifacts:在清单声明 artifacts[{path,sha256}],--check 会校验哈希。