216 lines
13 KiB
Markdown
216 lines
13 KiB
Markdown
# Geopro 3.0 桌面客户端 — Windows 开发环境从零搭建指引
|
||
|
||
适用：Windows 10 22H2 / Windows 11，64 位，**MSVC 2022（v143）工具链**。
|
||
目标：从一台干净的机器，搭到 `build.bat app` 能编出可运行、且**不因 ABI 不匹配崩溃**的 Qt6 + VTK9 桌面程序。
|
||
|
||
> 最后核对：2026-07-01，已对齐 `CMakePresets.json` / `vcpkg.json` / 根 `CMakeLists.txt` / `build.bat` 的真实配置。
|
||
> ⚠️ 若你手里有更早版本的本文档：**§6.1/§7/§9 曾残留「全 vcpkg（Qt/VTK 也走 vcpkg）」的旧方案，与现状矛盾——以本版为准。** 现状是「方案②-修订」：**官方预编译 Qt + 源码编 VTK + vcpkg 只管非 Qt 依赖**。
|
||
|
||
---
|
||
|
||
## 0. 总览（方案②-修订）
|
||
|
||
**单一 Qt = 官方 MSVC 预编译 Qt**（`D:\Qt\6.11.1\msvc2022_64`）。**凡依赖 Qt 的组件都不走 vcpkg**（vcpkg 的 Qt 端口会再编一份 qtbase = 双份 Qt 冲突）：
|
||
|
||
| 组件 | 来源 | 备注 |
|
||
|---|---|---|
|
||
| Qt 6.11.1（Core/Gui/Widgets/Network/Sql/Concurrent/OpenGL + tools） | **官方 MSVC 2022 64-bit kit**（§4） | 路径由预设 `CMAKE_PREFIX_PATH` 指定 |
|
||
| VTK 9.6.x（GUISupportQt/RenderingOpenGL2/RenderingFreeType/InteractionStyle/FiltersSources…） | **源码 Release 编 → `external/vtk-install`**（§5） | 必须对齐同一份 Qt + 同一工具集 + Release/`/MD` |
|
||
| ADS（Qt-Advanced-Docking-System 4.3.1） | **FetchContent 自动**（配置时拉，对接官方 Qt） | 无需手动 |
|
||
| QtKeychain v0.14.0 | **FetchContent 自动**（`BUILD_WITH_QT6`） | 无需手动 |
|
||
| Qwt 6.2（二维科学图表） | **手工克隆到 `external/qwt-src`**（§5.3，gitignored） | 缺失则详情页图表功能不编入 |
|
||
| vendored 3DGPRViewer（geopro_gpr3dv） | 仓库内 `external/gpr3dviewer`（随仓库） | 无需手动 |
|
||
| 非 Qt 依赖：eigen3 / gdal / gtest / nlohmann-json / openssl / proj | **vcpkg manifest**（`vcpkg.json`，有 baseline 锁版本） | 配置时自动拉 |
|
||
|
||
**ABI 铁律（否则运行时崩溃，见 §10）**：Qt(预编译 msvc2022) / VTK(你自己编) / app / 所有 FetchContent 组件，**必须同一工具集(v143)、同一运行时(`/MD`)、同一配置(全 Release)**。任何一处混 Debug/Release 或换工具集，`std::map`/`std::string` 跨界就崩。
|
||
|
||
---
|
||
|
||
## 1. Visual Studio（MSVC v143 + CMake + Ninja）
|
||
|
||
1. 安装 **Visual Studio 2022 Community**（或更高）。`build.bat` 也兼容 VS2026 preview，但**其工具集必须与预编译 Qt 的 msvc2022(v143) ABI 兼容**——若用 VS2026 的更新工具集，稳妥做法是**用同一工具集重编 VTK**（§5），别让 Qt(v143 预编译) 与 VTK/app(更新工具集) 混。
|
||
2. 勾选工作负载 **「使用 C++ 的桌面开发」**，确保含：
|
||
- MSVC v143 - VS 2022 C++ x64/x86 生成工具
|
||
- Windows 11 SDK（或 Windows 10 SDK）
|
||
- C++ CMake tools for Windows（自带 CMake ≥3.21 + Ninja）
|
||
- C++ AddressSanitizer（Debug Sanitizer 用）
|
||
3. 验证（开「x64 Native Tools Command Prompt for VS」）：`cl` / `cmake --version`（≥3.21）/ `ninja --version`。
|
||
|
||
> `build.bat` 会用 `vswhere` 自动定位 VS 并激活 MSVC 环境，所以**日常构建直接跑 `build.bat` 即可**，不必手动开 x64 命令行。但 `cmake/ninja/cl` **不在 PATH**，手动跑 cmake 前需先激活 vcvars64。
|
||
|
||
---
|
||
|
||
## 2. Git
|
||
|
||
1. 安装 [Git for Windows](https://git-scm.com/download/win)，`git --version` 验证。
|
||
2. 本项目**已是 git 仓库**（无需 `git init`）；正常 `git clone` 即可。
|
||
|
||
---
|
||
|
||
## 3. vcpkg（仅非 Qt 依赖）
|
||
|
||
```powershell
|
||
git clone https://github.com/microsoft/vcpkg C:\dev\vcpkg # 路径不含空格/中文
|
||
C:\dev\vcpkg\bootstrap-vcpkg.bat
|
||
setx VCPKG_ROOT "C:\dev\vcpkg" # 永久；新开终端生效
|
||
```
|
||
- **manifest 模式**：根 `vcpkg.json` 声明依赖 + `builtin-baseline` 锁版本，CMake 配置时自动拉取，**无需手动 `vcpkg install`**。
|
||
- 实际依赖（勿加 Qt/VTK 进来）：`eigen3, gdal, gtest, nlohmann-json, openssl, proj`。
|
||
- **不要随意 `vcpkg x-update-baseline`**——baseline 已锁，改动会漂移依赖版本、可能引入 ABI 不一致。
|
||
- 首次会编 GDAL/PROJ 等，较久；可选配 `VCPKG_BINARY_SOURCES` 二进制缓存加速。
|
||
|
||
---
|
||
|
||
## 4. Qt（官方 MSVC 2022 64-bit kit）
|
||
|
||
**必须是 MSVC kit**——若你原装的是 `mingw_64`，MSVC 下不可链：
|
||
|
||
1. 用官方在线安装器（或已装则开 `D:\Qt\MaintenanceTool.exe`）→ Add or remove components → 登录 Qt 账号。
|
||
2. 展开 Qt → **Qt 6.11.1**，勾选 **MSVC 2022 64-bit**，安装。
|
||
3. 完成后应存在 `D:\Qt\6.11.1\msvc2022_64\lib\cmake\Qt6`。
|
||
4. 预设通过 `CMAKE_PREFIX_PATH=D:/Qt/6.11.1/msvc2022_64` 找到它（§6）。**全链路只此一份 Qt。**
|
||
|
||
> 若你的 Qt 装在别处/别的版本：**改预设/环境的 `CMAKE_PREFIX_PATH` 指向你的 `msvc2022_64`，但版本仍须是 6.11.1**（换版本可能与源码编的 VTK/ADS 不匹配）。
|
||
|
||
---
|
||
|
||
## 5. 源码依赖（手工准备）
|
||
|
||
### 5.1 VTK 9.6.x 源码编到 `external/vtk-install`（用官方 Qt，Release）
|
||
|
||
```bat
|
||
call "<VS>\VC\Auxiliary\Build\vcvars64.bat"
|
||
git clone --depth 1 --branch v9.6.2 https://gitlab.kitware.com/vtk/vtk.git D:\dev\vtk-src
|
||
cmake -S D:\dev\vtk-src -B D:\dev\vtk-build -G Ninja ^
|
||
-D CMAKE_BUILD_TYPE=Release -D BUILD_SHARED_LIBS=ON ^
|
||
-D VTK_GROUP_ENABLE_Qt=YES -D VTK_MODULE_ENABLE_VTK_GUISupportQt=YES ^
|
||
-D Qt6_DIR=D:/Qt/6.11.1/msvc2022_64/lib/cmake/Qt6 ^
|
||
-D CMAKE_PREFIX_PATH=D:/Qt/6.11.1/msvc2022_64 ^
|
||
-D VTK_BUILD_TESTING=OFF -D VTK_BUILD_EXAMPLES=OFF ^
|
||
-D CMAKE_INSTALL_PREFIX=D:/Git/lanbingtech/geopro/external/vtk-install
|
||
cmake --build D:\dev\vtk-build --target install
|
||
```
|
||
- 完成后 `external/vtk-install/lib/cmake/vtk-9.6` 供 `find_package(VTK)`（`CMakePresets.json` 里 `VTK_DIR` 已指向它）。
|
||
- **必须 Release + 与本项目相同的工具集(v143)编**；因此**本项目也用 `msvc-release` 构建**，避免 `/MD` vs `/MDd` 或 Debug/Release 混链（→ §10 崩溃）。需要调试 VTK 时另出一份 Debug VTK，且此时 app 也须整套 Debug。
|
||
- 根 `CMakeLists.txt` 里 `find_package(VTK REQUIRED COMPONENTS ...)` **必须列组件**（否则 `VTK_LIBRARIES` 为空、链不到）；当前组件：`GUISupportQt / RenderingOpenGL2 / RenderingFreeType / InteractionStyle / FiltersSources`（随渲染层增补）。
|
||
|
||
### 5.2 ADS / QtKeychain（FetchContent，自动）
|
||
|
||
无需手动——根 `CMakeLists.txt` 用 `FetchContent` 拉 **ADS 4.3.1** 与 **QtKeychain v0.14.0**，对接同一份官方 Qt（`BUILD_WITH_QT6=ON`）。首次配置会 clone，需能访问 GitHub。
|
||
|
||
### 5.3 Qwt 6.2（手工克隆到 `external/qwt-src`）
|
||
|
||
二维科学图表（数据集详情散点/等值线）依赖 Qwt。`external/qwt-src` 已 gitignore，须自备：
|
||
|
||
```powershell
|
||
# 克隆/解压 Qwt 6.2 源码到 external/qwt-src，使 external/qwt-src/src 存在
|
||
git clone --branch qwt-6.2 https://git.code.sf.net/p/qwt/git external/qwt-src
|
||
```
|
||
- CMake 检测到 `external/qwt-src/src` 才 include `cmake/qwt.cmake` 编 Qwt；**缺失则相关图表功能不编入**（不报错，但详情图表缺失）。
|
||
|
||
---
|
||
|
||
## 6. CMake 接线（现状，勿照旧文档）
|
||
|
||
### 6.1 `CMakePresets.json`（真实内容）
|
||
|
||
```json
|
||
{
|
||
"configurePresets": [
|
||
{
|
||
"name": "msvc-debug",
|
||
"generator": "Ninja",
|
||
"binaryDir": "${sourceDir}/build/debug",
|
||
"cacheVariables": {
|
||
"CMAKE_BUILD_TYPE": "Debug",
|
||
"CMAKE_TOOLCHAIN_FILE": "$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake",
|
||
"VCPKG_TARGET_TRIPLET": "x64-windows",
|
||
"CMAKE_PREFIX_PATH": "D:/Qt/6.11.1/msvc2022_64",
|
||
"VTK_DIR": "${sourceDir}/external/vtk-install/lib/cmake/vtk-9.6"
|
||
}
|
||
},
|
||
{ "name": "msvc-release", "inherits": "msvc-debug",
|
||
"binaryDir": "${sourceDir}/build/release",
|
||
"cacheVariables": { "CMAKE_BUILD_TYPE": "Release" } }
|
||
]
|
||
}
|
||
```
|
||
- **预设确实设 `CMAKE_PREFIX_PATH`（官方 Qt）+ `VTK_DIR`（源码编的 VTK）**——这是「方案②-修订」的核心，别按旧文档去掉它。
|
||
- vcpkg 只经 `CMAKE_TOOLCHAIN_FILE` 管非 Qt 依赖；triplet `x64-windows`。
|
||
|
||
### 6.2 根 `CMakeLists.txt` 要点
|
||
|
||
- `find_package(Qt6 REQUIRED COMPONENTS Core Gui Widgets Network Sql Concurrent)`。
|
||
- `find_package(VTK REQUIRED COMPONENTS GUISupportQt RenderingOpenGL2 RenderingFreeType InteractionStyle FiltersSources)`（**必须列组件**）。
|
||
- MSVC flags：`/utf-8 /MP /W4 /permissive-`；非 Debug 配置产 PDB（`/Zi` + `/DEBUG` + `/OPT:REF,ICF`）。
|
||
- ADS/QtKeychain 经 FetchContent；Qwt 经 `cmake/qwt.cmake`（存在才编）。
|
||
- 视图层用 **`QVTKOpenGLStereoWidget`**（QOpenGLWidget 系，ADS reparent 友好）。
|
||
|
||
---
|
||
|
||
## 7. 首次配置、编译、运行、部署
|
||
|
||
**日常直接用 `build.bat`（推荐）**：
|
||
```
|
||
build.bat app # 配置(首次)+ 增量编 geopro_desktop（Release）
|
||
build.bat test # 编 + ctest 跑单测
|
||
build.bat run # 编 + 启动
|
||
build.bat rebuild # 强制 --clean-first 全量重编（增量疑似漏编时用）
|
||
build.bat configure # CMakeLists 改动后强制重跑 configure
|
||
```
|
||
- `build.bat` 固定 `--preset msvc-release`、`build/release`，自动激活 MSVC 环境。exe：`build/release/src/app/geopro_desktop.exe`。
|
||
- 首次会拉 vcpkg 依赖 + FetchContent(ADS/QtKeychain)，较久；VTK/Qt/Qwt 须已按 §4/§5 就位。
|
||
|
||
**运行期 DLL 部署（官方 Qt，非 vcpkg）**：
|
||
- Qt6*.dll + plugins：用**官方 Qt 的 `windeployqt`**（`D:\Qt\6.11.1\msvc2022_64\bin\windeployqt.exe`）对齐**同一份官方 Qt** 到 exe 目录。
|
||
- VTK*.dll：从 `external/vtk-install/bin` 拷到 exe 目录（或加进 PATH）。
|
||
- **只保证 exe 目录一份 Qt6*.dll（无双 Qt）**；勿混入别处/vcpkg 的 Qt。
|
||
|
||
---
|
||
|
||
## 8. AI/IDE 上下文（clangd）
|
||
|
||
- `.clangd`：`CompileFlags.CompilationDatabase: build/release`（对齐 `build.bat` 的主构建目录；若你主要用 Debug 则指 `build/debug`）。`CMAKE_EXPORT_COMPILE_COMMANDS=ON` 会在该目录产 `compile_commands.json`。
|
||
- VS Code 用 **clangd** 扩展（禁用微软 C++ IntelliSense 避免冲突）。
|
||
|
||
---
|
||
|
||
## 9. 构建环境兼容性检查清单（交付/接手前逐项核对）
|
||
|
||
> 目的：把「配置错→运行时随机崩溃」变成「一眼可查」。**任何一项不满足都可能导致 §10 的 `std::map`/`std::string` ABI 崩溃。**
|
||
|
||
### 9.1 前置就位
|
||
- [ ] `cl` / `cmake`(≥3.21) / `ninja` / `git` 可用；`VCPKG_ROOT` 已设。
|
||
- [ ] Qt **6.11.1** 的 **`msvc2022_64`**（MSVC，非 MinGW）存在于 `CMAKE_PREFIX_PATH` 指向处；`.../msvc2022_64/lib/cmake/Qt6` 在。
|
||
- [ ] `external/vtk-install/lib/cmake/vtk-9.6` 存在（VTK 已源码编 install）。
|
||
- [ ] `external/qwt-src/src` 存在（如需详情页图表）。
|
||
- [ ] `vcpkg.json` 的 `builtin-baseline` 未被改动。
|
||
|
||
### 9.2 ABI 一致性（最关键，防崩溃）
|
||
- [ ] **单一配置**：Qt(预编译) / VTK(你编) / app / ADS / QtKeychain / Qwt **全 Release**（或全 Debug），**绝不混**。日常一律 `build.bat`（msvc-release）。
|
||
- [ ] **同一工具集**：VTK/app 用的 MSVC 工具集与预编译 Qt 的 **v143(msvc2022)** ABI 兼容；若用 VS2026-preview 工具集，**用它重编 VTK**，别让 Qt(v143) 与 VTK/app(更新集) 混。
|
||
- [ ] **同一运行时**：全部 `/MD`（Release 动态 CRT），`_ITERATOR_DEBUG_LEVEL=0`。**绝不把 Release 的 Qt/VTK 链进 Debug 的 app**（Debug 是 `/MDd` + IDL=2，STL 布局不同）。
|
||
- [ ] **VTK 来源正确**：是**你按 §5.1 源码 Release 编、对齐本 Qt** 的那份；**不是** vcpkg 的 VTK、不是别处/别配置的 VTK。
|
||
- [ ] **单一 Qt**：exe 目录/PATH 只有一份 Qt6*.dll，无双 Qt。
|
||
|
||
### 9.3 干净构建验证
|
||
- [ ] 删 `build/` 后 `build.bat app` 从零配置**无错**（尤其无「找不到 Qt6/VTK」「add_subdirectory 目录不存在」）。
|
||
- [ ] `build.bat test` → ctest 全绿。
|
||
- [ ] 启动 app、点对象树、渲染视图**不崩**（§10 的崩溃即出现在这里）。
|
||
|
||
---
|
||
|
||
## 10. 已知崩溃签名 → 根因速查
|
||
|
||
| 现象 | 根因 | 处理 |
|
||
|---|---|---|
|
||
| **点对象树/渲染时，崩在 `std::_Tree::_Find_lower_bound`（`std::map`/`set` 查找），`_Myhead` 是 `0xFFFF...` 之类垃圾值，读取访问冲突** | **STL ABI 不匹配**：Debug/Release 混链、`/MD` vs `/MDd`、`_ITERATOR_DEBUG_LEVEL` 不一致、或工具集不匹配（最常见：**别处/别配置的 VTK/Qt**，或 **Debug app 链 Release 依赖**） | 按 §9.2 逐项核对；**删 `build/` 全 Release 干净重建**；确认 VTK 是 §5.1 那份 |
|
||
| 链接期报「找不到 Qt6::/VTK::」 | 预设 `CMAKE_PREFIX_PATH`/`VTK_DIR` 指向不存在 | 按 §4/§5 就位或改预设路径 |
|
||
| 配置报「add_subdirectory ... 不是已存在目录」 | 引用了未随仓库的目录（如误提交本地临时工具目录） | 从 `CMakeLists.txt` 去掉该引用，或补齐该目录 |
|
||
| 详情页图表缺失但不报错 | `external/qwt-src` 未就位（§5.3） | 克隆 Qwt 后重配置 |
|
||
| 双 Qt / 起不来找不到 platform 插件 | 混入了 vcpkg/别处的 Qt dll | 只用官方 `windeployqt` 对齐单一 Qt |
|
||
|
||
---
|
||
|
||
*遇到具体报错按规约由工程师复核；AI 协助按 build-error-resolver 流程逐条解决。*
|