4a4ad6bc5f
现状口径:/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 全过;字节卫生零漂移。
90 lines
6.3 KiB
Markdown
90 lines
6.3 KiB
Markdown
# `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` 少几条),改的时候别顺手"对齐"成一套。
|