STM32F4-Base/docs/环境与部署/本地工具路径环境变量方案.md

本地工具路径环境变量方案

本文档描述项目的本机工具路径环境变量机制：变量清单、解析与失败语义、各级配置方法、验收判据 （2026-10-02 实施并生效；实施过程与后续变更见文末变更记录）。 约束（现行）：只用进程/用户/CI 服务环境变量配置本机差异；不提交本机路径，不引入 .env/python-dotenv， 不把个人工具路径写入共享 workflow；仓库内部路径继续相对脚本/仓库根解析。

1. 变量清单

变量	必需性	值的形态	使用者	默认/回退
DTU_KEIL_UV4	MCU 构建机必需	UV4.exe 完整路径，例如 D:\Tools\Keil\UV4\UV4.exe	keil_build.py（@build）	不设即报错（exit 2）；不从 C 盘旧路径猜测
DTU_STLINK_CLI	复位/烧录/回读机必需	ST-LINK_CLI.exe 完整路径，例如 C:\Program Files (x86)\STMicroelectronics\STM32 ST-LINK Utility\ST-LINK Utility\ST-LINK_CLI.exe	stlink_flash.py	未设时回退 PATH（where ST-LINK_CLI.exe 首个命中）；已设但无效 = 硬报错
DTU_PRECOMMIT_PYTHON	可选（覆盖用）	含 pre_commit 模块的 python.exe 完整路径	ci_local.py L0、CI l0-gates	未设时按 §1.1 探测（当前解释器 → .venv → PATH）；已设但无效 = 硬报错
DTU_GRAPHVIZ_DOT	可选（覆盖用）	dot.exe 完整路径	gen_refgraph.py	未设时只查 PATH；无 Graphviz 时降级为"生成 .dot/.json、跳过渲染"
DTU_MSVC_CL	可选（覆盖用）	x64 cl.exe 完整路径（bin\Hostx64\x64 下）	unit_test_harness.py L0.5、CI l05	未设时按 VS 安装根自动探测（2019/2022/2026 各 edition）；已设但不符 bin\Hostx64\x64\cl.exe = 硬报错
DTU_WINDOWS_KITS_ROOT	可选（覆盖用）	Windows Kits\10 根目录（须含 Include/Lib）	unit_test_harness.py L0.5、CI l05	未设时从 %ProgramFiles*% 推导根自动探测；已设但无 Include/Lib = 硬报错
DTU_VSWHERE	可选（覆盖用）	vswhere.exe 完整路径	build_sim.ps1	未设时用 %ProgramFiles(x86)%\Microsoft Visual Studio\Installer\vswhere.exe 推导；已设但无效 = 硬报错
DTU_CPPCHECK	可选（覆盖用）	cppcheck.exe 完整路径	CI l0-gates cppcheck 步骤	未设时用 PATH（Get-Command）；已设但无效 = 硬报错。本地 ci_local.py L0 不读该变量：cppcheck 钩子按 pre-commit entry: cppcheck 从 PATH 解析

变量值只存路径本身（不加引号）；可执行文件变量存 .exe 完整路径，目录变量（Kits 根）存目录。 不设任何变量时全部走自动发现（PATH / 系统目录推导 / .venv / vswhere）；变量只用于覆盖非标准安装位置。 字体系统目录（simsun.ttc）不设 DTU 变量：由 %WINDIR%\Fonts\ 推导，make_font.py 的 --font 参数仍最高优先。

1.1 Python 优先级特别说明（ci_local.py / CI L0）

pre-commit 是门禁的执行环境而非"工具地址"，优先级与其余工具不同：

1. 显式 DTU_PRECOMMIT_PYTHON（若设置，必须可执行且能 import pre_commit，否则报错）；
2. 当前解释器（sys.executable，即实际运行 ci_local.py 的 Python）；
3. 仓库 .venv\Scripts\python.exe（若存在且装了 pre-commit）；
4. PATH 中的 python。

CI 侧同理：DTU_PRECOMMIT_PYTHON → runner PATH → workspace .venv。

2. 解析与失败语义（所有调用端统一）

1. 显式值校验：变量已设置时，先校验其指向的文件/目录真实存在且符合形态（如 cl.exe 必须位于 bin\Hostx64\x64\ 下）；无效则立即报错，错误信息必须包含变量名与所给值，不得静默回退到自动发现。
2. 未设置才自动发现：PATH / 系统目录推导 / .venv / vswhere 等；自动发现失败按各工具既有降级或报错语义处理。
3. BAT 实现约束：.bat 中读取环境变量用 %DTU_...%；判空用 if defined；错误分支 exit /b 非零。BAT 内解析一律平铺 goto 标签风格，不用括号块（echo ) 会提前闭合块）。
4. PowerShell 实现约束：$env:DTU_...；build_sim.ps1 的 CMake 配置不直接读环境变量（保持生成器无关）。
5. workflow run 块：ci.yml 的 run 块内用 ${env:DTU_...}（未设置时为空串）与 PowerShell $env:DTU_... 判空，不得在 workflow 文件里写死任何本机绝对路径。
6. Windows 命令行引号规则：值含空格（如 C:\Program Files (x86)\...）时，调用端必须整体加引号（"%DTU_KEIL_UV4%" / "& $env:DTU_..."）；变量值本身不要带引号。
7. 系统变量推导：%WINDIR%、%ProgramFiles%、%ProgramFiles(x86)% 仅用于推导（如 make_font.py 的 simsun.ttc、build_sim.ps1 的 vswhere 路径），不得作为"工具安装目录"的硬编码兜底。

3. 本机配置方法

3.1 当前 PowerShell 会话（立即生效，适合试配置）

# 仅当前会话有效；换终端/重启即失效
$env:DTU_KEIL_UV4   = 'D:\Tools\Keil\UV4\UV4.exe'
$env:DTU_STLINK_CLI = 'D:\Tools\ST-LINK Utility\ST-LINK_CLI.exe'
# 验证：Test-Path $env:DTU_KEIL_UV4   → True

3.2 用户级持久配置（日常开发机，推荐）

# 当前用户、全部新进程可见；无需管理员
[Environment]::SetEnvironmentVariable('DTU_KEIL_UV4',   'D:\Tools\Keil\UV4\UV4.exe', 'User')
[Environment]::SetEnvironmentVariable('DTU_STLINK_CLI', 'D:\Tools\ST-LINK Utility\ST-LINK_CLI.exe', 'User')
# 已存在同名值时直接覆盖；删除用 [Environment]::SetEnvironmentVariable('DTU_KEIL_UV4', $null, 'User')
# 设置后需重开终端/IDE 才对新进程生效

3.3 Gitea Windows runner（SYSTEM 服务）

# 必须管理员；写入机器级（Machine）环境，供 Gitea runner 服务（SYSTEM 账户）读取
[Environment]::SetEnvironmentVariable('DTU_PRECOMMIT_PYTHON', 'C:\ProgramData\anaconda3\python.exe', 'Machine')
[Environment]::SetEnvironmentVariable('DTU_CPPCHECK', 'C:\Program Files\Cppcheck\cppcheck.exe', 'Machine')
# 写入后需重启 Gitea runner 服务/任务才能带上新变量（服务启动时读取环境变量快照）

注意：runner 以 SYSTEM 运行，用户级变量对 runner 不可见；反之机器级变量对交互用户可见但不应依赖。开发机日常配置用 User 级，runner 专用覆盖用 Machine 级。 值示例中的 C:\ProgramData\anaconda3\... 仅演示"显式覆盖"形态；若 runner 的 PATH/.venv 可自动发现，则不必设置该变量。

4. 验收判据

• 新电脑只配置本机 DTU_* 环境变量（§3），clone 仓库后可直接运行各开发命令，不修改任何脚本/工作流中的本机路径。
• 显式变量指向无效路径时，命令以非零退出码失败且错误信息指明变量名，不静默使用其他工具。
• 仓库内不出现提交的本机绝对工具路径（文档中的示例路径除外）。
• 跨机验证操作清单见 项目部署环境要求.md §2.12；runner 侧机器级变量设置见 docs/CI/远程CI完整指南.md §4.1.3。

---

变更记录

日期	变更
2026-10-02	文档改造：删除规划阶段内容（设计结论、路径耦合盘点、代码改造映射、分阶段推广与验收、风险与边界、后续任务拆分），保留并重组为现行机制说明——§1 变量清单（含 Python 优先级特别说明）、§2 解析与失败语义、§3 本机配置方法（会话/用户/runner 三级）、§4 验收判据、变更记录；章节重编号，外部引用同步（gen_refgraph.py §3→§1、ci_local.py §3.1→§1.1、Gitea_Runner部署指南.md §5.3→§3.3）
2026-10-02	实施完成：阶段 A~D 落地。① 10 处调用点全部改为"DTU_* 变量优先 + 自动发现回退"（显式值无效 = 硬报错、不静默回退）：build/download/reset.bat（goto 标签式解析，纯 ASCII）、ci_local.py（DTU_PRECOMMIT_PYTHON 严格校验）、ci.yml（DTU_PRECOMMIT_PYTHON/DTU_CPPCHECK/DTU_MSVC_CL/DTU_WINDOWS_KITS_ROOT，run 块纯 ASCII）、gen_refgraph.py（DTU_GRAPHVIZ_DOT→PATH，保留无渲染降级）、unit_test_harness.py（DTU_MSVC_CL/DTU_WINDOWS_KITS_ROOT + %ProgramFiles*% 推导取代静态盘符列表）、build_sim.ps1（DTU_VSWHERE→%ProgramFiles(x86)% 推导，去字面 C 盘回退）、make_font.py（%WINDIR% 推导）；_build.cmd 确认零调用后删除。② 本机按 §3.2 配置用户级 DTU_KEIL_UV4/DTU_STLINK_CLI（其余工具本机均可自动发现，未设变量），验证：@build BUILD_OK 0/0、ci_local.py L0 15 钩子 + L0.5 278/278 断言全绿、refgraph 重生成（含修复 引用关系图.json 末尾换行缺失导致的 end-of-file-fixer 抖动，生成器补 f.write("\n")）、build_sim.ps1 vswhere 推导命中 VS2026（当时模拟器 CMake 配置期暴露既有问题：App/cfg_file.c 已移入 App/cfg/ 但 simulator/CMakeLists.txt 未同步——与环境变量改造无关；2026-10-02 已修复：CMakeLists 同步 App/cfg/ + test/board/ 引用，模拟器全量构建通过）、reset.bat list 识别探针。③ 文档收口：AGENTS.md/MDK-ARM/README.md/项目部署环境要求.md（新增 §2.1.1）/Gitea_Runner部署指南.md（新增 §5.1.3 机器级变量）/CI配置指南.md/pre-commit使用说明.md/字体/测试流程/引用图说明/ST-LINK 说明/实机规划/scripts/README.md 共 12 篇同步为变量口径。④ requirements.txt 增 pre-commit==4.6.2（重建 .venv 即可跑 L0）。⑤ 全量 pre-commit --all-files + ci_local.py 通过。待办：新 workflow 推送远程后跑一次 CI 两 job 闭环验证；第二台不同安装路径机器的交叉验证（操作清单已固化入 项目部署环境要求.md §2.12）
2026-10-02	初版规划：盘点 BAT/Python/PowerShell/Gitea workflow 中机器相关工具路径；定义 DTU_* 变量清单、优先级、用户级与 SYSTEM runner 配置边界；规划 4 阶段迁移及离线/实机验收范围。未改工具调用代码