Physlib开发者进阶:缓存优化、TODO系统与网站生成脚本工作原理
Physlib开发者进阶:缓存优化、TODO系统与网站生成脚本工作原理
Physlib 是一个将物理结果数字化并形式化进 Lean 证明助手的开源项目。本文带你快速理解它的三大基础设施:构建缓存优化(lake cache + R2 桶)、TODO 任务系统与网站生成脚本,帮助贡献者跳过漫长的编译等待、高效追踪开发任务,并看懂 physlib.io 上每个数据页背后的自动化原理。
为什么需要构建缓存优化?🚀
一个动辄数十万行的 Lean 库,从零编译可能需要数小时。Physlib 的解决方案是把预编译产物(artifacts)发布到远端,让贡献者直接下载,而不是重新编译。
一键拉取:lake exe get_cache
核心入口是 scripts/dev/get_cache.lean,它做了三件事:
- 拉取 Mathlib 的预编译文件(调用
lake exe cache get); - 拉取 Physlib 自己的缓存,缓存作用域为
physlib-master/<toolchain>/physlib; - 单独拉取 PhyslibAlpha 的缓存,作用域为
.../alpha,两个作用域互不覆盖。
它还内置了两个精巧的细节:
isStaleOlean:通过检查.olean文件头部的 Lean githash,识别出由旧 toolchain 编译的陈旧产物;removeStaleDepBuilds:在 toolchain 升级后自动清理失效的依赖构建目录,避免 Windows 上只读硬链接卡住解压。
拉取失败也不是致命错误——程序会继续运行,只是 lake build 会退化为从源码编译(更慢)。
读写分离的 R2 桶配置 📦
缓存桶的配置在 lake-cache.toml,遵循"读写分离"原则:
| 服务名 | 用途 | 凭证要求 |
|---|---|---|
physlib-r2 |
匿名公共读端点,贡献者下载缓存 | 无 |
physlib-r2-upload |
认证写端点,仅 CI 发布使用 | LAKE_CACHE_KEY |
桶选用 Cloudflare R2,因为小体量存储、高并发下载且出口流量免费。完整的建桶步骤(创建桶、API token、GitHub secret、域名部署与验证命令)记录在 docs/cache-setup.md,验证只需两条命令:
lake exe get_cache
lake build
相关开关在 lakefile.toml 中:enableArtifactCache = true 与 restoreAllArtifacts = true 让 lake cache 在 CI 发布和本地构建时都能正常工作。
TODO 系统:如何追踪一个库的"未完成事项"?📋
Physlib 把待办任务当作一等公民。它有两套互补的机制:
1. TODO 命令与环境扩展
Physlib/Meta/TODO/Basic.lean 定义了一条 Lean 命令 TODO "内容"。编译时,elaborator 会记录 todoInfo 结构体(内容、文件、行号、标签),存入名为 todoExtension 的环境扩展中——这意味着 TODO 随编译产物一起被持久化,后续脚本可直接读取。
tag取自内容字符串的哈希,保证每个任务标签唯一;lint_all的第 4 步会检查不存在重复标签;- 全局性任务集中在 Physlib/Meta/TODO/Global.lean,例如"移除所有
erw用法"这类跨模块目标。
2. 生成唯一任务标签:make_tag
scripts/website/make_tag.lean 用当前时间戳做 Base32 编码生成短标签(去掉前两位),为 informal 引理、半形式化结果等提供可引用的稳定标识。
3. 导出到 YAML:TODO_to_yml
scripts/website/TODO_to_yml.lean 是网站 TODO 列表页的数据源。它一次性收集三类"未完成":
TODO ...命令条目;- informal 定义与引理(用
informal_definition/informal_lemma声明,表示"已陈述但未形式化"); - 半形式化结果。
每条记录按物理分支归入 PhyslibCategory(Classical Mechanics、QFT、Quantum Mechanics 等,各配一个 emoji),生成 docs/_data/TODO.yml 供网站渲染。该脚本同时导入 Physlib、QuantumInfo、PhyslibAlpha 三个库,因此还能顺带发现跨库的命名冲突。
4. 纯文本版扫描器:find_TODOs
scripts/dev/find_TODOs.lean 不依赖构建,直接扫描源码中的 /-! TODO: 注释块,输出 文件:行号: 内容 格式并生成带行号链接的 Markdown 列表(docs/TODOList.md)。两套机制一个走编译元数据、一个走文本解析,互为备份。
网站生成脚本:数据如何变成网页?🌐
scripts/website/ 目录下的脚本全部通过 lake exe 运行,产出物统一落在 docs/ 下:
| 脚本 | 运行命令 | 产出 |
|---|---|---|
| stats.lean | lake exe stats mkHTML |
Stats.html:文件数、行数、定义/引理数、doc-string 覆盖率进度条、TODO 进度条 |
| informal.lean | lake exe informal mkFile mkDot mkHTML |
informal 引理清单、Graphviz 依赖图(.dot)与可交互 HTML 图 |
| notes.lean | lake exe notes |
精选笔记(Wick 定理、量子谐振子、Higgs 势、张量)的 YAML,每个声明附带"已完成/未完成"状态 |
| make_tag.lean | lake exe make_tag |
唯一任务标签 |
| treemap_gen.py | python treemap_gen.py |
按物理分支着色的模块树状图(即文首的 treemap) |
| Template.lean | — | 生成模板 |
统计脚本的底层能力
stats.lean 依赖 Physlib/Meta/Basic.lean 中一组通用元编程工具:noDefs、noLemmas、noTODOs、noImports、noLines 等。它们遍历所有 .olean 模块数据与源码,回答"共多少定义、多少缺 doc-string、多少文件还有 TODO"这类问题——这正是 Stats.html 上进度条的数字来源。
CI 如何保证脚本不出错?
lake exe auxillary_script_test(定义见 lakefile.toml 与 scripts/README.md)会在每次 PR 上实际运行 make_tag、TODO_to_yml mkFile、stats mkHTML、informal mkFile mkDot mkHTML,网站数据生成脚本本身也是被测试的代码。
给贡献者的实践建议 💡
- 首次构建前先跑
lake exe get_cache,可把等待时间从数小时缩短到几分钟; - 写新任务时用
TODO "..."命令而不是普通注释,让它进入环境扩展、被统计进网站进度条; - 修改
scripts/website/后,本地跑一遍lake exe auxillary_script_test确认产出无回归; - 想了解各物理分支的代码规模,直接看 scripts/website/treemap_gen.py 生成的树状图,面积即文件大小、颜色即分支归属。
掌握这套"缓存 + TODO + 网站"基建后,你就不只是 Physlib 的使用者,而是能维护它生长节奏的开发者。🔭
