docs(client): 整理SDK打包文档

2026-09-08 18:14:58 +08:00
parent 8dfef45bc4
commit 613607475e
5 changed files with 137 additions and 79 deletions
@@ -0,0 +1,117 @@
+# Hub 更新客户端打包成 SDK
+
+本文只说明如何从 `SIMCAE/update-client` 生成给 SIMCAE 开发者使用的 SDK 包。SIMCAE 如何拿这个 SDK 打客户安装器和交付包，见项目根目录的 [客户端部署.md](../../客户端部署.md)。
+
+## 一、SDK 包含什么
+
+SDK 用来把 Hub 更新客户端接入 SIMCAE 安装包。
+
+| 内容 | 作用 |
+| --- | --- |
+| `Launcher.exe` | 客户日常启动入口，检查整包更新并启动主程序 |
+| `Updater.exe` | 拉取 Manifest、下载发布包、校验 SHA-256、准备安装 |
+| `Bootstrap.exe` | 替换运行中文件时接管安装 |
+| Qt 运行库 | 可选，给没有单独 Qt 运行环境的接入方使用 |
+| 文档 | 说明客户端目录结构、配置字段和接入方式 |
+
+SDK 不包含最终客户配置文件，例如 `app_config.json`、`server_config.json`、`server_config.qrc`、`manifest_public_key.pem`。这些文件由服务端在上传客户软件包或 Qt IFW 交付包时生成或注入。
+
+## 二、编译 Release
+
+先进入 SIMCAE 仓库下的 `update-client` 目录。如果当前已经在 SIMCAE 仓库根目录：
+
+```powershell
+cd .\update-client
+```
+
+然后执行：
+
+```powershell
+cmake --preset x64-release
+cmake --build --preset x64-release
+```
+
+编译完成后，Release 产物通常位于 `out/bin/Release`。
+
+检查核心程序：
+
+```powershell
+Test-Path .\out\bin\Release\Launcher.exe
+Test-Path .\out\bin\Release\Updater.exe
+Test-Path .\out\bin\Release\Bootstrap.exe
+```
+
+预期都返回 `True`。
+
+## 三、打包不带 Qt 运行库的 SDK
+
+适用于接入方已经有 Qt 运行环境，或希望自己控制 Qt DLL 的情况。
+
+```powershell
+.\scripts\package-sdk.ps1 `
+  -SourceDir .\out\bin\Release `
+  -OutputDir .\dist\SimCAEHubUpdateClientSDK `
+  -ZipFile .\dist\SimCAEHubUpdateClientSDK.zip `
+  -SdkVersion 0.1.0
+```
+
+输出：
+
+| 输出 | 说明 |
+| --- | --- |
+| `dist\SimCAEHubUpdateClientSDK` | SDK 展开目录 |
+| `dist\SimCAEHubUpdateClientSDK.zip` | 可交给 SIMCAE 开发者的 SDK 压缩包 |
+
+## 四、打包带 Qt 运行库的 SDK
+
+适用于接入方不想单独准备 Qt DLL，或者希望拿到后能直接放进安装包。
+
+```powershell
+.\scripts\package-sdk.ps1 `
+  -SourceDir .\out\bin\Release `
+  -OutputDir .\dist\SimCAEHubUpdateClientSDK-with-qt `
+  -ZipFile .\dist\SimCAEHubUpdateClientSDK-with-qt.zip `
+  -SdkVersion 0.1.0 `
+  -IncludeQtRuntime
+```
+
+输出：
+
+| 输出 | 说明 |
+| --- | --- |
+| `dist\SimCAEHubUpdateClientSDK-with-qt` | 带 Qt 运行库的 SDK 展开目录 |
+| `dist\SimCAEHubUpdateClientSDK-with-qt.zip` | 推荐交给 SIMCAE 开发者的 SDK 压缩包 |
+
+## 五、打包后检查
+
+```powershell
+Test-Path .\dist\SimCAEHubUpdateClientSDK-with-qt\bin\Launcher.exe
+Test-Path .\dist\SimCAEHubUpdateClientSDK-with-qt\bin\Updater.exe
+Test-Path .\dist\SimCAEHubUpdateClientSDK-with-qt\bin\Bootstrap.exe
+Test-Path .\dist\SimCAEHubUpdateClientSDK-with-qt.zip
+```
+
+预期都返回 `True`。
+
+## 六、不要提交的内容
+
+`SIMCAE/update-client/.gitignore` 已忽略这些本地内容：
+
+- `thirdparty/`
+- `out/`
+- `dist/`
+- `*.exe`
+- `*.dll`
+- `*.zip`
+- `config/app_config.json`
+- `config/client_identity.dat`
+- `config/local_state.json`
+- `config/version_policy.dat`
+
+提交前看一下：
+
+```powershell
+git status --short
+```
+
+不要把本地依赖、编译产物、SDK ZIP、客户配置和运行状态提交进仓库。