# 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. 总览

四块：① 编译器（VS2022 / MSVC）② Git ③ 依赖管理（vcpkg + CMake）④ 全量依赖（含 Qt/VTK，走 vcpkg）。

> **构建方案已定：全 vcpkg（方案 B）。** 原因（已核 vcpkg `ports/vtk/vcpkg.json`）：嵌 VTK 进 Qt 必须用 `QVTKOpenGLNativeWidget`/`QVTKOpenGLStereoWidget`（在 VTK 的 `GUISupportQt` 模块），该模块要求 `vtk[qt]`，而 `vtk[qt]` 依赖 vcpkg 的 `qtbase`+`qtdeclarative`。若再叠加 Qt 官方安装器，会出现**两份 Qt（官方 + vcpkg）DLL/ABI 冲突**（典型表现：运行期 plugin 加载失败或崩溃）。故全家共用同一份 vcpkg Qt。
>
> 代价：首次编译 Qt+VTK 较久（数小时级），用二进制缓存（`VCPKG_BINARY_SOURCES`）缓解；CI 同此方案保证可复现。
>
> （若确有理由保留官方 Qt，须为 vcpkg 的 vtk/qtkeychain 配 overlay-port 指向官方 Qt、禁止 vcpkg 重复构建 Qt——复杂易错，不推荐。）

---

## 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（不单独装——随 vcpkg 全量构建）

方案 B 下 **Qt 不用官方安装器**，由 vcpkg 的 `qtbase`/`qttools` 以及 `vtk[qt]` 共同复用同一份 Qt（见 §5）。这样 VTK、QtKeychain、ADS、应用本体全部链接同一 Qt，杜绝双份 Qt 冲突。

---

## 5. 全量依赖：`vcpkg.json`（项目根，M1 清单）

```json
{
  "name": "geopro-desktop",
  "version": "0.1.0",
  "dependencies": [
    { "name": "qtbase", "default-features": false, "features": ["gui", "widgets", "network", "sql", "sql-sqlite", "concurrent", "opengl"] },
    "qttools",
    { "name": "vtk", "default-features": false, "features": ["qt", "opengl", "gdal", "proj"] },
    "gdal",
    "proj",
    "eigen3",
    "spdlog",
    "fmt",
    "nlohmann-json",
    "openssl",
    "qtkeychain",
    "gtest"
  ],
  "builtin-baseline": "<运行 vcpkg x-update-baseline 自动填入>",
  "overrides": []
}
```

说明：
- **`vtk[qt]`** 拉入 vcpkg `qtbase`+`qtdeclarative`（已核 vcpkg `ports/vtk/vcpkg.json`）；与上面显式声明的 `qtbase` 复用同一份 Qt——这是方案 B 的关键。
- **`vtk` 用 `default-features:false` 只选 `qt/opengl/gdal/proj`**，避免默认拉入 netcdf/seacas/libharu/cgns 等重特性，缩短编译。
- **ADS（Qt-Advanced-Docking-System）**：vcpkg 端口 `qt-advanced-docking-system`——**端口可用性/对 Qt6 支持需在 spike 阶段先验证**；不可用则改 FetchContent 锁 tag（见 §6 备注）。验证通过后加进 dependencies。
- **PCL 不引入**（M1 点规模无需 KD-tree）。
- `builtin-baseline`：`vcpkg x-update-baseline --add-initial-baseline` 自动写入，锁版本（规约 §5.4）。
- 首次编译 Qt+VTK 久，配 `VCPKG_BINARY_SOURCES`（如本地/网络二进制缓存）显著提速。

---

## 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 流程逐条解决。*