update-client/Docs/02-编译环境和第三方依赖说明.md

客户端编译环境和第三方依赖说明

thirdparty/ 是本机依赖目录，已经被 .gitignore 忽略，不会提交到 Git。

当前客户端构建依赖：

1. Qt 5.15.2 或兼容的 Qt 5 版本
2. OpenSSL

Windows 下推荐使用 Qt 5.15.2 msvc2019_64 和 OpenSSL-Win64；Linux 下使用系统安装的 Qt/OpenSSL 开发包。

先看结论：

• Windows：配置 Qt 环境变量，把 OpenSSL 复制到 thirdparty/OpenSSL-Win64。
• Linux：用 apt 安装 Qt/OpenSSL 开发包。
• thirdparty/ 只放本机依赖，不提交 Git。

1. Qt 配置

Windows

Qt 路径由本机环境变量提供。你需要在 Windows 环境变量里配置 Qt 路径，让 CMake 的 find_package(Qt5 ...) 能找到 Qt。

推荐配置用户环境变量 CMAKE_PREFIX_PATH：

[Environment]::SetEnvironmentVariable("CMAKE_PREFIX_PATH", "C:\Qt\5.15.2\msvc2019_64", "User")

设置完成后，重新打开 PowerShell 或 Visual Studio。

如果只想对当前 PowerShell 窗口临时生效：

$env:CMAKE_PREFIX_PATH="C:\Qt\5.15.2\msvc2019_64"

也可以配置更精确的 Qt5_DIR：

[Environment]::SetEnvironmentVariable("Qt5_DIR", "C:\Qt\5.15.2\msvc2019_64\lib\cmake\Qt5", "User")

CMAKE_PREFIX_PATH 和 Qt5_DIR 二选一即可，推荐使用 CMAKE_PREFIX_PATH。

一般不需要把 C:\Qt\5.15.2\msvc2019_64\bin 加入 Path。项目构建后会通过 windeployqt 复制运行所需的 Qt DLL。

Linux

Linux 下需要安装 Qt5 开发包，让 CMake 能找到 Qt5::Core、Qt5::Network、Qt5::Gui、Qt5::Widgets。

Ubuntu/Debian 示例：

sudo apt update
sudo apt install -y build-essential cmake qtbase5-dev qttools5-dev-tools libssl-dev

如果 Qt 安装在自定义目录，可以临时设置：

export CMAKE_PREFIX_PATH=/path/to/Qt/5.x/gcc_64

2. OpenSSL 配置

Windows

OpenSSL 默认放在：

thirdparty/OpenSSL-Win64

推荐目录结构：

thirdparty/
  OpenSSL-Win64/
    include/
      openssl/
    lib/
      VC/
        x64/
          MD/
          MDd/

复制命令示例：

cd C:\Users\admin\Desktop\update-client
mkdir thirdparty
Copy-Item "C:\Program Files\OpenSSL-Win64" ".\thirdparty\OpenSSL-Win64" -Recurse

如果 OpenSSL 不放在 thirdparty/，可以在配置 CMake 时手动指定：

cmake -S . -B out\build\x64-Debug `
  -G "Visual Studio 17 2022" `
  -A x64 `
  -DSIMCAE_OPENSSL_ROOT="C:\Program Files\OpenSSL-Win64"

Linux

Linux 下 CMake 会通过 find_package(OpenSSL REQUIRED) 查找系统 OpenSSL。通常安装 libssl-dev 即可，不需要 thirdparty/OpenSSL-Win64。

3. Windows 重新配置和编译

如果之前配置过 CMake，建议先删除旧缓存：

cd C:\Users\admin\Desktop\update-client
Remove-Item out\build -Recurse -Force

重新配置：

cmake -S . -B out\build\x64-Debug `
  -G "Visual Studio 17 2022" `
  -A x64

编译：

cmake --build out\build\x64-Debug --config Debug

4. Linux 重新配置和编译

如果之前配置过 CMake，建议先删除旧缓存：

cd ~/project/update-client
rm -rf out/build/linux-x64-debug out/build/linux-x64-release

Debug 构建：

cmake --preset linux-x64-debug
cmake --build --preset linux-x64-debug

Release 构建：

cmake --preset linux-x64-release
cmake --build --preset linux-x64-release

Linux 构建时会自动使用 config/app_config.linux.example.json 作为输出目录里的默认 config/app_config.json，可执行程序名不带 .exe。

5. 提交注意事项

不要提交下面这些内容：

thirdparty/
.vs/
out/
build/
dist/
App/
*.exe
*.dll
*.lib
*.pdb

这些都属于本机依赖、构建产物或打包产物，不应该进 Git。