# 构建和打包

## 所有权

父级 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 仓库根目录运行集成工作流：

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

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

调试开发使用 Debug 预设：

```powershell
cmake --preset SimCAE-debug
cmake --build --preset SimCAE-debug --target SimCAE
```

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

## 测试

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

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

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

## 安装程序

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

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

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

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

## 独立开发者构建

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

从父仓库根目录：

```powershell
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` 写入作为变通方法。

### 更新应用程序回滚

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