Files

VDE 插件 SDK 模板包(P3-12)

四类微内核插件的最小可构建模板:纯 C ABI、只依赖 include/vde/plugin/vde_plugin_api.h、 不链接 VDE 内核、不加入 VDE 默认构建。用于第三方/内部插件快速起步(P3-12 路线图)。

模板矩阵

模板 kind 扩展点结构 能力 ID 示例 输入/输出
format_plugin format VdeFormatPlugin format:example.read/write .example 文本 ⇄ B-Rep 实体
cae_solver cae_solver VdeCaeSolverPlugin cae_solver:example.linear_static VDE 序列化模型 + params JSON → 结果 JSON
cam_strategy cam_strategy VdeCamStrategyPlugin cam_strategy:example.contour VDE 序列化模型 + args JSON → G-code/JSON
gcs_solver gcs_solver VdeGcsSolverPlugin gcs:solve 草图 JSON + params JSON → 位置/DOF JSON

每个模板包含:插件实现(*.cpp)、vde-plugin.json、独立 CMakeLists.txt、README.md (构建/部署/加载/测试步骤)。清单 ABI 为 { "major": 1, "minor": 3 }。

快速开始(以 format_plugin 为例)

# 1) 独立构建(不进入 VDE 默认构建;只用到 SDK 头)
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

# 2) 自检:清单/kind/ABI/query 一致性/artifacts/兼容性
<VDE 构建>/tools/vde_plugin_tool --check build/template_format/plugin
<VDE 构建>/tools/vde_plugin_tool --list  build/template_format/plugin

# 3) 部署到宿主搜索路径(示例)
#    把 build/template_format/plugin/ 拷到 <VDE 构建>/plugins/ 或 <prefix>/lib/vde/plugins/com.example.vde.format/

注意:源码目录里的模板清单引用尚未构建的 DLL,--check 源码目录会报 plugin library not found;请先构建,再对构建产物目录执行 --check/--list。

vde_plugin_tool --check 校验内容

  • 清单文件存在且可解析:必填 id/version/kind/entry/abi,capabilities 建议非空;
  • 平台 entry 解析后的动态库存在;
  • 动态库导出 vde_plugin_query,其 id/version/kind/abi_major/abi_minor 与清单一致;
  • ABI 与宿主兼容:manifest.abi_major == 宿主 major 且 manifest.abi_minor <= 宿主 minor;
  • 清单声明的 artifacts[{path,sha256}] 路径安全、存在且 SHA-256 一致;
  • kind 与能力前缀一致(format:/cae_solver:/cam_strategy:/gcs:;不匹配给 warning)。

退出码与 verify 一致:0 OK,2 用法错误,3 校验失败。

设计约束(模板刻意保持最小)

  • 不链接内核:只 include 纯 C 契约头;所有内核能力经 VdePluginHost 函数指针;
  • 不跨 ABI 传 C++ 类型/异常:输出内存用 host->alloc/host->free_buffer;
  • ABI 版本兼容:清单 abi.minor 记录构建时宿主 ABI;旧宿主按 struct_size 判空;
  • 默认构建零影响:模板目录不 add_subdirectory,需显式独立 CMake 构建;
  • 模板代码是契约演示/骨架(如 GCS 返回空解、CAE/CAM 返回估算),生产实现替换算法即可。

相关文档

  • 插件开发指南:docs/guides/plugin-development.md(含“模板包/自检”章节);
  • 微内核架构路线图:docs/design/architecture-plugin-roadmap.md(P3-12);
  • ABI 契约:include/vde/plugin/vde_plugin_api.h;
  • 官方插件参考实现:plugins/official/*;示例插件:plugins/sample_vbox、plugins/sample_cae、plugins/sample_cam_post、plugins/sample_gcs。