# tools/menu_gen/ — 菜单代码生成 > 从**菜单树定义**生成 UI 菜单的 C 代码,保证菜单结构与页面注册一致、避免手写遗漏。 ## 脚本一览 | 脚本 | 作用 | |---|---| | `gen_menu.py` | 读取菜单树定义(见 `ui_menu_tree.txt`)→ 生成菜单代码 | ## 使用方式 两种模式,**写不写盘是唯一区别**;两者的生成/注册逻辑共用同一段代码(`plan_prune` + `plan_sync` 只算不写,写盘模式再落盘),所以"检查说的"与"写入做的"不可能漂移。 ### 写入模式(默认,不带参数) ```bash & '.venv\Scripts\python.exe' tools/menu_gen/gen_menu.py ``` 重写 4 个生成物(`ui_menu_tab.c/.h`、`ui_page_registry.c/.h`)+ 同步双端注册 (`MDK-ARM/STM32F407-Demo.uvprojx`、`simulator/CMakeLists.txt`)。 输出里的箭头行(`-> Drivers/BSP/UI/ui_menu_tab.h` 等)**表示文件确实被重写了**—— 注意重写不代表内容变了:内容相同时字节不变、`git status` 也就没有 diff。 **什么时候用**:改了 `ui_menu_tree.txt` 或增删页面实例后,这是唯一会刷新生成物的途径。 ### 只读模式(`--check`) ```bash & '.venv\Scripts\python.exe' tools/menu_gen/gen_menu.py --check ``` 只报告"工作区生成物是否已与 `ui_menu_tree.txt` 同步",**一次写操作都不发生**, 也不建临时文件;双端注册同样只比对不写入。退出码即结论: | 情形 | 输出 | 退出码 | |---|---|---| | 已同步 | `[OK] up-to-date: 4 个生成物与双端注册均与 ui_menu_tree.txt 一致` | 0 | | 有漂移 | 每个待刷新文件一行 `[STALE] would rewrite <路径> (原因)`,末行给总数 | 1 | `[STALE]` 行**刻意不使用箭头符号**——那个符号在只读场景里会被误读成"已经写过了"。 差异摘要会给出首个不同的行号,或"需删 N 条死引用 / 需补 N 条注册",便于直接定位。 **什么时候用**:改完菜单树、提交前想确认"我这笔改动是否已经重跑过生成器", 或 review 别人的菜单改动时。它不替代强制门禁——见下节。 ## 与 `check_generated_fresh.py` 的分工 `scripts/check_generated_fresh.py`(pre-commit 钩子「生成器幂等性」)把生成器拷到临时目录 重跑再逐字节比对,是**强制的红绿门禁**,保证"生成物比生成器旧"必 FAIL。 `--check` 是**给人看差异的**:门禁只说红或绿,`--check` 说差在哪个文件、第几行、缺哪条注册。 日常改菜单用 `--check` 自查,提交时由门禁兜底,两者都要在。 菜单树输入的权威副本:仓库根 `ui_menu_tree.txt`。 ## ⚠️ 注意 - 生成产物**勿手改**(会被下次生成覆盖);要改菜单结构改**定义源**后重跑 - 中文字符串字面量须为**纯 ASCII 安全**(见 `docs/文档规范.md` §2 编码铁律)——生成后的文案 如需汉字,须配套重跑字体生成(`tools/font_gen/`) ## 相关文档 - `docs/UI设计/菜单页面设计.md` - `docs/UI设计/内容页架构.md`