Files
STM32F4-Base/test/host/common
wandering1 e4981aa2f6 refactor(docs): point entry-file references at their new homes
AGENTS.md stopped being the store of record for build steps, Python env,
hardware pins, doc conventions, log cost and task ownership. Those facts
already live in docs, skills and role files; the entry file now only
points at them. This commit moves every reference that used to name the
entry file to the authoritative landing point, so a reader who follows a
link arrives at the fact instead of at a sentence that no longer exists.

What changed is links and prose, not behaviour. Code, scripts and tests
only have comment and docstring lines touched; the only non-comment edit
in the whole changeset is one note string inside the generated pin table
JSON, and its generator was changed in the same step so the two stay
byte-identical.

New landing points created before the references were retargeted:
- The console single-writer log design doc, section 7.1, is now the single
  authority for log cost: about 90 B flash and 216 B stack per DBG_ line,
  and the rule that deep call chains must predefine DBG_LINE_BUF_MAX.
  It also carries the full list of the twelve translation units that have
  tightened it, plus the grep command that decides the truth if the list
  and the code ever disagree.
- The document writing standard, section 2, now holds the BOM list.
- keil-build skill gains an exit code table: 0 success, 1 build failure,
  2 BuildEnvError, 3 usage, 4 build lock held. This corrects a belief
  that was never actually written down anywhere: exit 2 does not simply
  mean environment error, argparse also exits 2 and the wrapper script
  was remapped so the two no longer collide.

Regenerated and checked byte for byte:
- The end-to-end architecture SVG in docs/images from its generator.
- tools/netlist_semantics/pinout_kb.json from gen_kb.py.
Both are idempotent; running the generators again produces no diff.

Deliberately not touched, because machines read them:
- scripts/check_bom_drift.py joins every line containing BOM and asserts
  four paths are present, so the entry file BOM line must stay one line.
- scripts/gen_task_table.py reads the TASK_TABLE anchors directly.
- scripts/rename_maps and scripts/archive keep their historical wording;
  they describe what happened, not what is true now.

Verified: doc links report the same six pre-existing findings as the base
commit and no new ones, generated-fresh passes, bom drift is clean across
101 files, and AGENTS.md itself is unchanged in this commit.
2026-11-16 19:38:27 +08:00
..

test/host/common/ — 主机侧测试公共库

主机侧纯逻辑单测的通用 harness:被各模块的单测运行器共享, 集中承载工具链探测与编译/运行/判定的公共细节。

文件一览

文件 作用
unit_test_harness.py 通用单测 harness(纯标准库):探测本机 MSVC → 拼 INCLUDE/LIB → 编译测试单元 → 运行 → 判定退出码

为什么要有这层(2026-10-01 抽取)

看门狗单测最早的运行器(test/host/watchdog/run_unit_test.py)把工具链探测、 INCLUDE/LIB 拼接、GBK 解码、/wd4819 抑制、退出码契约全写死在模块目录内。 第二个主机侧纯逻辑单测出现时须整段复制——工具链细节一旦修正(新增 VS 版本、SDK 布局 变化、编码处理调整)就会发散。抽取后各模块运行器只剩"声明式"配置。

边界:harness 不认识任何模块——源码路径、桩目录、额外 include、断言 汇总行特征全部由调用方传入。新单测只写一个 TestBuild(...) + 一行 sys.exit(...)。

用法(模块侧 run_unit_test.py 模板)

import os, sys
HERE = os.path.dirname(os.path.abspath(__file__))
ROOT = os.path.dirname(os.path.dirname(os.path.dirname(HERE)))
sys.path.insert(0, os.path.join(ROOT, "test", "host", "common"))

from unit_test_harness import TestBuild, run_host_unit_test

BUILD = TestBuild(
    name="<模块名> Tests",                       # 人类可读名(打印用)
    src=os.path.join(HERE, "<模块>_test.c"),     # 测试单元(内部 #include 生产源)
    include_dirs=[                               # 顺序敏感:桩目录必须在生产目录之前
        os.path.join(HERE, "stub"),
        os.path.join(ROOT, "App", "util"),
        HERE,
    ],
    summary_marker="=== <模块名> Tests:",          # 运行输出中必须出现的汇总行前缀
)

if __name__ == "__main__":
    sys.exit(run_host_unit_test(BUILD))

另一写法(不落 run_unit_test.py,直接内联):

from unit_test_harness import TestBuild, run_host_unit_test
raise SystemExit(run_host_unit_test(TestBuild(name="...", src="...", ...)))

退出码契约(各模块运行器统一遵循)

码 含义
0 PASS——编译 + 运行成功,且日志含 summary_marker
1 FAIL——有测试用例未通过
2 环境错误——找不到编译器 / 编译失败 / 未产生汇总行

TestBuild 字段

字段 必填 说明
name ✓ 打印用名称;同时用于派生 exe 名与 obj 目录名
src ✓ 测试单元 .c 的绝对路径(内部 #include 生产源,保证测的是真代码)
include_dirs /I 目录列表;桩目录需排在前面才能覆盖真实头
summary_marker 运行输出中必须出现的汇总行前缀;空 = 不校验
extra_flags 追加的 cl.exe 开关
exe_name / obj_tag 覆盖派生的产物名 / 中间目录名(默认由 name 派生;落点见下节"产物目录归属")

环境要求

同主机侧纯逻辑单测通用要求(见 ../../../docs/测试说明/流程与规范/测试开发标准流程.md §4.2): MSVC cl.exe(装了 VS 即有)+ Windows SDK + 纯标准库 Python;不调 vcvars64.bat (内部 reg.exe 受限),直接拼环境变量调 cl.exe。

产物目录归属(跨工作树并行,2026-10-25)

obj / exe / pdb 每次运行独占一个子目录,按工作树分家:

%TEMP%\dtu_host\<仓库根路径 sha1 前 10 位>\runs\<pid>-<纳秒时间戳>\
    <suite>_obj\*.obj        ← 中间目标文件
    <suite>_tests.exe        ← 本次编译产物(跑完随目录一起删)
    <suite>_tests.exe.owner.json  ← 归属凭据:suite / repo_root / pid / started

为什么这么放(两条都是实测出来的,不是洁癖):

  • 旧写法把 obj/exe 摊在全机共用的 %TEMP%,名字由套件名派生( %TEMP%\net_socket_tests.exe)。多棵工作树并行跑同名套件就会互相覆盖,而最坏情况 不是编不过:A 树编译完,B 树把同名 exe 又盖一遍,A 树随后执行的是 B 树编出来的 二进制——两棵树的 summary_marker 一模一样,harness 分辨不出来,等于拿别人的 运行结果给自己下结论。2026-10-25 三条道并行时全量 ci_local 里 test-cppcheck / test-coverage 偶发 "files were modified by this hook"、单跑即绿,就是这一类。
  • 按工作树分家 + 每次跑独占同时解决"跨树互踩"和"同树并发"(覆盖率钩子与手工主机侧纯逻辑单测 同时跑同一棵树时也会撞)。不牺牲任何东西:每个测试单元就一个 .c,cl 每次整体 重编,"共享 obj 省编译"本来就是错觉。没有加锁——这里没有需要互斥的独占资源, 只是名字撞了;加锁等于把主机侧纯逻辑单测变成和 build/bench 一样的全局串行。

两个开关(都写在 harness 顶部注释里,判据以 unit_test_harness.host_build_root() 为准):

  • DTU_HOST_BUILD=<目录>:改产物根(CI/容器要固定路径时用)。覆盖率侧同源—— scripts/check_test_coverage.py 复用同一个函数,不再用自己那套固定名 (旧 %TEMP%\dtu_test_cov 的共享名,正是 docs/测试说明/单元测试/主机单测覆盖率口径.md 里 "并行期每人只跑 --module 自己模块"那条规避的由来;分家之后该规避不再必要)。
  • DTU_HOST_BUILD_KEEP=1:保留本次独占目录不删(要单步调试那个 exe 时用,会打印路径)。

想知道当前树算到哪个目录:

& '.venv\Scripts\python.exe' -c "import sys;sys.path.insert(0,'test/host/common');import unit_test_harness as U;print(U.host_build_root())"

⚠️ 注意

  • 本目录在 pre-commit 的 cppcheck / 代码规范排除范围(test/ 豁免)
  • 改动本 harness 会触发 watchdog-unit-test 钩子(files 正则已含本文件)