Files
STM32F4-Base/docs/门禁说明/cppcheck.md
T
wandering1 4a4ad6bc5f chore(全仓): @build/@test 旧文档别名清退为技能调用名
现状口径:/keil-build 与 /serial-boot-test 是 DSH 会话的技能调用名,
不是 shell 命令;「名 + 命令行参数」的命令形态改为可执行体
run_boot_test.py 的真实调用。

- AGENTS.md:别名说明重写为「技能调用名不是 shell 命令」,两条目改
  「编译(/keil-build)」「串口回归(/serial-boot-test)」
- keil-build / serial-boot-test 两 skill 调用名与示例同步;task-worktree
  方案文档去掉 @build/@test 惯例从句;@task 保留(不在点名范围)
- 123 文件现状陈述全改;台架捕获、变更记录/时间线、rename 映射输入
  等 41 行历史证据保留旧名
- gen_memory_svg.py 6 处措辞随改,3 张 SVG 产物同批重跑
- 顺手补并行方案同行漏网计数 51→52 钩子

验证:提交期快钩子对 123 文件实跑全 Passed;check_doc_links --all
rc=0(3038 处、无法判定 0);check_mermaid --all rc=0;YAML 解析 52
钩子不变;skill-size rc=0;py_compile 全过;字节卫生零漂移。
2026-10-30 13:03:12 +08:00

90 lines
6.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# `cppcheck` / `test-cppcheck` — 静态分析(同一工具,两套范围与严格度)
> 一句话:它管**单个 C 文件内部**能被看出来的一类错(越界、空指针、未初始化、资源/性能、
> 可移植性)。它**不知道跨文件的事实**,也不看我们的项目契约(那是 `bsp-err` 的活)。
- 两个钩子:`cppcheck`(项目自有代码,`--enable=warning,performance,portability,style`)、
`test-cppcheck`(只扫 `test/`,**只开 warning**,排除 `test/host/*/stub`)。
- `entry: cppcheck`、`language: system`、`types: [c]`、`pass_filenames: true`(**逐文件**分析)、
`--error-exitcode=1`、`--std=c99`、`--quiet`、`--inline-suppr`。
- 两根都带 `stages: [manual]`:**`git commit` 阶段不跑**,只在远端 CI 的「手动阶段门禁」步(逐根
`--hook-stage manual`)与 `scripts/ci_local.py` 的 manual 段跑。手工复跑:
`& '.venv\Scripts\python.exe' -m pre_commit run --all-files --hook-stage manual cppcheck`
(`test-cppcheck` 换 id,**一次只能给一个 id**,多 id 实测报 `unrecognized arguments`)。
## 1. 它在查什么
- 检查集 = cppcheck 的 `warning` / `performance` / `portability` / `style` 四类(`test-cppcheck` 只有 `warning`)。
- `--inline-suppr`:允许源码里用 `// cppcheck-suppress <id>` 单行抑制——**这是唯一的一事一议豁免通道**。
- **抑制项清单**(`args` 里逐条,别当噪音看,每条都是为了让它跑得动):
`missingIncludeSystem` / `missingInclude`(我们没有完整的 include 环境,否则整文件解析不下去)、
`invalidPrintfArgType_sint` / `_uint`(`DBG_*` 宏展开后参数类型判定全是噪音)、
`unusedFunction`(逐文件分析看不到调用方,误报连天)、`unusedStructMember`、
`noExplicitConstructor` / `useStlAlgorithm`(C 项目无关)、`constParameterPointer` /
`constParameterCallback`(建议加 const,属排版建议)、`redundantAssignment`、
`normalCheckLevelMaxBranches`(**分支数上限提示**——见 §6 第 2 条)。
- include 路径:`Inc`、`App`、`Drivers/BSP`、HAL Inc、CMSIS Include、FreeRTOS include。
## 2. 为什么要它
- **真实案例一(把 `simulator/` 纳入受检的直接收获)**:本仓原先在顶层 `exclude` 里整目录挡掉
`simulator/`,实测那是自研代码;纳入 cppcheck 后**立刻揪出 `sim_syslog.c` 一处真实的空指针解引用**。
- **真实案例二(`test/` 为什么单独立钩)**:`test/board/` 下 6300+ 行 C 代码**是要编进固件的**,
此前完全豁免、只靠自律,出过 `s_rx_buf` 使用先于声明。基线:2026-10-03 全量实测 0 条 warning,
所以敢直接挂钩子(先清存量再关闸,顺序不能反)。
## 3. 触发面与看不见的地方
- 排除:`Drivers/CMSIS/`、HAL、`Drivers/BSP/NET/lftpd/`、`Drivers/BSP/dhara/`、`Lib/`、
`Middlewares/`、`MDK-ARM/`、`test/`(`test/` 由第二个钩子负责)。
- UI 生成文件(`ui_font_cn_12`、`ui_menu_tab`)**纳入受检**——生成器按工程约定产出,不是第三方。
- 本机须装了 cppcheck 才有效(远端 CI 的 runner 同样按 `DTU_CPPCHECK` → PATH 探测,缺则 job 直接失败);
CI 不跑构建类门禁 `/keil-build`(见 `docs/CI/README.md`)。
- 速度口径:**单文件约 1~2 秒、全库约 20 s**(2026-10-28 实测 `cppcheck` 20.5 s、`test-cppcheck` 38.1 s)——
提交期不跑它们,全量由 CI 与 `ci_local.py` 的 manual 段承担。
- style 类别 95 项的逐项详解、配置参数与 YAML 引号陷阱 → `docs/代码规范/cppcheck使用说明.md`;
本门只管钩子这一层。
- 典型报错形态:`[path/to/file.c:123]: (style) variableScope The scope of the variable ... can be reduced`。
## 4. 报错怎么读
```
Drivers\BSP\XXX\x.c:123:45: warning: ... [someCheckId]
```
- 单独跑:`cppcheck --enable=warning,style,performance,portability --inline-suppr --std=c99 --quiet <文件>`;
想复现钩子行为,**照抄 `args` 里的抑制清单**,否则噪音会让你误判成"新引入的问题"。
- 确属误报:在**那一行**加 `// cppcheck-suppress <id>` 并写一句为什么;不要用 `--suppress=` 全仓关掉一类。
## 5. 好处
- 便宜、快、无副作用;对越界/空指针/未初始化这类"编译器不管但真会炸"的问题有效。
- `test/` 有独立档位,测试代码不再是法外之地。
## 6. 限制与盲区(今天最有料的一节)
1. **它照不出"返回值被丢弃"**。实跑证据:按本钩子自己的 `--enable` 跑 `gd5f2gq5ue.c`,对
**14 处丢弃 `HAL_SPI_*` 返回值**、以及"未初始化局部量直接进 `P_FAIL` 判定"**一条不报**——
它假定被调函数会写出参,而我们的驱动在失败路径根本不写出参。**这条负结果是 `bsp-err` 加
`consume-result` 检查的直接依据**(另一半依据是 ARMCC v5 不认 `warn_unused_result`)。
2. `normalCheckLevelMaxBranches` 被抑制,但**问题本身还在**:默认检查级别会**限制分支分析**
(它会打印 "Limiting analysis of branches")。分支多的函数,它其实没分析完。想要全量得
显式 `--check-level=exhaustive`(很贵,没挂进提交门禁)。
3. **逐文件**分析(`pass_filenames: true`):没有跨 TU 知识,`unusedFunction` 因此被整条抑制;
跨文件的契约错误(A.c 改了返回值语义、B.c 的判据就失效)看不见。
4. include 缺失被整条抑制 → **解析可能只到一半**,越报"干净"越要留个心眼:某类检查是否根本
没跑到,本工具不告诉你。
5. 它不懂项目约定:错误码、超时单位、分层方向、日志成本一概不管。
## 7. 豁免与基线
- 没有存量基线:**新报即拦**。所以存量必须先清(`test/` 就是这么做的)。
- 两类合法豁免:单行 `// cppcheck-suppress`(要写理由)、`args` 里的整类抑制(要写清为什么整类都是噪音)。
## 8. 改这个门禁本身
- 加抑制项 = 永久放弃一类检查,必须在提交说明里写清噪音样本;能单行抑制就别整类抑制。
- 加/减 `--enable` 档位前,先跑一次全库看新增多少条——直接挂钩子会把所有人卡在提交外。
- 两个钩子的抑制清单**有意不同**(`test-cppcheck` 少几条),改的时候别顺手"对齐"成一套。