Physlib开发者进阶:缓存优化、TODO系统与网站生成脚本工作原理

原创2026-10-26 21:00:521,432 阅读

Physlib开发者进阶:缓存优化、TODO系统与网站生成脚本工作原理

Physlib 是一个将物理结果数字化并形式化进 Lean 证明助手的开源项目。本文带你快速理解它的三大基础设施:构建缓存优化(lake cache + R2 桶)、TODO 任务系统与网站生成脚本,帮助贡献者跳过漫长的编译等待、高效追踪开发任务,并看懂 physlib.io 上每个数据页背后的自动化原理。

Physlib项目模块分布树状图,展示缓存优化与网站脚本所统计的模块结构

为什么需要构建缓存优化?🚀

一个动辄数十万行的 Lean 库,从零编译可能需要数小时。Physlib 的解决方案是把预编译产物(artifacts)发布到远端,让贡献者直接下载,而不是重新编译。

一键拉取:lake exe get_cache

核心入口是 scripts/dev/get_cache.lean,它做了三件事:

  1. 拉取 Mathlib 的预编译文件(调用 lake exe cache get);
  2. 拉取 Physlib 自己的缓存,缓存作用域为 physlib-master/<toolchain>/physlib;
  3. 单独拉取 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,网站数据生成脚本本身也是被测试的代码。

给贡献者的实践建议 💡

  1. 首次构建前先跑 lake exe get_cache,可把等待时间从数小时缩短到几分钟;
  2. 写新任务时用 TODO "..." 命令而不是普通注释,让它进入环境扩展、被统计进网站进度条;
  3. 修改 scripts/website/ 后,本地跑一遍 lake exe auxillary_script_test 确认产出无回归;
  4. 想了解各物理分支的代码规模,直接看 scripts/website/treemap_gen.py 生成的树状图,面积即文件大小、颜色即分支归属。

掌握这套"缓存 + TODO + 网站"基建后,你就不只是 Physlib 的使用者,而是能维护它生长节奏的开发者。🔭

登录后查看全文
physlib