CyberEther 插件开发指南:打包并发布你自己的 .cep 模块包

原创2026-10-26 19:14:181,709 阅读

CyberEther 插件开发指南:打包并发布你自己的 .cep 模块包

CyberEther 是一个高性能、GPU 加速的信号处理与可视化框架,支持把自定义处理逻辑以 .cep 插件包的形式打包发布。本文带你从零开始:复制官方 blueprint 模板、实现 Block 与 Module、用 bundler.py 打包出 .cep 文件,并最终发布给其他用户安装使用。

⚠️ 插件机制目前仍属实验特性,.cep 格式、ABI 与加载器行为可能随版本变化,升级 CyberEther 后可能需要重新编译插件。

CyberEther 插件打包后的信号处理 Flowgraph 界面示意

一、认识 .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

概念上分为两层,理解后开发就很简单:

  1. Block(块):用户在 Flowgraph 画布上看到的节点,定义类型、域、配置字段、输入输出;
  2. 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 里对比你的模块在不同设备上的性能,这对发布说明很有说服力:

CyberEther 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:

  1. 顶部菜单 CyberEther → Preferences...(快捷键 CTRL+,);
  2. 左侧 Registry 分区,找到 Plugins 区域,点击 Add Plugin;
  3. 选择你的 .cep 文件,勾选信任声明后点击 Register Plugin。

加载成功后会弹出 "Plugin loaded." 通知,插件出现在列表中(状态 Loaded),你的 Block 会像内置块一样出现在 block catalog 中。也可以临时加载:

cyberether --plugin path/to/plugin.cep

各状态含义与故障排查详见 docs/installing-plugins.md。

CyberEther 插件加载后的可视化全景界面

八、发布前的检查清单 ✅

发布 .cep 到仓库 Releases 或官网前,建议核对:

  • [ ] manifest.yml 中 name / version 准确,最低版本号与宿主兼容;
  • [ ] 所有目标平台(system / arch / device 组合)均已构建并合并,无重复标签;
  • [ ] 尽量把第三方依赖静态链接进插件库——插件会被拷到你不控制的机器上运行,只依赖 C/C++ 标准库最安全;无法静态链接时,必须在插件文档中写清每个依赖的包名与版本范围;
  • [ ] 附带至少一个可运行的示例 Flowgraph;
  • [ ] 提供校验和(checksum)供用户验证下载完整性;
  • [ ] 在 README 中说明支持的操作系统与设备后端。

🔒 安全提醒:插件以 CyberEther 同等权限运行原生代码,没有沙箱。作为发布者保持源码公开,作为安装者只加载你信任来源的插件。

完成以上步骤,你就拥有了一个可跨平台分发的 CyberEther 插件包。想要深入了解插件 API、依赖规则或加载流程,请继续阅读官方文档 docs/plugins.md 与 docs/metadata.md。

登录后查看全文
CyberEther