跳到主要内容

插件包制作

须按本文格式制作插件包与配置文件，方可正确导入 Rokae+ 应用。

插件包结构​

HMI 导入的对象为 插件包（zip），其中包含 数据包：

  • client.zip：客户端插件
  • controller.zip：控制器插件

插件包 可同时包含上述两者，亦可仅含其一。客户端与控制器插件无强制依赖关系。

若需交付多个插件，可采用下列任一方式：

  1. 分包装：每一插件各自形成独立的 插件包（及其中的数据包），分别导入。
  2. 合包装：在同一 client.zip 或 controller.zip 内并列多个插件目录，一次导入。

下文分两种情形说明目录布局。

1. 单个插件​

单架构、客户端与控制器合包示例如下：

Package.zip                # 插件包
├── client.zip             # 客户端数据包
│   └── MyPlugin/
│       ├── MyPlugin.dll   # Windows 后缀为 .dll，Linux 后缀为 .so
│       ├── xplugin.dll    # 框架库；Windows 后缀为 .dll，Linux 后缀为 .so
│       └── MyPlugin.json  # 配置文件
└── controller.zip         # 控制器数据包
    └── MyPlugin/
        ├── MyPlugin.lic   # 授权文件
        ├── MyPlugin.so    # 控制器动态库（.so）
        └── MyPlugin.json  # 配置文件

2. 同一数据包内的多个插件（合包装）​

在同一 client.zip 或 controller.zip 内并列多个插件目录；每一目录对应一个插件，目录内布局与单插件相同。一次导入可安装包内全部插件。

客户端与控制器均包含 MyPlugin 与 OtherPlugin 的示例如下：

Package.zip
├── client.zip
│   ├── MyPlugin/
│   │   ├── MyPlugin.dll      # Windows 后缀为 .dll，Linux 后缀为 .so
│   │   ├── xplugin.dll       # 框架库；Windows 后缀为 .dll，Linux 后缀为 .so
│   │   └── MyPlugin.json     # 配置文件
│   └── OtherPlugin/
│       ├── OtherPlugin.dll   # Windows 后缀为 .dll，Linux 后缀为 .so
│       ├── xplugin.dll       # 框架库；Windows 后缀为 .dll，Linux 后缀为 .so
│       └── OtherPlugin.json  # 配置文件
└── controller.zip
    ├── MyPlugin/
    │   ├── MyPlugin.lic      # 授权文件
    │   ├── MyPlugin.so       # 控制器动态库（.so）
    │   └── MyPlugin.json     # 配置文件
    └── OtherPlugin/
        ├── OtherPlugin.lic   # 授权文件
        ├── OtherPlugin.so    # 控制器动态库（.so）
        └── OtherPlugin.json  # 配置文件

若 MyPlugin 依赖 OtherPlugin，须在 MyPlugin.json 的 depend（客户端依赖）或 ctrlDepend（控制器依赖）中声明，例如 "depend": ["OtherPlugin"]。

配置文件​

在插件目录中放置 MyPlugin.json。客户端配置示例如下，字段说明见下表：

{
    "client_plugin": {
        "name": "MyPlugin",
        "depend": [],
        "ctrlDepend": [],
        "enable": false,
        "version": "3.0.1",
        "min_hmi_version": "3.0.1",
        "custom_hmi_version": [],
        "author": "rokae",
        "description": "description"
    }
}

选填字段（表中标 ✗）可不写入 JSON。

字段必填说明
name✓插件名；命名约束见下文 插件名一致性
depend✗所依赖的其它客户端插件名列表；无依赖时为空数组
ctrlDepend✗所依赖的控制器插件名列表
enable✓导入后是否默认启用；本例为 false
version✓插件版本号
min_hmi_version✗所支持的最低 HMI（xCore）版本
custom_hmi_version✗自定义适配版本列表
author✗作者
description✗描述

控制器侧配置文件同为目录内的 MyPlugin.json，字段定义以控制器插件规范为准；文件名与目录名约束见下文 插件名一致性。

插件名一致性​

下列各项中的插件名须为同一字符串。下文以 MyPlugin 为例；合包装中的 OtherPlugin 同理，各项均取为 OtherPlugin。

  1. 工程注册
    Qt 工程中的 PLUGIN_NAME，以及 XPLUGIN_REGISTER 的 KEY，须为 MyPlugin。

  2. 数据包目录与文件
    插件包 内该插件相关路径与文件主文件名须为 MyPlugin：

Package.zip
├── client.zip
│   └── MyPlugin/              # 部署目录名 = MyPlugin
│       ├── MyPlugin.dll       # 用户插件动态库主文件名 = MyPlugin（Linux 为 MyPlugin.so）
│       ├── xplugin.dll
│       └── MyPlugin.json      # 配置文件名 = MyPlugin
└── controller.zip
    └── MyPlugin/              # 部署目录名 = MyPlugin
        ├── MyPlugin.lic       # 授权文件主文件名 = MyPlugin
        ├── MyPlugin.so        # 控制器动态库主文件名 = MyPlugin
        └── MyPlugin.json      # 配置文件名 = MyPlugin

  1. 配置文件中的 name
    MyPlugin.json 内 name 字段须为 "MyPlugin"。

  2. 依赖声明（如有）
    若在 depend / ctrlDepend 中引用其它插件，所填名称须与被依赖插件的上述各项一致（例如引用 OtherPlugin 时填写 "OtherPlugin"）。

使用脚本快速生成​

文档配套脚本可将已整理的 client / controller 目录打包为可导入的 插件包。

获取脚本​

将下列文件与 client、controller 目录置于同一工作目录：

文件作用
PluginPackage.batWindows 打包脚本
PluginPackage.shLinux 打包脚本

准备目录​

目录结构如下（可仅含客户端或仅含控制器）。client / controller 下可并列多个插件目录：

工作目录/
├── client/                   # 可选
│   ├── MyPlugin/
│   │   ├── MyPlugin.dll      # Windows 后缀为 .dll，Linux 后缀为 .so
│   │   ├── xplugin.dll       # 框架库；Windows 后缀为 .dll，Linux 后缀为 .so
│   │   └── MyPlugin.json     # 配置文件
│   └── OtherPlugin/          # 可选
│       ├── OtherPlugin.dll   # Windows 后缀为 .dll，Linux 后缀为 .so
│       ├── xplugin.dll       # 框架库；Windows 后缀为 .dll，Linux 后缀为 .so
│       └── OtherPlugin.json  # 配置文件
├── controller/               # 可选
│   └── MyPlugin/
│       ├── MyPlugin.lic      # 授权文件
│       ├── MyPlugin.so       # 控制器动态库（.so）
│       └── MyPlugin.json     # 配置文件
└── PluginPackage.bat         # 或 PluginPackage.sh

生成步骤（Windows）​

  1. 确认工作目录中存在 PluginPackage.bat，以及 client 和/或 controller。
  2. 双击 PluginPackage.bat。
  3. 待控制台提示完成后，同目录将生成 插件包 zip（默认文件名为当前文件夹名，可按需重命名）。
  4. 将该 zip 导入插件管理。

产出说明​

Package.zip
├── client.zip      # 由 client/ 压缩得到
└── controller.zip  # 由 controller/ 压缩得到
  • 仅存在 client 时，插件包 仅含 client.zip。
  • 仅存在 controller 时，插件包 仅含 controller.zip。

常见问题​

现象处理
提示找不到 client / controller确认脚本与上述目录位于同一路径
多架构未按预期架构目录名须为 aarch64 / amd64 / win（控制器无 win）

多架构插件包​

Rokae+ 支持在同一 插件包 内按系统架构分别存放数据包。在 client.zip / controller.zip 内先按架构建立子目录，再放入与单架构相同的插件目录。

  • 客户端（client.zip）：aarch64、amd64、win
  • 控制器（controller.zip）：aarch64、amd64
Package.zip
├── client.zip
│   ├── aarch64
│   │   └── MyPlugin/
│   │       ├── MyPlugin.so
│   │       ├── xplugin.so
│   │       └── MyPlugin.json
│   ├── amd64
│   │   └── MyPlugin/
│   │       ├── MyPlugin.so
│   │       ├── xplugin.so
│   │       └── MyPlugin.json
│   └── win
│       └── MyPlugin/
│           ├── MyPlugin.dll
│           ├── xplugin.dll
│           └── MyPlugin.json
└── controller.zip
    ├── aarch64
    │   └── MyPlugin/
    │       ├── MyPlugin.lic
    │       ├── MyPlugin.so
    │       └── MyPlugin.json
    └── amd64
        └── MyPlugin/
            ├── MyPlugin.lic
            ├── MyPlugin.so
            └── MyPlugin.json
提示

多架构插件包自插件 1.0.2.6 起支持，配套 xCore 控制系统 v3.2.2 及以上。

下一步​

请按 安装与使用 将 插件包 导入 HMI 并启用。

本页导航