wandering1/STM32F4-Base
1
0
Fork 0
Code Issues 30 Pull Requests Actions Packages Projects 2 Releases Wiki Activity
Files
728d60675f29bab0af51f6cb500f2ebcf20323cc
STM32F4-Base/docs/门禁说明/cppcheck.md
T
wandering1 6822726b2c docs(门禁说明): 手册 §2 收敛为通用机制与查号表，逐项详解归一到 23 篇 
用户一句"现在门禁都在干什么，我一概不知"引出的收尾。原手册 §2 有 27 个逐钩子小节，只回答
"拦了什么、怎么配"，回答不了"什么时候会骗我"；docs/门禁说明/ 已把逐项详解（含"限制与盲区"
一节）建好，本笔做收敛：同一事实只留一处（docs/文档规范.md 的要求）。

**先搬后删**（否则收敛等于丢事实）：旧 §2 里独有条目逐篇折回，共 18 处插入、15 篇受益。折回的
东西包括：六套主机单测的来历与用例规模（13/36/82/46/32/149 断言，含 nand-port 的"与旧算法
对照"）与"改动公共骨架 unit_test_harness.py 会同时触发 16 个钩子"；UI 页面**两层注册**（构建
注册 vs 框架注册：枚举 + s_defs[] 描述符表）与"豁免不整目录一刀切"；lv-conf-sync 首次落地清掉
26 个 LVGL 9.3 不存在的选项、3 处重复定义、10 项隐式开关显式化，以及 ALLOW_DIFF 端专属白名单
与必须穿过 lv_conf_internal.h 里那层 KCONFIG 包裹；cubemx-survival 的 16 项清单、断言前先剥
C 注释（本仓注释刻意引用历史代码，不剥就恒定误报）、旧手册"自造标记区"建议与看门狗文档实测
教训之间的优先级；id-check 顺带收编 check_test_traceability.py、裸形同字母多义属**显式承认的
盲区**、--update-baseline 只许涨；layer-deps 的注入自证与报错时三条修法（注入回调 / 上层递数据
/ 才谈 ALLOW）；coding-standard **nand_ftl.* 也在排除清单**（我先前那篇漏了）；test-suite-switch
的剥注释判定与派生宏白名单；mem-budget 两类软提醒不拦、退出码 2 是解析失败不是通过；doc-links
的排除目录与状态词 ±40 字符距离；task-table 改栈三步；gitlint 报错样例；no-mojibake 的修复路径。

**顺带抓到旧文档两处错**（记进文档，不悄悄改）：一是 check-added-large-files 的阈值旧手册写
"单个文件 > 1MB"，按本机安装的钩子源码实测是 --maxkb 默认 **500**（500 KB）——已更正，并把
"本目录任何默认值都以实测或安装的钩子源码为准"写进 end-of-file-fixer 当反面教材；二是
**ui-golden 在旧手册里连小节都没有**，只活在配置注释里：除了"有基线不等于有门禁"，这是另一种
失踪——有钩子、没文档。

手册 §2 改写为三节：迁移说明 / **旧编号 → 新文档 查号表**（历史引用靠它读，旧号按"冻结历史不
回改"保留）/ **跨钩子通用机制**：两阶段与换机必须重装 hooks 才带 commit-msg、stash 陷阱、
always: true 已废、改写型与只读型豁免不对称、增量拦截三段式且刻意没有 --write、没有 .map 是
"跳过"不是"通过"、改配置的验收是看目标钩子出现在输出里且不是 Skipped、新增门禁三步必须做
注入自证且"限制与盲区"不许留空，另有快速自查入口。手册 707 行 → 273 行。

引用**按内容**重指（只核编号存在与否不够，同号小节会被当本文自引用静默放过）：编号规范、
scripts/README（顺带更正那里过时的 warn-only 说法，早已关闸为增量拦截）、RAM 使用分析与优化
方案、测试开发标准流程、lvgl-simulator skill、AGENTS 文档表（拆成"每门禁一篇详解"与"通用
机制"两行）、.pre-commit-config.yaml 头注释、docs/README.md 描述、手册自身 §5.5 与 §6 的两处
内部引用。另：表格里的裸节号会被 doc-links 判成本文自引用，查号表统一写成不带 § 的形态。

写说明过程又被自家门禁拦一次：gitlint 篇里引用报错样例时写了两个规则号字面量，被判形态不合规
→ 改成中文描述，没有往台账里塞 reason 解决。

验证：纯文档与注释改动，不动代码，Program Size 不变，故不跑 @build/@test；
check_doc_links --all --sections-strict **171 篇 0 问题**；id-check 增量拦截通过；
pre-commit run **RC=0 / 13 项 Passed**；28 个改动文件字节卫生 **0 异常**（无 BOM、无 CR、
无 U+FFFD、均 LF、无行尾空白）。
2026-10-23 11:44:21 +08:00

5.9 KiB
Raw Blame History

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。

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 不跑构建类门禁（见 docs/CI/README.md）。

  • 速度口径（原手册实测）：单文件约 1~2 秒、全库约 5 秒，所以它能逐文件传参而不拖慢提交。

  • 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 少几条），改的时候别顺手"对齐"成一套。

9. 变更记录

日期 变更
2026-10-23 首篇逐项文档；补记"照不出返回值丢弃"这条实测负结果（它是 consume-result 的由来）
Reference in New Issue View Git Blame Copy Permalink