e4981aa2f6
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.
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正则已含本文件)