update-client/docs/build-and-packaging.md

构建和打包

所有权

父级 SimCAE 仓库拥有发布配置、运行时部署、安装程序元数据以及最终的用户包。此子项目提供运行时目标和可安装的公共资源。

支持的包目标是 package_installer。它使用父级 CMake 安装规则和 Qt Installer Framework。 package_installer_qt 是一个归档的实验性路径，不得使用，也不应作为后备方案进行修复或作为支持的交付选项进行文档说明。

移除的 install-sdk.ps1、package-client.ps1 和 package-sdk.ps1 工作流不被支持。它们在父级外部组装了部分树 ，这可能导致与产品运行时闭包不一致。

前提条件

发布构建需要：

• 与父项目兼容的 CMake 和编译器版本；
• 更新客户端目标所请求的 Qt 模块；
• 通过 CMake 导入目标发现的 OpenSSL
• Qt Installer Framework for package_installer；和
• 父仓库中批准的 3rdparty 包或由调用者明确提供的 CMake 包提示。

仓库的 CMake 文件不得包含指向工作站的绝对路径，强制 调用者的生成器或架构，或手动选择 Debug 和 Release 库目录。依赖项发现必须生成导入的目标，例如 Qt5::Core、OpenSSL::SSL 和 OpenSSL::Crypto。

缺少已批准的包必须停止配置并显示可操作的错误。发布包不得静默回退到不相关的系统包。

父级发布构建

从 SimCAE 仓库根目录运行集成工作流：

git submodule update --init --recursive
cmake --preset SimCAE-release
cmake --build --preset SimCAE-release --target SimCAE

专用的发布预设将发布依赖项和输出分开 来自调试信息和旧的混合构建树。集成构建生成 Launcher、Updater 和 Bootstrap 位于 SimCAE 相同的运行目录中，并将发布启动门构建到 SimCAE 中。

调试开发使用 Debug 预设：

cmake --preset SimCAE-debug
cmake --build --preset SimCAE-debug --target SimCAE

调试模式可能允许开发者直接启动 SimCAE 进行迭代开发。请勿从调试或混合构建树中验证或打包发布版本。

测试

在打包之前运行父级发布测试：

ctest --test-dir out/build/SimCAE-release -C Release --output-on-failure

聚焦的更新客户端测试可能运行得更早，但它们不会替代父级测试套件、安装树检查或真实机器验收。

安装程序

从同一配置的 Release 树构建唯一支持的用户交付版本:

cmake --build --preset SimCAE-release --target package_installer

该目标通过 cmake --install 阶段文件，根据父包定义分离可选的产品组件，并调用 Qt Installer Framework。生成的安装程序以配置的产品版本和平台名称写入 Release 构建目录中。

服务器发布仍然是一个显式的发布操作。构建安装程序不会创建或发布服务器版本、策略、清单或许可证。

独立开发者构建

一个独立的更新客户端构建对于集中编译和演示测试很有用。它不是最终用户包。

从父仓库根目录：

cmake -S update-client -B out/build/update-client-release
cmake --build out/build/update-client-release --config Release `
--target Launcher Updater Bootstrap MainApp

默认情况下，子项目会在父仓库的 3rdparty 目录中查找。对于不同的批准布局，请传递 更新客户端第三方库根目录；标准的包特定 CMake 提示仍可用于专注的开发者构建。请保留所有未提交到 CMake 文件中的值。不要在父应用程序选择的运行时上覆盖第二个 Qt 运行时。

独立输出是临时的开发者输出。不要将其压缩或发送给用户。

包接受检查清单

在交付前，请对照干净的安装阶段验证以下所有内容：

• Launcher，Updater，Bootstrap 和 SimCAE 存在于预期的运行时目录中。
• 已安装的用户入口点和快捷方式启动 Launcher，而不是 SimCAE。
• 在 Release 版本中拒绝直接启动 SimCAE。
• 未安装 app_config.json，client.ini，源 config.json 或示例产品配置。
• 公开验证材料和嵌入式翻译资源存在。
• 没有 PDB、ILK、带有 Debug 后缀的 Qt 运行时或其他 Debug 产物。
• 在预期的安装路径下存在一个且仅有一个 SimCAE 可执行文件。
• 运行时依赖闭包来源于配置的 Release 包；没有 DLL 或共享库解析到开发工作站路径。
• 受保护的文件与已签名的当前版本清单文件匹配。如果支持离线首次启动，其已签名的策略和清单缓存都存在且有效。
• 开发机器上的可变状态不存在。
• 在 Launcher 旁边放置一个伪造的 app_config.json 文件无法更改应用程序身份、渠道、端点、可执行策略或票务验证。
• 安装、启动、更新、回滚和卸载均从真实安装位置执行。

运行时兼容性

更新运行时和 SimCAE 共享已部署的 Qt 和编译器运行时。打包更改不得用不同的 Qt 构建覆盖该运行时。Qt 库中的入口点错误通常表示混合运行时，而不是缺少配置文件。

对于提升系统安装，首先验证首次注册和状态写入，而不应授予整个应用程序目录的写入权限。运行时状态应存储在本机机器存储或批准的数据位置，而不是放在可执行文件旁边。

故障排除

目标包缺失

确认在配置过程中已找到 Qt Installer Framework，并检查配置输出。不要切换到 package_installer_qt。

发布版本加载调试库

使用专用的发布预设重新配置，并检查所选导入的目标。不要重命名调试二进制文件或在产品树中添加别名。

设备注册无法持久化

确认 Launcher 具备用于机器范围状态的平台权限，并且已安装的构建正在使用原生状态后端。不要将安装目录中的 app_config.json 写入作为变通方法。

更新应用程序回滚

检查更新事务的诊断信息，并确认候选进程在配置的超时时间之前已写入请求的健康标记。绝不要强制提交未经验证的候选进程。