From 6b90fa0581c5cb02f8969e908b4ccc47f1054a96 Mon Sep 17 00:00:00 2001 From: Wanderingss <1624155937@qq.com> Date: Thu, 1 Oct 2026 07:03:53 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=87=E6=A1=A3=EF=BC=9A=E8=A1=A5=E5=85=85?= =?UTF-8?q?=E4=B8=BB=E6=9C=BA=E4=BE=A7=E5=8D=95=E5=85=83=E6=B5=8B=E8=AF=95?= =?UTF-8?q?=EF=BC=88L0.5=EF=BC=89=E7=9A=84=E7=8E=AF=E5=A2=83=E8=A6=81?= =?UTF-8?q?=E6=B1=82?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 新增 L0.5 主机侧单测需 MSVC（cl.exe）离线编译真实源码，此前环境 文档未覆盖该依赖。本次补齐环境侧全部引用点： - 项目部署环境要求.md： · §2.3 由"PC 模拟器环境"扩为"PC 侧编译环境（模拟器 + 主机侧单元 测试）"，明确同一套 VS 的 cl.exe 同时服务两者，MSVC 由"仅模拟器 需要"升级为"提交门禁需要" · §2.7 pre-commit 表补 watchdog-unit-test 钩子 + "未装 VS 会被拦截" · 总览拓扑图加 MSVC 节点；第 3 步 / 第 10 步冒烟 / 搭建清单 / §2.10 下载表（补 VS2022/2026）/ 速查表（补 cl.exe 缺失、 C1083 stdio.h 两条）/ 相关文档 / 变更记录同步 - 测试开发标准流程.md： · §4.2 补 L0.5 环境要求表（cl.exe / SDK / 纯标准库 Python / 缺失时 退出码 2 且钩子拦截）+ "不调 vcvars64.bat（reg.exe 受限）"原因 · §4.1 工具清单标注该运行器需 VS --- docs/测试说明/测试开发标准流程.md | 17 ++++++++++++- docs/环境与部署/项目部署环境要求.md | 38 ++++++++++++++++++++++------- 2 files changed, 45 insertions(+), 10 deletions(-) diff --git a/docs/测试说明/测试开发标准流程.md b/docs/测试说明/测试开发标准流程.md index 53154cec..0cec607e 100644 --- a/docs/测试说明/测试开发标准流程.md +++ b/docs/测试说明/测试开发标准流程.md @@ -194,7 +194,7 @@ static void phaseN_run(void) { | Python 串口助手（serial_tool） | `tools/serial_tool/serial_tool.py`（.venv + pyserial） | 常驻 daemon + 薄 CLI：列端口 / 开关 / 收发 / 全量日志 / wait-idle | | `test/host/run_boot_test.py` | `test/host/` | 一键闭环：采集 → 烧录 → 提取日志 → 校验 | | `test/host/verify_log.py` | `test/host/` | 日志标记校验（Required / Forbidden → PASS / FAIL） | -| **`test/host/watchdog/run_unit_test.py`** | `test/host/watchdog/` | **L0.5 主机侧单测**：MSVC 离线编译真实 `task_watchdog.c` + 可观测桩，穷举判定状态机（零硬件、秒级） | +| **`test/host/watchdog/run_unit_test.py`** | `test/host/watchdog/` | **L0.5 主机侧单测**：MSVC 离线编译真实 `task_watchdog.c` + 可观测桩，穷举判定状态机（零硬件、秒级）。**需本机装有 VS（`cl.exe`）**，见 §4.2 环境要求 | | `.opencode/serial_config.json` | 仓库 | **串口端口单一配置源**（当前 COM6 / 115200）；换端口只改这个文件 | | `test/host/ftp_*.py`（4 个）/ `ch395f_socket_test.py` / `time_sync_server.py` | `test/host/` | PC 端交互测试工具（FTP 客户端 / socket 回显 / 对时推送） | | `simulator/tests/*.py`（4 个） | `simulator/tests/` | LVGL 模拟器回归脚本（见 §5） | @@ -212,6 +212,20 @@ static void phaseN_run(void) { 3. 用 MSVC 离线编译运行（`run_unit_test.py` 自动探测工具链）； 4. 挂 pre-commit 钩子，被改动时自动跑（**只 commit 不烧录**，秒级）。 +**环境要求**（详见 [`../环境与部署/项目部署环境要求.md`](../环境与部署/项目部署环境要求.md) §2.3 / §2.7）： + +| 项 | 要求 | 说明 | +|---|---|---| +| MSVC `cl.exe` | **装了 VS（2019/2022/2026）即有** | 与 LVGL 模拟器**共用同一套 VS**，无需另装；脚本按本机 VS/SDK 目录自动拼 `INCLUDE`/`LIB` 后直接调 `cl.exe` | +| Windows SDK | 随 VS 勾选"使用 C++ 的桌面开发"+ SDK | `cl.exe` 编 `stdio.h` 等标准头从这里取 | +| Python | 仓库 `.venv` 或任意 python3 | 运行器**纯标准库**，无需第三方依赖 | +| 硬件 | **无** | 不需要开发板 / 串口 / ST-LINK | +| 缺失时 | 运行器报环境错误（**退出码 2**）→ pre-commit 钩子**拦截提交** | 未装 VS 的机器改动被测文件时会被拦，须先装 VS | + +> ⚠ **不调 `vcvars64.bat`**：它内部调用 `reg.exe` 探测环境，部分受限机器（安全策略禁 `reg.exe`） +> 会失败 → 无 `INCLUDE` → `fatal error C1083: 无法打开包括文件 "stdio.h"`。 +> 运行器因此**直接拼 `INCLUDE`/`LIB` 环境变量 + 绝对路径调 `cl.exe`**，无副作用、可重复。 + **约束**： - 平台层的抽取必须**零行为变化、零额外开销**（MCU 端默认实现即原逻辑；`@build` 须 0/0）； @@ -381,5 +395,6 @@ flowchart LR | 日期 | 变更 | |---|---| +| 2026-10-01 | §4.2 补 **L0.5 环境要求表**（MSVC `cl.exe` = 装了 VS 即有、与模拟器共用；Windows SDK；纯标准库 Python；缺失时退出码 2 且 pre-commit 钩子拦截）+ "不调 `vcvars64.bat`（`reg.exe` 受限）"原因说明；§4.1 工具清单标注该运行器需 VS。同步更新 `../环境与部署/项目部署环境要求.md`（§2.3 / §2.7 / 第 3、10 步 / 清单 / 下载表 / 速查表） | | 2026-09-15 | §3.4 更新：P1-6 修复落地（基础线程策略）——USER CODE 区冗余 netTask 创建删除 + `net_task_func` 入口 `ENABLE_HW_LAYER_TESTS` 自挂起守卫；"代码事实/设计约束"按修复后现状重写（硬件层模式中断断言恢复安全、NET 层/产品仍按"netTask 恒在轮询"设计）；彻底方案（`.ioc` 移除）经评估未采用。同日构建验证发现两处**存量**测试固件缺陷（与 P1-6 无关，A/B 对照确证）：① `net_test_task.c` `s_rx_buf` 使用先于声明 → NET 层配置自 2026-08（88160a5）起不可编译；② 128KB 静态 RAM 预算溢出（产品镜像 123.6KB，HW 全阶段固件超 8.7KB、NET 固件超 ~28KB）——已立 P1-9/P1-10 跟踪 | | 2026-09-13 | 重写：对齐现测试架构——统一 `test_config.h` 套件（旧版仅描述 CH395F 单套件与 `ch395fTestTask` 旧入口）；新增 @test 自动化闭环、pre-commit 门禁、UI 模拟器五步门禁、主机侧工具约定；新增"测试构建下 netTask"已知问题（旧版"硬件层模式 netTask 不创建"表述与代码不符，改为设计约束并给出重构路径）；修正附录路径（旧版 `docs/测试说明/CH395F_Test_Guide.md` 等已移入 `docs/测试说明/`）；新增双端注册、内存预算、陷阱沉淀要求 | diff --git a/docs/环境与部署/项目部署环境要求.md b/docs/环境与部署/项目部署环境要求.md index 4d97ce60..7aed5065 100644 --- a/docs/环境与部署/项目部署环境要求.md +++ b/docs/环境与部署/项目部署环境要求.md @@ -22,6 +22,7 @@ flowchart LR S[CMake + VS2019/2026
LVGL PC 模拟器] P[Python .venv
字体/回归脚本] T[Python 串口助手 serial_tool
串口调试/自动测试] + U[MSVC (VS2022 生成工具)
主机侧单元测试 cl.exe] G[Graphviz
引用关系图渲染（可选）] end subgraph TGT["② 目标板（DTU 硬件）"] @@ -91,19 +92,27 @@ flowchart LR - Keil `Options for Target → Target` 页显示的片上内存来自 `.uvprojx` 的 `` 行（IRAM 112 KB / IRAM2 16 KB / IROM 1 MB，同样在仓库）+ Device Pack - ⚠ 新机器**不要在 GUI 里重填 RAM 区**，也**勿改 Target 页**（会回写共享的 `.uvprojx` 影响他人）；确需调整内存布局（如日后启用 SRAM3/CCM）时修改 `.sct` 并提交 -### 2.3 PC 模拟器环境（UI 开发/回归必需） +### 2.3 PC 侧编译环境（模拟器 + 主机侧单元测试，必需） + +> ⚠ 本节涵盖**两类都要 MSVC 的 PC 侧构建**：① LVGL 模拟器（C++，产物 `lvgl_sim.exe`）； +> ② 主机侧单元测试（C，批量离线编译**真实生产源码**，见 §2.10 与 +> `docs/测试说明/看门狗单元测试说明.md`）。两者共用同一套 VS 安装，**无需装两次**。 | 项 | 要求 | 说明 | |---|---|---| -| CMake | ≥ 3.15 | 本机实测 4.3.0-rc1 | +| CMake | ≥ 3.15 | 本机实测 4.3.0-rc1；**仅模拟器需要**，单元测试不用 CMake | | 编译器 | **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/` 目录 gitignore，fresh clone/换机须本地下载一次）；缺失时的下载/解压/校验步骤见**第 3 步** | +| **MSVC C 工具链** | **同上（`cl.exe`）** | **主机侧单元测试的必需项**：`test/host/<模块>/run_unit_test.py` 用 `cl.exe` 离线编译真实源码。**只要装了 VS 就有**（`VC\Tools\MSVC\\bin\Hostx64\x64\cl.exe`），不额外装东西 | +| Windows SDK | 10.0.19041 及以上 | CMake 配置与 `cl.exe` 编译（`stdio.h` 等）都从这里取；随 VS 工作负载勾选安装 | +| SDL2 | 2.32.10（预编译，无需系统安装） | **不在仓库**（`simulator/SDL2/` 目录 gitignore，fresh clone/换机须本地下载一次）；缺失时的下载/解压/校验步骤见**第 3 步**。**仅模拟器需要** | | 产物 | `simulator/build/Debug/lvgl_sim.exe` | `build/` 为生成物（gitignore），可整体删除重建 | ```powershell & "simulator\build_sim.bat" # 一键构建（自动探测 VS 版本；首次自动配置，改 CMakeLists.txt 后需重跑） .\simulator\build\Debug\lvgl_sim.exe # 运行（纯键盘导航 ↑↓←→ / Enter / Esc） + +# 主机侧单元测试（示例：看门狗判定状态机；纯逻辑、零硬件、秒级） +& '.venv\Scripts\python.exe' test/host/watchdog/run_unit_test.py # 退出码 0=PASS / 1=FAIL / 2=环境错误 ``` > 模拟器与 MCU **共用 UI 源码**（`Drivers/BSP/UI/`），无硬件业务（网络推流除外，Winsock 版）。 @@ -159,10 +168,14 @@ python tools/font_gen/extract_cn.py # 任意 python3： | pre-commit | 已安装并 `pre-commit install` | 提交门禁（pre-commit + commit-msg 两类钩子） | | cppcheck | 在 PATH 中 | 本地钩子直接调 `cppcheck --enable=warning,performance,portability,style`（`language: system`） | | python | 在 PATH 中 | 本地钩子调 `scripts/check_mojibake.py`（U+FFFD 乱码）、`scripts/check_coding_standard.py`（规范 V1.0，纯标准库） | +| **MSVC `cl.exe`** | **装了 VS 即有（§2.3）** | **`watchdog-unit-test` 钩子必需**：改 `App/util/task_watchdog.*` 或 `test/host/watchdog/**` 时触发，用 `cl.exe` 离线编译真实源码跑单测。**未装 VS 时该钩子报环境错误（退出码 2）→ 拦截提交** | | gitlint | 随 pre-commit 自动拉取 | commit message 格式（宽松规则，兼容中文标题） | > 检查范围仅项目自有代码；`Lib/`、`Middlewares/`、`Drivers/BSP/UI`、`lftpd`、`dhara`、`test/` 等被排除。 > 全库扫描：`pre-commit run --all-files`。详见 `docs/代码规范/pre-commit使用说明.md`、`docs/代码规范/cppcheck使用说明.md`。 +> +> ⚠ **新增 L0.5 单测钩子（2026-10-01）后，"装了 VS"从"仅模拟器需要"升级为"提交门禁需要"**： +> 只要装了 VS（§2.3）就自动具备，无需额外安装；但**完全未装 VS 的机器在改动看门狗相关文件时会被钩子拦截**。 ### 2.8 引用关系图渲染（Graphviz，可选） @@ -203,15 +216,16 @@ winget install Git.Git - 固件包须 **STM32Cube FW_F4 V1.28.3**（与仓库 HAL 驱动一致；若未随附，在 CubeMX `帮助 → 管理` 下载对应包） - ⚠ 更新版本的 CubeMX 会升级 HAL 驱动、产生大量无关 diff，**勿随意用最新版** -**第 3 步：VS（2019/2022/2026 任一）+ CMake**（模拟器工具链） +**第 3 步：VS（2019/2022/2026 任一）+ CMake**（模拟器工具链 **+ 主机侧单元测试编译器 MSVC**） ```powershell -winget install Kitware.CMake # ≥3.15 +winget install Kitware.CMake # ≥3.15（仅模拟器用；单元测试不用 CMake） ``` - VS 版本不固定：构建入口 `simulator\build_sim.bat` 自动探测本机 VS 大版本选生成器（16=2019 / 17=2022 / 18=2026），装任一即可 +- **这一个 VS 同时提供两样东西**：① 模拟器的 C++ 工具链 + CMake 生成器；② **主机侧单元测试的 `cl.exe`**（§2.3 / §2.10）——装一次即可，**不需要为单测另装编译器** - 新装选 VS2019 的注意：Community 已下架主站，从**存档页**下载：（直链：）；装 VS2022/VS2026 走主站下载 - - 工作负载勾选 **“使用 C++ 的桌面开发”**；单个组件勾对应 **Windows 10/11 SDK** + - 工作负载勾选 **“使用 C++ 的桌面开发”**；单个组件勾对应 **Windows 10/11 SDK**（**`cl.exe` 编 `stdio.h` 等标准头也依赖此处安装的 SDK**） - **SDL2 无需系统安装**（用预编译 SDK），但**不在仓库**——`simulator/SDL2/` 被 gitignore，`git clone` 后本地没有；目录不存在时按下面步骤补一次 **补 SDL2 SDK（仅当 `simulator/SDL2/` 缺失）** @@ -316,6 +330,7 @@ pre-commit run --all-files # 首次全库基线扫描 & '.venv\Scripts\python.exe' simulator\tests\check_content_pages.py --update # 首次生成参考图 & '.venv\Scripts\python.exe' simulator\tests\check_content_pages.py # 再跑 → PASS & '.venv\Scripts\python.exe' tools\serial_tool\serial_tool.py selftest # → SELFTEST PASS +& '.venv\Scripts\python.exe' test\host\watchdog\run_unit_test.py # 主机侧单测 → 39/39 PASSED（退出码 0） pre-commit run --all-files ``` @@ -324,13 +339,13 @@ 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 / 2022 / 2026 任一（C++ x64 工作负载）+ Windows 10/11 SDK + CMake ≥3.15（模拟器构建脚本自动适配 VS 版本） +- [ ] VS2019 / 2022 / 2026 任一（C++ x64 工作负载）+ Windows 10/11 SDK + CMake ≥3.15（模拟器构建脚本自动适配 VS 版本；**同一 VS 提供主机侧单测所需的 `cl.exe`**，见 §2.3 / §2.10） - [ ] `git clone` 仓库 → `pre-commit install`；cppcheck 入 PATH - [ ] 建 `.venv` 并 `pip install -r requirements.txt` - [ ] `npm i -g lv_font_conv` - [ ] 写好 `.opencode/serial_config.json`（本机 COM 口），`serial_tool selftest` PASS - [ ] 下载器（ST-Link 等）USB 驱动已装，Keil `Options for Target → Debug` 驱动一致 -- [ ] 第 10 步冒烟验证全部通过 +- [ ] 第 10 步冒烟验证全部通过（含 `test/host/watchdog/run_unit_test.py` → PASSED） - [ ] （可选）Graphviz 已装（引用关系图渲染：`winget install Graphviz.Graphviz`，见 §2.8） ### 2.10 手动下载来源速查 @@ -345,6 +360,7 @@ pre-commit run --all-files | STM32CubeMX | https://www.st.com/en/tools/stm32cubemx.html | 6.17.0（与 .ioc 一致）；直链 https://www.st.com/resource/en/software_stm32cubemx/stm32cubemx_setup.exe | | STM32Cube FW_F4（固件包） | https://www.st.com/en/embedded-software/stm32cube-f4.html | V1.28.3（与仓库 HAL 驱动一致） | | Visual Studio 2019 | https://visualstudio.microsoft.com/zh-hans/vs/archives/ | 直链：https://aka.ms/vs/16/release/vs_community.exe | +| Visual Studio 2022 / 2026 | https://visualstudio.microsoft.com/zh-hans/downloads/ | 任一版本均可（模拟器构建 + 主机侧单测 `cl.exe`，二者共用） | | CMake | https://cmake.org/download/ | ≥ 3.15 | | Python | https://www.python.org/downloads/windows/ | ≥ 3.10，推荐 3.12 | | Node.js | https://nodejs.org/ | LTS | @@ -498,6 +514,8 @@ pre-commit run --all-files | CubeMX 再生成后出现大量 diff / 新告警 | 用了比工程记录更新的 CubeMX / 固件包版本 | 用 git 还原生成文件，按 **.ioc 记录的 CubeMX 6.17.0 + STM32Cube FW_F4 V1.28.3** 重新生成 | | 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 文件校验） | +| **`run_unit_test.py` 退出码 2 / 报"找不到 MSVC cl.exe"** | 本机未装 VS（C++ 工作负载） | 按 §2.3 装 VS2019/2022/2026（勾"使用 C++ 的桌面开发"），装完即有 `cl.exe`；**提交看门狗相关改动时该钩子会拦截，必须装** | +| **`run_unit_test.py` 编译报 `C1083: 无法打开包括文件 "stdio.h"`** | VS 未勾选 Windows SDK，或 `cl.exe` 路径异常 | 在 VS Installer 里补勾 **Windows 10/11 SDK**；脚本已按本机 VS/SDK 目录自动拼 `INCLUDE`/`LIB`，无需手动 `vcvars64.bat`（其内部 `reg.exe` 在受限机器上会被安全策略拦截） | | `.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` | @@ -522,6 +540,7 @@ pre-commit run --all-files | 远程显示协议 | `docs/UI设计/RemoDispBus协议与接收设计说明.md` | | LVGL 模拟器部署 | `docs/UI设计/LVGL模拟器部署与使用说明.md`、`simulator/README.md` | | 串口调试 / 自动化测试 | `docs/测试说明/串口助手使用指南.md`、`docs/测试说明/串口助手设计说明.md`、`docs/测试说明/自动化测试流程.md` | +| **测试分层 / L0.5 主机侧单测** | `docs/测试说明/测试开发标准流程.md`（分层与门禁）· `docs/测试说明/看门狗单元测试说明.md`（L0.5 范式：MSVC 离线编译 + 平台桩） | | pre-commit / cppcheck | `docs/代码规范/pre-commit使用说明.md`、`docs/代码规范/cppcheck使用说明.md` | | 引用关系图（文件引用） | `docs/架构设计/引用关系图说明.md`（生成工具 `tools/refgraph`；渲染依赖 Graphviz，§2.8） | | 各模块测试指南 | `docs/测试说明/CH395F_Test_Guide.md`、`GD5F2GQ5UE_Test_Guide.md`、`SD2506_Test_Guide.md`、`FTP_Test_Guide.md` | @@ -533,6 +552,7 @@ pre-commit run --all-files | 日期 | 变更 | |---|---| +| 2026-10-01 | **补主机侧单元测试（L0.5）环境要求**：§2.3 由"PC 模拟器环境"扩为"PC 侧编译环境（模拟器 + 主机侧单元测试）"——明确**同一套 VS 的 `cl.exe` 同时服务模拟器与单测**，MSVC 从"仅模拟器需要"升级为"提交门禁需要"；§2.7 pre-commit 表补 `watchdog-unit-test` 钩子及"未装 VS 会被拦截"；第 3 步 / 第 10 步冒烟 / 搭建清单 / §2.10 下载表（补 VS2022/2026 行）/ 速查表（补 `cl.exe` 缺失与 `C1083 stdio.h` 两条）/ 相关文档同步；总览拓扑图加 `MSVC cl.exe` 节点 | | 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 下载表、相关文档各补一项 |