CyberEther 插件开发指南:打包并发布你自己的 .cep 模块包
CyberEther 插件开发指南:打包并发布你自己的 .cep 模块包
CyberEther 是一个高性能、GPU 加速的信号处理与可视化框架,支持把自定义处理逻辑以 .cep 插件包的形式打包发布。本文带你从零开始:复制官方 blueprint 模板、实现 Block 与 Module、用 bundler.py 打包出 .cep 文件,并最终发布给其他用户安装使用。
⚠️ 插件机制目前仍属实验特性,
.cep格式、ABI 与加载器行为可能随版本变化,升级 CyberEther 后可能需要重新编译插件。
一、认识 .cep 插件包
.cep 文件本质上是一个 tar.gz 压缩包,内含三部分内容:
| 组成 | 说明 |
|---|---|
| 共享库 | 针对特定 system / arch / device 编译的插件动态库 |
manifest.yml |
根目录清单,声明名称、版本、最低 CyberEther 版本及各目标库路径 |
| 示例 Flowgraph(可选) | 随包附带的 YAML 流程图,安装后可直接打开体验 |
一个典型的 manifest.yml 长这样:
metadata:
name: cyberether-blueprint-plugin
version: 0.1.0
minimumJetstreamVersion: 1.17.0
targets:
- path: targets/macos-arm64-cpu/cyberether_blueprint_plugin.dylib
system: macos
device: cpu
arch: arm64
examples:
- path: examples/blueprint_gain.yml
注意:版本号必须严格为 x.y.z 三段式(每段 0–255),不支持预发布后缀。
二、从 Blueprint 模板起步
仓库内置了完整的插件骨架 examples/plugins/blueprint/,新建插件时直接复制该目录,然后重命名项目名、blueprint 目录、块名与模块名即可。目录布局如下:
.
|-- include/
| `-- blueprint/
| `-- gain/
| |-- block.hh # Block 配置声明
| `-- module.hh # Module 配置声明
|-- examples/
| `-- blueprint_gain.yml # 随包示例流程图
|-- src/
| |-- plugin.cc # 导出插件 ABI 符号
| `-- blueprint/
| `-- gain/
| |-- block_impl.cc
| |-- module_impl.cc
| `-- module_impl_native_cpu.cc # CPU 原生实现
|-- tools/
| |-- bundler.py # 打包 .cep
| `-- merger.py # 合并多目标包
`-- meson.build
- include/ 下的公开头文件定义 Block 的配置字段、输入输出;
- src/ 实现具体处理逻辑并注册执行提供者;
- 更多细节参见官方文档 docs/plugins.md。
以模板中的增益块为例,src/plugin.cc 只需两行即可导出 ABI 符号:
#include <jetstream/plugin.hh>
JST_REGISTER_PLUGIN();
而 include/blueprint/gain/block.hh 中通过 JST_BLOCK_TYPE、JST_BLOCK_PARAMS、JST_BLOCK_DESCRIPTION 等宏声明了块类型、参数与说明文档——你在自己的插件中只需照葫芦画瓢替换这些内容。
三、实现 Block 与 Module
概念上分为两层,理解后开发就很简单:
- Block(块):用户在 Flowgraph 画布上看到的节点,定义类型、域、配置字段、输入输出;
- Module(模块):真正执行运行时计算的单元,按设备(CPU/CUDA/Metal/Vulkan/WebGPU)注册具体实现。
注册是静态完成的,CyberEther 加载目标库时会自动收集这些注册项。模板中的关键注册点:
JST_REGISTER_BLOCK(BlueprintGainImpl, {"blueprint_gain"});
JST_REGISTER_MODULE(BlueprintGainImplNativeCpu,
DeviceType::CPU,
RuntimeType::NATIVE,
"generic");
💡 重要规则:同一个共享库不要在清单里挂多个
device标签——CyberEther 会加载每一个匹配目标,重复注册会导致加载失败。每种设备应单独构建一个变体。
四、用 Meson 构建插件
确保系统已安装 CyberEther(或让 Meson 通过 subprojects/cyberether.wrap 自动拉取依赖),然后在插件目录执行:
cd examples/plugins/blueprint
meson setup build -Ddevices=cpu
meson compile -C build
构建完成后,build/ 目录下会生成两个产物:
- 共享库(中间产物)
cyberether_blueprint_plugin.cep(面向用户的最终插件包)
构建入口逻辑见 meson.build,它通过 dependency('jetstream') 找到宿主框架并校验最低版本 1.17.0。测试文件位于 tests/ 目录,可加 -Dtests=false 关闭。
浏览器(WebAssembly)插件
如果要发布 Web 版插件,使用 Emscripten 交叉编译,保证线程、SIMD、LTO 等设置与 CyberEther 浏览器端一致:
meson setup build-wasm examples/plugins/blueprint \
--cross-file meson/crosscompile/emscripten.ini \
-Dbuildtype=release \
-Ddevices=cpu \
-Dtests=false
meson compile -C build-wasm cyberether_blueprint_plugin_cep
可选:为模块添加基准测试
模板附带了 module_benchmarks.cc,用 JST_BENCHMARKS 注册 F32 / CF32 多尺寸用例。插件加载后,可以在 Benchmarking Tool 里对比你的模块在不同设备上的性能,这对发布说明很有说服力:
五、用 bundler.py 打包 .cep
手动调用 tools/bundler.py 可以精细控制包内容(正常构建时它会自动被调用):
./tools/bundler.py \
--output build/cyberether_blueprint_plugin.cep \
--name cyberether-blueprint-plugin \
--version 0.1.0 \
--minimum-jetstream-version 1.17.0 \
--target path=build/cyberether_blueprint_plugin.dylib,system=macos,device=cpu,arch=arm64 \
--example examples/blueprint_gain.yml
- 用
--target重复声明多个目标库(每个system + device + arch组合只允许出现一次); - 用
--example附带示例流程图,例如模板自带的 blueprint_gain.yml。
六、用 merger.py 合并多平台包
发布时通常需要覆盖 macOS / Linux / Windows 等多个平台,但每台机器只能构建自己的目标。推荐做法:每个平台各自构建单目标 .cep,再用 tools/merger.py 合并:
./tools/merger.py \
--output build/cyberether_blueprint_plugin.cep \
build/macos-arm64.cep \
build/linux-x86_64.cep
合并前 merger 会自动校验:
- 所有输入包的
name、version、minimumJetstreamVersion必须完全一致; - 每个
system + device + arch组合只能来自一个输入包; - 相同路径的示例文件内容必须相同(会自动去重)。
输出是原子写入的,中断也不会留下残缺的 .cep。
七、安装验证你的插件
打包完成后先自测。启动 CyberEther:
- 顶部菜单 CyberEther → Preferences...(快捷键
CTRL+,); - 左侧 Registry 分区,找到 Plugins 区域,点击 Add Plugin;
- 选择你的
.cep文件,勾选信任声明后点击 Register Plugin。
加载成功后会弹出 "Plugin loaded." 通知,插件出现在列表中(状态 Loaded),你的 Block 会像内置块一样出现在 block catalog 中。也可以临时加载:
cyberether --plugin path/to/plugin.cep
各状态含义与故障排查详见 docs/installing-plugins.md。
八、发布前的检查清单 ✅
发布 .cep 到仓库 Releases 或官网前,建议核对:
- [ ]
manifest.yml中name/version准确,最低版本号与宿主兼容; - [ ] 所有目标平台(system / arch / device 组合)均已构建并合并,无重复标签;
- [ ] 尽量把第三方依赖静态链接进插件库——插件会被拷到你不控制的机器上运行,只依赖 C/C++ 标准库最安全;无法静态链接时,必须在插件文档中写清每个依赖的包名与版本范围;
- [ ] 附带至少一个可运行的示例 Flowgraph;
- [ ] 提供校验和(checksum)供用户验证下载完整性;
- [ ] 在 README 中说明支持的操作系统与设备后端。
🔒 安全提醒:插件以 CyberEther 同等权限运行原生代码,没有沙箱。作为发布者保持源码公开,作为安装者只加载你信任来源的插件。
完成以上步骤,你就拥有了一个可跨平台分发的 CyberEther 插件包。想要深入了解插件 API、依赖规则或加载流程,请继续阅读官方文档 docs/plugins.md 与 docs/metadata.md。


