From c1d14681bfe4f12e51173640abbec2d5c4aa2301 Mon Sep 17 00:00:00 2001 From: jianf <2198972886@qq.com> Date: Sun, 19 Jul 2026 12:32:56 +0800 Subject: [PATCH] docs: sync PLUGIN_DEV.md with SDK toolchain updates - Fix project structure: remove main.go, add auto-generated bridge files note - Clarify plg.json (targets) vs plugin.json (entry/platforms) distinction - Add --bundle multi-platform build section - Add plugindev sdk version management subcommands - Update entry point section: NewPlugin is in plugin.go, no separate main.go - Sync zh and en versions --- docs/en/PLUGIN_DEV.md | 81 +++++++++++++++++++++++++++++-------------- docs/zh/PLUGIN_DEV.md | 78 +++++++++++++++++++++++++++-------------- 2 files changed, 107 insertions(+), 52 deletions(-) diff --git a/docs/en/PLUGIN_DEV.md b/docs/en/PLUGIN_DEV.md index 164aed1..2ab9241 100644 --- a/docs/en/PLUGIN_DEV.md +++ b/docs/en/PLUGIN_DEV.md @@ -49,6 +49,21 @@ go build -o plugindev # Add plugindev to PATH or use directly ``` +### SDK Version Management + +`plugindev sdk` manages local SDK versions: + +```bash +plugindev sdk list # list installed SDK versions +plugindev sdk current # show current SDK version +plugindev sdk latest # show latest available version +plugindev sdk install v0.7.1 # install a specific version +plugindev sdk use v0.7.1 # switch to a version +plugindev sdk path # show current SDK path +``` + +SDK is stored at `~/.homeagent/plugindev/sdk//`; `plugindev init` reads the current SDK version for `go.mod`. + ### Creating a Go Plugin ```bash @@ -81,13 +96,15 @@ plugindev build ``` myplugin/ -├── plg.json — Plugin metadata (name, version, entry, target platform) -├── main.go — Entry point (compiled for non-Windows or non-cgo) -├── plugin.go — Plugin implementation (Plugin interface) +├── plg.json — Plugin metadata (name, version, entry, target platforms) +├── plugin.go — Plugin implementation (Plugin interface + NewPlugin export) ├── go.mod — Go module definition -└── README.md — Documentation +├── README.md — Documentation +└── thirdpart/ — Optional external source code directory ``` +C ABI bridge files (`z_bridge_gen.go` + `z_entry.c`) are auto-generated at build time. + **Lua plugin**: ``` @@ -108,29 +125,45 @@ plugindev build ``` Execution process: -1. Reads `plg.json` to determine target platform -2. **Go plugin**: Runs `go build -buildmode=c-shared` (produces `.so` + C ABI header) -3. **Lua plugin**: Packages source code directly, no compilation needed -4. Generates `plugin.json` manifest file -5. Packages as `.hmap` distribution (zip format, containing `plugin.json` + platform binary) +1. Reads `plg.json` `targets` field to determine target platforms +2. Auto-generates C ABI bridge code (`z_bridge_gen.go` + `z_entry.c`) +3. **Go plugin**: Runs `go build -buildmode=c-shared` (produces `.so` / `.dylib` / `.dll`) +4. **Lua plugin**: Packages source code directly, no compilation needed +5. Generates `plugin.json` output manifest +6. Packages as `.hmap` distribution (zip format, containing `plugin.json` + binary) -The `platforms` field in `plugin.json` declares supported platforms; the build includes the corresponding binary: +### plg.json (project config) vs plugin.json (output manifest) -| Platform | Binary name | -|----------|-------------| +| File | Purpose | Key fields | +|------|---------|------------| +| `plg.json` | Project metadata, maintained by developer | `targets` — build targets (e.g. `"linux/amd64,windows/amd64"`) | +| `plugin.json` | Build artifact manifest, auto-generated | `entry` — entry filename; `platforms` — declared platforms | + +Each target produces a separate `.hmap`; binary name by platform: + +| Platform | Binary | +|----------|--------| | Linux | `plugin.so` | | macOS | `plugin.dylib` | | Windows | `plugin.dll` | -> Use `--bundle` to build a multi-platform bundle — the resulting `.hmap` contains binaries for all platforms. -> During installation, the kernel automatically selects the correct binary for the current OS, skipping others. +### Multi-platform bundle: --bundle + +```bash +plugindev build --bundle +``` + +Builds linux/amd64 + darwin/amd64 + windows/amd64 in one pass, producing a single `.hmap` +with all platform binaries. The output manifest includes a `platforms` field. +The kernel auto-selects the correct binary during installation. Output in `dist/` directory: ``` dist/ -├── myplugin_linux_amd64.hmap # Go plugin Linux version -├── myplugin_windows_amd64.hmap # Go plugin Windows version -├── myplugin_darwin_amd64.hmap # Go plugin macOS version +├── myplugin_linux_amd64.hmap # Single platform: Linux +├── myplugin_windows_amd64.hmap # Single platform: Windows +├── myplugin_darwin_amd64.hmap # Single platform: macOS +├── myplugin_bundle.hmap # Multi-platform bundle └── myplugin_lua.hmap # Lua plugin ``` @@ -197,21 +230,17 @@ func NewPluginFactory(name string, config map[string]interface{}) (sdk.Plugin, e ### Entry Point -`main.go` provides the `NewPlugin` export function, which is the entry point when the kernel loads the plugin: +`plugindev init` generates `plugin.go` with the `NewPlugin` export function directly, +which is the entry point when the kernel loads the plugin: ```go -//go:build !windows || !cgo - -package main - -import "gitcode.com/JianFeeeee/homeagent-sdk/sdk" - func NewPlugin(name string, config map[string]interface{}) (sdk.Plugin, error) { - return NewPluginFactory(name, config) + return &Plugin{name: name}, nil } ``` -For `-buildmode=c-shared`, `plugindev build` auto-generates C ABI bridge code (`z_bridge_gen.go` + `z_entry.c`), no manual handling needed. +At build time, `plugindev build` auto-generates C ABI bridge code (`z_bridge_gen.go` + `z_entry.c`), +shared by both Windows DLL and Linux/macOS .so builds. No manual bridge code needed. ### PluginSDK Core API diff --git a/docs/zh/PLUGIN_DEV.md b/docs/zh/PLUGIN_DEV.md index 9e7853c..b51eedc 100644 --- a/docs/zh/PLUGIN_DEV.md +++ b/docs/zh/PLUGIN_DEV.md @@ -50,6 +50,21 @@ go build -o plugindev # 将 plugindev 加入 PATH 或直接使用 ``` +### SDK 版本管理 + +`plugindev sdk` 子命令管理本地 SDK 版本： + +```bash +plugindev sdk list # 列出已安装的 SDK 版本 +plugindev sdk current # 显示当前使用的 SDK 版本 +plugindev sdk latest # 显示最新可用版本 +plugindev sdk install v0.7.1 # 安装指定版本 +plugindev sdk use v0.7.1 # 切换使用版本 +plugindev sdk path # 显示当前 SDK 路径 +``` + +SDK 存储在 `~/.homeagent/plugindev/sdk//`，`plugindev init` 自动读取当前 SDK 版本填充 `go.mod`。 + ### 创建 Go 插件 ```bash @@ -82,13 +97,15 @@ plugindev build ``` myplugin/ -├── plg.json — 插件元信息（名称、版本、入口、目标平台） -├── main.go — 入口点（非 Windows 或非 cgo 时编译） -├── plugin.go — 插件实现（Plugin 接口） +├── plg.json — 插件元信息（名称、版本、入口、目标平台 targets） +├── plugin.go — 插件实现（Plugin 接口 + 导出函数 NewPlugin） ├── go.mod — Go 模块定义 -└── README.md — 说明文档 +├── README.md — 说明文档 +└── thirdpart/ — 外部源码存放目录（可选） ``` +编译时自动生成 C ABI bridge 文件（`z_bridge_gen.go` + `z_entry.c`），无需手动创建。 + **Lua 插件**： ``` @@ -109,29 +126,44 @@ plugindev build ``` 执行过程： -1. 读取 `plg.json` 确定目标平台 -2. **Go 插件**：执行 `go build -buildmode=c-shared`（生成 `.so` + C ABI header） -3. **Lua 插件**：直接打包源码，无需编译 -4. 生成 `plugin.json` 清单文件 -5. 打包为 `.hmap` 分发包（zip 格式，内含 `plugin.json` + 平台二进制） +1. 读取 `plg.json` 的 `targets` 字段确定目标平台 +2. 自动生成 C ABI bridge 代码（`z_bridge_gen.go` + `z_entry.c`） +3. **Go 插件**：执行 `go build -buildmode=c-shared`（生成 `.so` / `.dylib` / `.dll`） +4. **Lua 插件**：直接打包源码，无需编译 +5. 生成 `plugin.json` 输出清单 +6. 打包为 `.hmap` 分发包（zip 格式，内含 `plugin.json` + 二进制） -`plugin.json` 的 `platforms` 字段声明支持的平台，打包时自动包含对应二进制： +### plg.json（项目配置）vs plugin.json（输出清单） -| 平台 | 二进制文件名 | -|------|-------------| +| 文件 | 用途 | 关键字段 | +|------|------|---------| +| `plg.json` | 项目元信息，由开发者维护 | `targets` — 构建目标（如 `"linux/amd64,windows/amd64"`）| +| `plugin.json` | 构建产物清单，`plugindev build` 自动生成 | `entry` — 入口文件名；`platforms` — 声明的支持平台 | + +每个目标生成单独的 `.hmap`，二进制文件名由平台决定： + +| 平台 | 二进制 | +|------|--------| | Linux | `plugin.so` | | macOS | `plugin.dylib` | | Windows | `plugin.dll` | -> 使用 `--bundle` 可一次打包多平台，生成的 `.hmap` 内含所有平台的二进制。 -> 安装时核心自动选择当前平台的文件，跳过其他平台。 +### 多平台打包：--bundle + +```bash +plugindev build --bundle +``` + +一次编译 linux/amd64 + darwin/amd64 + windows/amd64，生成包含所有平台二进制的单 `.hmap`， +输出清单自动添加 `platforms` 字段。安装时核心自动选择当前平台的二进制，跳过其他平台。 输出在 `dist/` 目录： ``` dist/ -├── myplugin_linux_amd64.hmap # Go 插件 Linux 版 -├── myplugin_windows_amd64.hmap # Go 插件 Windows 版 -├── myplugin_darwin_amd64.hmap # Go 插件 macOS 版 +├── myplugin_linux_amd64.hmap # 单平台：Linux 版 +├── myplugin_windows_amd64.hmap # 单平台：Windows 版 +├── myplugin_darwin_amd64.hmap # 单平台：macOS 版 +├── myplugin_bundle.hmap # 多平台合集 └── myplugin_lua.hmap # Lua 插件 ``` @@ -198,21 +230,15 @@ func NewPluginFactory(name string, config map[string]interface{}) (sdk.Plugin, e ### 入口点 -`main.go` 提供了 `NewPlugin` 导出函数，它是内核加载插件时的入口： +`plugindev init` 生成的 `plugin.go` 中直接包含 `NewPlugin` 导出函数，它是内核加载插件时的入口： ```go -//go:build !windows || !cgo - -package main - -import "gitcode.com/JianFeeeee/homeagent-sdk/sdk" - func NewPlugin(name string, config map[string]interface{}) (sdk.Plugin, error) { - return NewPluginFactory(name, config) + return &Plugin{name: name}, nil } ``` -对于 `-buildmode=c-shared`，`plugindev build` 自动生成 C ABI bridge 代码（`z_bridge_gen.go` + `z_entry.c`），无需手动处理。 +编译时 `plugindev build` 根据目标平台自动生成 C ABI bridge 代码（`z_bridge_gen.go` + `z_entry.c`），无需手动编写。Windows DLL 和 Linux/macOS .so 共享同一入口。 ### PluginSDK 核心 API