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。