# 通用 ar 库的范围与验收

MoonAr 实现通用 Unix ar 库的完整归档生命周期：读取、成员访问、thin 引用处理、创建、
编辑、格式转换与符号索引维护，并提供可接入构建流程的命令行。主要兼容 GNU、BSD、Darwin 和 Microsoft COFF；
比较能力用于检查构建复现和编辑结果。

0.7.2 的范围以以下矩阵为准。各功能均有实现和可运行验收入口。

## 功能与验收矩阵

| 能力 | 0.7.2 交付内容 | 验收标准与入口 |
| --- | --- | --- |
| 读取 | GNU/BSD/Darwin，长名称、重名、原始名称字节、元数据和成员数据 | GNU/LLVM 列表及提取字节一致；截断和错误引用定位诊断；`verify_archives.py` |
| thin | 直接文件与嵌套 archive-offset 引用、加载、创建、编辑、重定位、物化，GNU32/64 索引 | 参考工具互读；路径越界、丢失、尺寸改变有明确结果；`verify_cli.py`、`verify_io.py` |
| 创建 | GNU32/64、BSD32/64、Darwin32/64、COFF 双索引，确定性与保留元数据 | 参考工具读取和提取；重复写出稳定；对齐、字段宽度、预算回归 |
| 编辑 | 追加、插入、替换、删除、移动、重命名；普通成员零基定位 | 独立修改同名项；编辑后索引指向最终对象；完整 CLI 操作链 |
| 自动索引 | ELF32/64、Mach-O32/64、COFF、bigobj、短导入对象、LLVM bitcode 版本 3 摘要；七种布局 | 对照对象符号；创建、替换、删除、移动后链接；`verify_cli.py`、`verify_lto.py` |
| 转换与比较 | 方言转换、thin 物化、普通/thin 直接逻辑比较和不可变快照 | 数据及符号映射符合布局约定；重名歧义单独报告；单元与参考验证 |
| 文件操作 | 原子发布、禁止意外覆盖、真实路径检查、JSON 和退出码 | 失败保持原文件；并发新建只成功一次；别名覆盖与目录联接回归；`verify_io.py` |
| 实际消费者 | zlib 1.3.1 普通及 thin 静态库 | 固定源码摘要、编译、创建、压缩/解压运行、替换对象后再次链接运行；`verify_zlib.py` |
| macOS 本机消费者 | Apple Silicon 上 BSD32/64、Darwin32/64 编辑、直接及嵌套 thin 物化 | Apple 工具核对，16 个消费者实际执行；`verify_macos.py` |
| 性能基准 | 39 组普通/唯一名称/重名/嵌套 thin 场景，最大 10000 成员、深度 16 | 语义与缓存检查、时间样本、峰值驻留内存和单位探针；`benchmark.py` |

脚本位于 `tools/`，调用命令见 [复现指南](REVIEW.md)。核心库测试运行于 native、JavaScript、
wasm、wasm-gc；文件 CLI 提供 native 和 Node.js 实现。

## 交付阶段

| 版本/阶段 | 成果 | 完成门槛 |
| --- | --- | --- |
| 0.2.0 读取与比较 | 多方言解析、索引校验、逻辑比较、查询 CLI | 四后端、双系统 CI、GNU/LLVM 对照、独立包消费者 |
| 0.3.0 基础读写 | thin 独立类型、普通与 thin Builder、不可变成员编辑 | 外部成员与内嵌表区分；输出由独立归档工具消费 |
| 0.3.0 索引与文件命令 | 三类对象发现、六种布局、完整编辑命令、原子文件发布 | 真实对象编辑后链接运行；覆盖及路径失败回归 |
| 0.3.0 应用集成 | thin 重定位与物化、zlib 构建运行、文档与发布包 | 可重复执行的消费者脚本；发布包公共 API 安装验证 |
| 0.4.0 thin 内容查询 | 外部成员校验、不可变快照、直接混合存储比较 | 容器相同仍能识别外部内容变化；原始成员位置和符号映射保留；缺失、越界与预算回归 |
| 0.5.0 嵌套 thin | archive-offset 读写、归档输入展开、缓存、传递依赖保护与有界递归 | GNU 生成与消费、精确成员寻址、循环和累计预算回归、编辑后链接运行 |
| 0.5.0 Windows 静态与导入库 | COFF 双表、bigobj、短导入对象与完整编辑 | MSVC lib/dumpbin 读取；静态与 DLL 消费者实际链接运行；`verify_windows.py` |
| 0.6.0 LLVM LTO | 原始和包装 bitcode、版本 3 摘要、模块组、共享发现预算 | LLVM 对照；full/ThinLTO 编辑、thin 物化与混合对象实际链接运行；GCC slim 拒绝与 fat 原生回退 |
| 0.6.1 路径与发行维护 | Windows 根目录及盘符相对路径、POSIX 字面反斜杠、版本与分发元数据检查 | native/Node 真实文件操作与公开 CLI 消费者；许可证和使用文档随包提供 |
| 0.6.2 健壮性维护 | 公开 CLI 请求预检、BSD 字节序与预算判断、长输出名称原子写入 | 非法请求零文件回调、双端序预算回归、native/Node 长路径操作与 MoonCakes 安装消费者 |
| 0.6.3 安装验证维护 | 注册表依赖下载顺序、已有发行 ZIP 核对入口 | 实际安装并执行四后端消费者，99 个发行文件逐一匹配 |
| 0.7.0 macOS 与性能 | Apple 本机消费者、Node 大小写路径保护、三平台性能报告 | 四后端及包消费者通过；实际执行 16 个 macOS 消费者；36 组基准检查结果与内存单位 |
| 0.7.1 比较与预算 | 原始字节分组、唯一名称配对优化、精确嵌套路径预算 | 非 UTF-8 与记录类型隔离回归、重复路径与新路径预算边界、39 组性能场景 |
| 0.7.2 工具链维护 | MoonBit 0.10.16 编译器与 core、最低版本及固定构建检查 | 三平台四后端测试、公开包消费者和工具链报告；`verify_toolchain.py` |

后续兼容扩展以具体格式样本及独立消费者为准。GCC slim 插件、旧 bitcode IR 重建和大文件流式处理不计入当前支持矩阵。
大文件处理需验证分块输入、64 位偏移及中断恢复，不能仅扩大当前整数上限。

对象指令/ABI 分析、链接器、压缩 tar 和包管理器不属于本库交付范围。

## 设计与验收原则

普通归档与 thin 使用独立类型，避免将外部声明大小当成容器切片。加载不隐式发生，
调用方可以控制根目录、路径策略和累计预算。

编辑针对普通成员序列，保留重名项；名称表、头部偏移和索引由最终序列重新计算。
自动索引从编辑完成后的对象发现定义，避免继续使用被替换或删除对象的旧映射。

兼容性同时检查“参考工具生成、MoonAr 读取”和“MoonAr 写出、参考工具消费”。
静态库还需经真实对象符号核对、链接和程序运行；异常路径独立验证原文件保留。
Mach-O 的跨平台链接验证与本机程序运行在结果中分别报告。

- [GNU ar 文档](https://sourceware.org/binutils/docs/binutils/ar.html)
- [LLVM ar 文档](https://llvm.org/docs/CommandGuide/llvm-ar.html)
- [读写接口](WRITING.md)、[开发说明](DEVELOPMENT.md)