模拟器构建入口改VS版本自适应（新增build_sim，兼容VS2019/2022/2026）；文档同步并补SDL2 SDK下载步骤

2026-09-21 02:30:16 +08:00
parent d0ec983cdd
commit bad5ceac0d
9 changed files with 246 additions and 51 deletions
@@ -30,7 +30,7 @@ simulator/main.c ──→ lv_init → sim_port_init（SDL 窗口 + 键盘）→
 ### 1.3 关键设计决策

 - **SDL2**：LVGL 官方 `lv_port_pc_vscode` 同款显示方案
- **CMake + MSVC**：本机使用 Visual Studio 2019 BuildTools（`Visual Studio 16 2019` / `-A x64`）
+- **CMake + MSVC**：`build_sim.ps1` 按本机 VS 版本自动选生成器（16=2019 / 17=2022 / 18=2026，取已装最高；`-A x64`）。不同机器 VS 版本不同，**勿把生成器写死**
 - **仅 UI 预览**：模拟器只跑 UI，不包含网络（netTask/ftpTask）等 MCU 业务
 - **共享代码不复制**：UI 源码直接引用 `Drivers/BSP/UI/`，MCU 与 PC 同步维护

@@ -39,7 +39,7 @@ simulator/main.c ──→ lv_init → sim_port_init（SDL 窗口 + 键盘）→
 | 依赖 | 版本 | 说明 |
 |------|------|------|
 | CMake | ≥ 3.15 | 本机验证 4.3.0-rc1 |
-| MSVC | VS2019 BuildTools | `Visual Studio 16 2019` 生成器，Hostx64/x64 |
+| MSVC | VS2019 / 2022 / 2026 任一 | `build_sim.ps1` 自动探测生成器（16=2019 / 17=2022 / 18=2026，取已装最高），Hostx64/x64 |
 | SDL2 | 2.32.10 | 已解压到 `simulator/SDL2/`，无需安装 |
 | 操作系统 | Windows | 已验证 win32 |

@@ -70,11 +70,12 @@ simulator/main.c ──→ lv_init → sim_port_init（SDL 窗口 + 键盘）→
 ### 3.2 配置 CMake 并构建

 ```powershell
-cd simulator
-cmake -B build -G "Visual Studio 16 2019" -A x64
-cmake --build build --config Debug
+# 仓库根目录执行（自动探测本机 VS 版本：2019/2022/2026）
+& "simulator\build_sim.bat"
 ```

+> 手动等效：`cd simulator; cmake -B build -G "Visual Studio <NN> <YYYY>" -A x64; cmake --build build --config Debug`，生成器号须与本机 VS 大版本一致（16=2019 / 17=2022 / 18=2026）。
+
 生成的可执行文件：`simulator/build/Debug/lvgl_sim.exe`（SDL2.dll 由 POST_BUILD 自动复制到同目录）。

 ### 3.3 运行
@@ -91,18 +92,13 @@ cd simulator\build\Debug
 ### 4.1 构建 + 运行

 ```powershell
-cd simulator
-cmake --build build --config Debug        # 增量编译
-.\build\Debug\lvgl_sim.exe                # 运行
+# 仓库根目录执行（增量构建；生成器变化时自动删 build/ 重建）
+& "simulator\build_sim.bat"
+.\simulator\build\Debug\lvgl_sim.exe      # 运行
 ```

-> 改 CMakeLists.txt 后需重新 `cmake -B build`；仅改 .c/.h 时直接 `cmake --build` 即可。
-> 遇到奇怪问题时先删 `build/` 全量重建：
-> ```powershell
-> Remove-Item -Recurse -Force build
-> cmake -B build -G "Visual Studio 16 2019" -A x64
-> cmake --build build --config Debug
-> ```
+> 改 CMakeLists.txt 后再跑一次 `build_sim.bat` 即可（缓存不匹配会自动重建）。
+> 遇到奇怪问题时加 `-Clean` 全量重建：`& "simulator\build_sim.bat" -Clean`

 ### 4.2 键盘操作

@@ -255,6 +251,7 @@ A: 不能。模拟器仅预览 UI，不含 CH395F/NAND/ADC 等硬件业务。
 | `simulator/lv_conf.h` | 新增 | 模拟器 LVGL 配置 |
 | `simulator/dbg_log.h` | 新增 | printf 日志 stub |
 | `simulator/CMakeLists.txt` | 新增 | 构建脚本 |
+| `simulator/build_sim.bat` / `.ps1` | 新增 | 一键构建（VS2019/2022/2026 生成器自适应；.bat 绕过 PowerShell 执行策略） |
 | `simulator/SDL2/SDL2-2.32.10/` | 新增 | SDL2 SDK（含 include/SDL2/ 子目录） |
 | `Lib/lvgl/CMakeLists.txt` | 新增 | LVGL 最小 CMake（仅模拟器用） |
 | `Drivers/BSP/UI/ui_menu.c` | 未改 | 共享 UI 代码 |
@@ -9,7 +9,7 @@

 | 项 | 说明 |
 |---|---|
-| 模拟器已构建 | 仓库根目录：`cmake --build simulator/build --config Debug`（首次需先 `cd simulator; cmake -B build -G "Visual Studio 16 2019" -A x64`，见 `simulator/README.md` §3.2） |
+| 模拟器已构建 | 仓库根目录：`& "simulator\build_sim.bat"`（自动探测本机 VS2019/2022/2026 生成器，见 `simulator/README.md` §3.2） |
 | Python | 统一入口 `.venv\Scripts\python.exe`（AGENTS.md「Python 环境」）；两个回归脚本纯标准库，任意 python3 均可，为保持一致一律用 .venv |

 ## 二、流程总览
@@ -19,7 +19,7 @@ flowchart LR
    subgraph DEV["① 开发机（Windows PC）"]
        K[Keil MDK-ARM v5<br/>MCU 编译/烧录]
        X[STM32CubeMX 6.17.0<br/>外设配置/代码再生成]
-        S[CMake + VS2019<br/>LVGL PC 模拟器]
+        S[CMake + VS2019/2026<br/>LVGL PC 模拟器]
        P[Python .venv<br/>字体/回归脚本]
        T[Python 串口助手 serial_tool<br/>串口调试/自动测试]
        G[Graphviz<br/>引用关系图渲染（可选）]
@@ -96,16 +96,14 @@ flowchart LR
 | 项 | 要求 | 说明 |
 |---|---|---|
 | CMake | ≥ 3.15 | 本机实测 4.3.0-rc1 |
-| 编译器 | **Visual Studio 16 2019**（C++ x64 工作负载） | 生成器固定 `"Visual Studio 16 2019"`、`-A x64`；CMakeLists 已加 `/utf-8` 消中文注释告警 |
+| 编译器 | **VS2019 / 2022 / 2026 任一**（C++ x64 工作负载） | `build_sim.ps1` 按本机 VS 大版本自动选生成器（16=2019 / 17=2022 / 18=2026）、`-A x64`；CMakeLists 已加 `/utf-8` 消中文注释告警 |
 | Windows SDK | 10.0.19041 及以上 | CMake 配置时自动选用已装版本 |
-| SDL2 | 2.32.10 | **随仓库提供**（`simulator/SDL2/` 预编译 SDK，含 x64 库与头文件副本），无需系统安装 |
+| SDL2 | 2.32.10（预编译，无需系统安装） | **不在仓库**（`simulator/SDL2/` 目录 gitignore，fresh clone/换机须本地下载一次）；缺失时的下载/解压/校验步骤见**第 3 步** |
 | 产物 | `simulator/build/Debug/lvgl_sim.exe` | `build/` 为生成物（gitignore），可整体删除重建 |

 ```powershell
-cd simulator
-cmake -B build -G "Visual Studio 16 2019" -A x64   # 仅首次（改 CMakeLists.txt 后需重跑）
-cmake --build build --config Debug                  # 日常增量
-.\build\Debug\lvgl_sim.exe                          # 运行（纯键盘导航 ↑↓←→ / Enter / Esc）
+& "simulator\build_sim.bat"                          # 一键构建（自动探测 VS 版本；首次自动配置，改 CMakeLists.txt 后需重跑）
+.\simulator\build\Debug\lvgl_sim.exe                 # 运行（纯键盘导航 ↑↓←→ / Enter / Esc）
 ```

 > 模拟器与 MCU **共用 UI 源码**（`Drivers/BSP/UI/`），无硬件业务（网络推流除外，Winsock 版）。
@@ -205,15 +203,53 @@ winget install Git.Git
  - 固件包须 **STM32Cube FW_F4 V1.28.3**（与仓库 HAL 驱动一致；若未随附，在 CubeMX `帮助 → 管理` 下载对应包）
  - ⚠ 更新版本的 CubeMX 会升级 HAL 驱动、产生大量无关 diff，**勿随意用最新版**

-**第 3 步：VS2019 + CMake**（模拟器工具链）
+**第 3 步：VS（2019/2022/2026 任一）+ CMake**（模拟器工具链）

 ```powershell
 winget install Kitware.CMake        # ≥3.15
 ```

- VS2019 Community 已下架主站，从**存档页**下载：<https://visualstudio.microsoft.com/zh-hans/vs/archives/>（直链：<https://aka.ms/vs/16/release/vs_community.exe>）
-  - 工作负载勾选 **“使用 C++ 的桌面开发”**；单个组件勾 **Windows 10 SDK (10.0.19041)**
- **SDL2 不用装**——仓库 `simulator/SDL2/` 已含 2.32.10 预编译 SDK（仅当缺失时补：https://github.com/libsdl-org/SDL/releases ）
+- VS 版本不固定：构建入口 `simulator\build_sim.bat` 自动探测本机 VS 大版本选生成器（16=2019 / 17=2022 / 18=2026），装任一即可
+- 新装选 VS2019 的注意：Community 已下架主站，从**存档页**下载：<https://visualstudio.microsoft.com/zh-hans/vs/archives/>（直链：<https://aka.ms/vs/16/release/vs_community.exe>）；装 VS2022/VS2026 走主站下载
+  - 工作负载勾选 **“使用 C++ 的桌面开发”**；单个组件勾对应 **Windows 10/11 SDK**
+- **SDL2 无需系统安装**（用预编译 SDK），但**不在仓库**——`simulator/SDL2/` 被 gitignore，`git clone` 后本地没有；目录不存在时按下面步骤补一次
+
+  **补 SDL2 SDK（仅当 `simulator/SDL2/` 缺失）**
+
+  ```powershell
+  # 1) 下载官方 2.32.10 VC 预编译包（GitHub Releases，约 7 MB）
+  New-Item -ItemType Directory -Force simulator\SDL2 | Out-Null
+  [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
+  Invoke-WebRequest -Uri "https://github.com/libsdl-org/SDL/releases/download/release-2.32.10/SDL2-devel-2.32.10-VC.zip" `
+      -OutFile simulator\SDL2\SDL2-devel-2.32.10-VC.zip -UseBasicParsing
+
+  # 2) 解压到 simulator/SDL2/；顶层目录名须为 SDL2-2.32.10
+  #    （若解压出 SDL2-devel-2.32.10/，改名为 SDL2-2.32.10/）
+  Expand-Archive simulator\SDL2\SDL2-devel-2.32.10-VC.zip -DestinationPath simulator\SDL2 -Force
+
+  # 3) 头文件复制到 include/SDL2/ 子目录（必做：LVGL SDL 驱动写死 #include "SDL2/SDL.h"）
+  $inc = "simulator\SDL2\SDL2-2.32.10\include"
+  New-Item -ItemType Directory -Path "$inc\SDL2" -Force | Out-Null
+  Copy-Item "$inc\*.h" "$inc\SDL2\"
+
+  # 4) 校验 5 个必备文件（全 True = 就绪），然后删 zip
+  foreach ($f in @("include\SDL.h", "include\SDL2\SDL.h", "lib\x64\SDL2.lib",
+                   "lib\x64\SDL2main.lib", "lib\x64\SDL2.dll")) {
+      "{0} : {1}" -f $f, (Test-Path "simulator\SDL2\SDL2-2.32.10\$f")
+  }
+  Remove-Item simulator\SDL2\SDL2-devel-2.32.10-VC.zip
+  ```
+
+  目标目录结构：
+
+  ```
+  simulator/SDL2/SDL2-2.32.10/
+  ├── include/            ← SDL.h 及各头文件
+  │   └── SDL2/           ← 头文件副本（第 3 步；缺它编译报 C1083: cannot open include file "SDL2/SDL.h"）
+  └── lib/x64/            ← SDL2.lib / SDL2main.lib / SDL2.dll（构建与运行均从此取）
+  ```
+
+  > 内网机器连不上 GitHub：在任一台有网的机器下载 zip（release 页：<https://github.com/libsdl-org/SDL/releases/tag/release-2.32.10>）拷过去，再走上面第 2~4 步。

 **第 4 步：Python**（`.venv` 脚本工具链）

@@ -274,10 +310,8 @@ pre-commit run --all-files          # 首次全库基线扫描

 ```powershell
 & "MDK-ARM\build.bat"                                            # → BUILD_OK: 0 errors, 0 warnings
-cd simulator
-cmake -B build -G "Visual Studio 16 2019" -A x64
-cmake --build build --config Debug                               # 0 警告
-.\build\Debug\lvgl_sim.exe                                       # 出 160×160 单色菜单画面
+& "simulator\build_sim.bat"                                      # 模拟器一键构建（自动探测 VS 版本），0 警告
+.\simulator\build\Debug\lvgl_sim.exe                             # 出 160×160 单色菜单画面
 & '.venv\Scripts\python.exe' simulator\tests\check_menu_rows.py           # PASS
 & '.venv\Scripts\python.exe' simulator\tests\check_content_pages.py --update  # 首次生成参考图
 & '.venv\Scripts\python.exe' simulator\tests\check_content_pages.py       # 再跑 → PASS
@@ -290,7 +324,7 @@ pre-commit run --all-files
 - [ ] Windows 10/11 x64 + PowerShell 5.1+
 - [ ] Keil MDK-ARM v5.x 装到 `C:\Keil_v5\`（或已同步修改两个 bat）+ CMSIS / STM32F4 DFP 包
 - [ ] STM32CubeMX 6.17.0 已装（与 .ioc 版本一致；含/可装 STM32Cube FW_F4 V1.28.3 固件包）
- [ ] VS2019（C++ x64 工作负载）+ Windows 10 SDK + CMake ≥3.15
+- [ ] VS2019 / 2022 / 2026 任一（C++ x64 工作负载）+ Windows 10/11 SDK + CMake ≥3.15（模拟器构建脚本自动适配 VS 版本）
 - [ ] `git clone` 仓库 → `pre-commit install`；cppcheck 入 PATH
 - [ ] 建 `.venv` 并 `pip install -r requirements.txt`
 - [ ] `npm i -g lv_font_conv`
@@ -462,8 +496,8 @@ pre-commit run --all-files
 | `build.bat` 找不到 UV4 / 闪退 | Keil 未装在 `C:\Keil_v5\` | 装到该路径，或改 `build.bat` / `download.bat` 的 `UV4=` 行 |
 | Keil 编译报编译器不识别 | 新装 MDK 只有 armclang | 工程锁 `uAC6=0`，必须用带 **ARMCC v5** 的 MDK v5.x |
 | CubeMX 再生成后出现大量 diff / 新告警 | 用了比工程记录更新的 CubeMX / 固件包版本 | 用 git 还原生成文件，按 **.ioc 记录的 CubeMX 6.17.0 + STM32Cube FW_F4 V1.28.3** 重新生成 |
-| CMake 配置失败：找不到生成器 | 未装 VS2019 | 装 VS2019（C++ x64 工作负载）；勿改生成器（工程按 VS16 配置） |
-| 模拟器构建报 `SDL2/SDL.h` 找不到 | 头文件副本缺失 | 按 `simulator/README.md` §四.1 把 SDK 头文件复制到 `include/SDL2/`（仓库已含，仅删过 SDK 目录才需要） |
+| CMake 配置失败：找不到生成器 | 本机 VS 大版本与生成器不匹配 | 统一走 `simulator\build_sim.bat`（自动探测 VS 版本选生成器）；手动 cmake 时 `-G` 号须与本机 VS 一致（16=2019 / 17=2022 / 18=2026） |
+| 模拟器构建报 `SDL2/SDL.h` 找不到 | `simulator/SDL2/` SDK 缺失（不入库）或头文件副本没做 | 按第 3 步"补 SDL2 SDK"完整走一遍（下载 → 解压 → 头文件复制到 `include/SDL2/` → 5 文件校验） |
 | `.venv` 不存在 / 脚本 ModuleNotFound | venv 未建（不入库） | 按 §2.4 重建 + `pip install -r requirements.txt` |
 | pip 装依赖报 UnicodeDecodeError | `requirements.txt` 含中文注释 | 保持该文件**纯 ASCII**（pip 按 GBK 代码页解码） |
 | 字体生成 / 转 PNG 报缺模块 | 误用 PATH 里的 msys64 python | 一律用 `.venv\Scripts\python.exe` |
@@ -499,6 +533,8 @@ pre-commit run --all-files

 | 日期 | 变更 |
 |---|---|
+| 2026-09-21 | 更正 SDL2 描述：`simulator/SDL2/` 并不入库（gitignore，fresh clone 缺失），原"**随仓库提供**/不用装"表述有误；第 3 步补全官方预编译包下载（直链 + 内网中转）、解压、`include/SDL2/` 头文件复制、5 文件校验步骤；§2.3 表格与速查表同步修正 |
+| 2026-09-21 | 模拟器构建改为自适应：新增 `simulator/build_sim.bat/.ps1`（vswhere 自动探测本机 VS 大版本 → 生成器 16=2019 / 17=2022 / 18=2026；`build/` 生成器不符自动删除重建，删除带重试抗文件锁）；VS 版本不再固定，2019/2022/2026 兼容：总览图、§2.3、第 3 步、第 10 步冒烟、搭建清单、速查表同步更新 |
 | 2026-09-16 | 补 Graphviz（引用关系图渲染，可选）：新增 §2.8，原 §2.8/§2.9 顺延为 §2.9/§2.10（章节内步骤号不变）；总览图、搭建清单、§2.10 下载表、相关文档各补一项 |
 | 2026-09-13 | 初版：汇总开发机（Keil / VS2019+SDL2 / Python venv / 字体 / 串口工具 / pre-commit）、目标板（引脚 / 资源预算 / 下载 / 功能开关）、网络现场部署（默认参数 / 端口 / 验收清单）、远端客户端四类环境要求，附一次性搭建清单（含分步安装命令与冒烟验证）与常见环境问题速查 |
 | 2026-09-13 | §2.8 各组件补手动下载网址；新增 §2.9 手动下载来源速查表 |