erofs-freebsd-out-tree/docs/refactoring-plan.md

repo22 Linux/FreeBSD 结构对齐维护计划

基线

• FreeBSD 实现：src/
• Linux 参考：/work/dev-src-linux/fs/erofs（Linux 7.1-rc1 快照）
• 比较方法：逐文件和逐职责比较，不依赖共同 Git 历史
• 运行目标：FreeBSD 15 amd64

决策规则

1. 先判断差异是否来自 FreeBSD vnode、GEOM、errno、锁或内核库接口。
2. 只对非必要差异调整静态函数名、变量名、定义顺序和文件职责。
3. 不为匹配 Linux 文件表而添加空模块或不适用的抽象。
4. src/Makefile 是模块名、源码清单、架构门控和编译选项的权威来源。
5. 构建产物、生成头和机器 include symlink 不进入版本控制。

本轮清单

• 清除受跟踪的 build/obj 生成头和机器 symlink
• 精确忽略模块构建及手工测试生成目录
• 由原生 bsd.kmod.mk 取代手写 amd64 clang/link 流程
• 明确拒绝未验证的非 amd64 架构
• 将 ZSTDIO 配置统一为 WITH_ZSTDIO=0/1
• 按 Linux 顺序整理 Makefile 源码列表
• 对齐 find_target_dirent 和 decompressor_*.c 名称
• 将跨文件解压后端声明集中到 internal.h
• 保留 BSD 专属 erofs_vnops.c、lz4.c 和后端调用契约
• 在 FreeBSD 15 VM 完成双配置构建和 ZSTD 挂载 smoke

验证门槛

1. WITH_ZSTDIO=0 与 WITH_ZSTDIO=1 均从空对象目录构建。
2. 禁用产物不含 ZSTD_* 未解析符号，启用产物必须含预期内核 API。
3. 启用产物完成加载、ZSTD 镜像挂载、文件读取、卸载和 KLD 清理。
4. 非 amd64 和非法 WITH_ZSTDIO 值必须明确失败。
5. 提交只包含 repo22 pathspec，且远端 xdm/main 与本地 HEAD 一致。