246 lines
9.9 KiB
Markdown
246 lines
9.9 KiB
Markdown
# Geopro 3.0 桌面客户端 — Windows 开发环境从零搭建指引
|
||
|
||
适用：Windows 10 22H2 / Windows 11，64 位，MSVC 2022 工具链。
|
||
目标：从一台干净的机器，搭到能 `cmake --build` 出可运行的 Qt6 + VTK9 桌面程序。
|
||
|
||
> 配套设计文档：`docs/superpowers/specs/2026-06-07-geopro-desktop-m1-design.md`
|
||
|
||
---
|
||
|
||
## 0. 总览
|
||
|
||
> ⚠️ **构建方案已改定为「方案②-修订」**（经双专家评审 + 实机勘验）。本文档大部分步骤按此更新；**权威步骤以设计 §11 + `docs/superpowers/plans/2026-06-07-m1-phase0-spikes.md` 为准**。
|
||
>
|
||
> **方案②-修订要点**：单一 Qt = **官方 MSVC 预编译 Qt**（`D:\Qt\6.11.1\msvc2022_64`）。**凡依赖 Qt 的组件(VTK/ADS/QtKeychain)都不走 vcpkg**（vcpkg 的 Qt 依赖端口会再编一份 qtbase = 双份冲突）：VTK 用官方 Qt 源码编到 install 前缀；ADS/QtKeychain 走 FetchContent；仅非 Qt 依赖(GDAL/PROJ/OpenSSL/Eigen/...)走 vcpkg。
|
||
> **关键事实**：① 用户原装 `D:\Qt\6.11.1` 是 **MinGW 版**(MSVC 不可链)，须在 Qt 维护工具里补装 **MSVC 2022 64-bit** kit；② VTK 无 MSVC 预编译，三方案都必须源码编；③ 本机 VS18 = MSVC 14.51，链官方 Qt(v143)属"新链旧"，ABI 安全。
|
||
|
||
四块：① 编译器（VS18 / MSVC 14.51）② Git ③ vcpkg（仅非 Qt 依赖）④ 官方 MSVC Qt + 源码 VTK。
|
||
|
||
---
|
||
|
||
## 1. Visual Studio 2022（MSVC + CMake + Ninja）
|
||
|
||
1. 安装 **Visual Studio 2022 Community**（或更高）。
|
||
2. 勾选工作负载 **「使用 C++ 的桌面开发」(Desktop development with C++)**，确保包含：
|
||
- MSVC v143 - VS 2022 C++ x64/x86 生成工具
|
||
- Windows 11 SDK（或 Windows 10 SDK）
|
||
- C++ CMake tools for Windows（自带 CMake + Ninja）
|
||
- C++ AddressSanitizer（用于 Debug Sanitizer，规约 §10.2）
|
||
3. 验证：开「x64 Native Tools Command Prompt for VS 2022」，运行：
|
||
```
|
||
cl
|
||
cmake --version # 应 ≥ 3.21
|
||
ninja --version
|
||
```
|
||
|
||
> 之后所有 cmake/vcpkg 命令都在 **x64 Native Tools 命令行** 里跑（已设好 MSVC 环境变量）。
|
||
|
||
---
|
||
|
||
## 2. Git
|
||
|
||
1. 安装 [Git for Windows](https://git-scm.com/download/win)。
|
||
2. 验证：`git --version`。
|
||
3. 本项目当前**尚未初始化 git 仓库**——首次提交前需 `git init`（见 §7）。
|
||
|
||
---
|
||
|
||
## 3. vcpkg（依赖管理）
|
||
|
||
```powershell
|
||
# 选一个不含空格/中文的路径，例如 C:\dev
|
||
git clone https://github.com/microsoft/vcpkg C:\dev\vcpkg
|
||
C:\dev\vcpkg\bootstrap-vcpkg.bat
|
||
```
|
||
|
||
设环境变量（系统环境变量或当前会话）：
|
||
```powershell
|
||
$env:VCPKG_ROOT = "C:\dev\vcpkg"
|
||
setx VCPKG_ROOT "C:\dev\vcpkg" # 永久（新开终端生效）
|
||
```
|
||
|
||
> 本项目用 **vcpkg manifest 模式**（`vcpkg.json`），不需要手动 `vcpkg install`；CMake 配置时按清单自动拉取。
|
||
|
||
---
|
||
|
||
## 4. Qt（官方 MSVC 预编译 kit）
|
||
|
||
**用官方安装器,但必须是 MSVC kit**(你原装的 `mingw_64` 在 MSVC 下不可用):
|
||
|
||
1. `.\qt-online-installer-windows-x64-4.11.0.exe --mirror https://ftp.jaist.ac.jp/pub/qtproject`
|
||
2. 打开 `D:\Qt\MaintenanceTool.exe` → Add or remove components → 登录 Qt 账号。
|
||
3. 展开 Qt → Qt 6.11.1,勾选 **MSVC 2022 64-bit**,安装。
|
||
4. 完成后存在 `D:\Qt\6.11.1\msvc2022_64\lib\cmake\Qt6`(供 `find_package(Qt6)`)。
|
||
|
||
CMake 经 `CMAKE_PREFIX_PATH=D:/Qt/6.11.1/msvc2022_64` 找到它(见 §6 预设)。**全链路只此一份 Qt**。
|
||
|
||
---
|
||
|
||
## 5. 依赖来源（方案②-修订）
|
||
|
||
| 类别 | 组件 | 来源 |
|
||
|---|---|---|
|
||
| Qt | qtbase/widgets/network/sql/concurrent/opengl + tools | 官方 MSVC kit(§4) |
|
||
| VTK | vtk 9.3[qt,opengl]（+gdal/proj 可选） | **源码编 → install 前缀**(§5.2) |
|
||
| Qt 依赖小件 | ADS、QtKeychain | **FetchContent 对接官方 Qt**(§6.2) |
|
||
| 非 Qt 依赖 | gdal/proj/openssl/eigen3/spdlog/fmt/nlohmann-json/gtest | **vcpkg**(下方 vcpkg.json) |
|
||
|
||
### 5.1 `vcpkg.json`（仅非 Qt 依赖）
|
||
|
||
```json
|
||
{
|
||
"name": "geopro-desktop",
|
||
"version": "0.1.0",
|
||
"dependencies": ["gdal","proj","eigen3","spdlog","fmt","nlohmann-json","openssl","gtest"]
|
||
}
|
||
```
|
||
- **凡依赖 Qt 的(vtk[qt]/qtkeychain/qt-advanced-docking-system)绝不放进 vcpkg**——否则 vcpkg 会再编一份 qtbase = 双份 Qt 冲突(已核 `ports/vtk/vcpkg.json`)。
|
||
- `vcpkg x-update-baseline --add-initial-baseline` 锁版本(规约 §5.4)。
|
||
- 先配 `VCPKG_BINARY_SOURCES` 二进制缓存(实测当前为空),省 GDAL/PROJ 重编。
|
||
|
||
### 5.2 VTK 源码编到 install 前缀（用官方 Qt）
|
||
|
||
实机用 **VTK 9.6.2**(最新稳定,对 Qt 6.11 兼容最好),源码/构建全放 **D:**(C: 仅剩 ~1GB)。脚本见 `external/build_vtk.bat`(已 .gitignore),要点:
|
||
|
||
```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`)。
|
||
> 注:VTK 用 **Release** 编。因此**冒烟程序也用 `msvc-release` 预设构建**,以匹配 Release VTK + Release Qt(避免 `/MD` vs `/MDd` 混链)。需要 Debug 调试 VTK 时再出一份 Debug VTK。
|
||
|
||
---
|
||
|
||
## 6. CMake 接线
|
||
|
||
### 6.1 `CMakePresets.json`（项目根）
|
||
|
||
```json
|
||
{
|
||
"version": 3,
|
||
"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",
|
||
"CMAKE_EXPORT_COMPILE_COMMANDS": "ON"
|
||
}
|
||
},
|
||
{
|
||
"name": "msvc-release",
|
||
"inherits": "msvc-debug",
|
||
"binaryDir": "${sourceDir}/build/release",
|
||
"cacheVariables": { "CMAKE_BUILD_TYPE": "Release" }
|
||
}
|
||
]
|
||
}
|
||
```
|
||
> 全 vcpkg 方案下**不设 `CMAKE_PREFIX_PATH` 指向官方 Qt**——vcpkg 工具链接管 Qt 查找（避免双 Qt）。
|
||
|
||
### 6.2 顶层 `CMakeLists.txt`（骨架）
|
||
|
||
```cmake
|
||
cmake_minimum_required(VERSION 3.21)
|
||
project(geopro_desktop LANGUAGES CXX)
|
||
set(CMAKE_CXX_STANDARD 17)
|
||
set(CMAKE_CXX_STANDARD_REQUIRED ON)
|
||
set(CMAKE_AUTOMOC ON)
|
||
set(CMAKE_AUTORCC ON)
|
||
set(CMAKE_AUTOUIC ON)
|
||
|
||
find_package(Qt6 REQUIRED COMPONENTS Core Gui Widgets Network Sql Concurrent)
|
||
find_package(VTK REQUIRED) # 含 GUISupportQt（vtk[qt]）→ QVTKOpenGLStereoWidget
|
||
find_package(GDAL CONFIG REQUIRED)
|
||
find_package(PROJ CONFIG REQUIRED)
|
||
find_package(Eigen3 CONFIG REQUIRED)
|
||
find_package(spdlog CONFIG REQUIRED)
|
||
find_package(nlohmann_json CONFIG REQUIRED)
|
||
find_package(OpenSSL REQUIRED)
|
||
# find_package(Qt6Keychain CONFIG REQUIRED) # qtkeychain
|
||
# ADS：vcpkg 端口验证通过后 find_package；否则用下方 FetchContent
|
||
|
||
add_subdirectory(src)
|
||
enable_testing()
|
||
add_subdirectory(tests)
|
||
```
|
||
|
||
> VTK 链接用 `vtk_module_autoinit`；视图层用 **`QVTKOpenGLStereoWidget`**（QOpenGLWidget 系，ADS reparent 友好，见设计 §K-9），不用 native 版。
|
||
|
||
> **ADS 备选引入**（若 vcpkg 端口不可用，spike 阶段确定）：
|
||
> ```cmake
|
||
> include(FetchContent)
|
||
> FetchContent_Declare(ads GIT_REPOSITORY https://github.com/githubuser0xFFFF/Qt-Advanced-Docking-System.git GIT_TAG <tag>)
|
||
> FetchContent_MakeAvailable(ads)
|
||
> ```
|
||
|
||
---
|
||
|
||
## 7. 首次配置、编译、运行
|
||
|
||
```powershell
|
||
# 在 x64 Native Tools 命令行、项目根目录
|
||
git init # 首次：初始化仓库
|
||
vcpkg x-update-baseline --add-initial-baseline
|
||
|
||
cmake --preset msvc-debug # 首次会编译 VTK 等，耗时较长
|
||
cmake --build build/debug
|
||
|
||
# 运行（VTK/Qt 的 dll 需在 PATH 或同目录）
|
||
.\build\debug\src\app\geopro_desktop.exe
|
||
```
|
||
|
||
**运行期 DLL 部署（单一 vcpkg 链路）**：
|
||
- 全部 dll（含 Qt）来自 vcpkg：`build/vcpkg_installed/x64-windows/(debug/)bin`。
|
||
- 用 CMake `TARGET_RUNTIME_DLLS` + `add_custom_command(POST_BUILD)` 自动拷贝到 exe 目录（实现阶段加）。
|
||
- **不混用官方 Qt 的 `windeployqt`**——本方案 Qt 来自 vcpkg，混用会拷错版本造成双 Qt 冲突。
|
||
- Qt plugins（platforms/imageformats/sqldrivers 等）由 vcpkg 部署脚本处理；如缺再用 vcpkg 安装树里的 `windeployqt` 对齐同一份 Qt。
|
||
|
||
---
|
||
|
||
## 8. AI 编码上下文基础设施（规约 §10.1，强烈建议先建）
|
||
|
||
项目根放：
|
||
|
||
- `.clang-format`：统一风格（基于 LLVM/Google + 团队微调）。
|
||
- `.clangd`：
|
||
```yaml
|
||
CompileFlags:
|
||
CompilationDatabase: build/debug
|
||
```
|
||
使 clangd 读取 `compile_commands.json`，给 AI/IDE 精确类型上下文。
|
||
- VS Code 装 **clangd** 扩展（禁用微软 C++ IntelliSense 避免冲突），或 CLion 直接用 CMake。
|
||
|
||
---
|
||
|
||
## 9. 验证清单
|
||
|
||
- [ ] `cl` / `cmake` / `ninja` / `git` 命令可用
|
||
- [ ] `VCPKG_ROOT` 已设
|
||
- [ ] `vcpkg.json` 含 qtbase + vtk[qt]（共用一份 Qt），preset **未**指向官方 Qt
|
||
- [ ] `cmake --preset msvc-debug` 成功（Qt+VTK 已拉取编译，首次较久）
|
||
- [ ] `cmake --build` 出 exe
|
||
- [ ] exe 能起一个空 Qt 窗 + 一个 `QVTKOpenGLStereoWidget` 渲染窗（冒烟测试）
|
||
- [ ] 部署后 exe 目录只有一份 Qt6*.dll（无双 Qt）
|
||
- [ ] `compile_commands.json` 生成，clangd 正常索引
|
||
|
||
---
|
||
|
||
## 10. 与设计文档对应的 spike 门槛
|
||
|
||
本指引服务于设计 §15 的第一周 spike：① 全 vcpkg 构建/部署打通（本文）；② ADS + `QVTKOpenGLStereoWidget` 浮动/重停靠不黑屏；③ 真实样本跑通 banded contour。三者通过再进入完整实现计划。
|
||
|
||
---
|
||
|
||
*遇到具体报错（VTK/Qt/GDAL 链接、ADS 端口、双 Qt）按规约 §10.4 由工程师复核；AI 协助按 build-error-resolver 流程逐条解决。*
|