bup 0.28.1 版本解析：归档构建修复、OS X 测试兼容与 bup-python umask 权限

• 灾备
• CLI
• 存储

bup 是一个基于 git packfile 格式的高效备份系统，提供快速增量保存与全局去重能力。0.28.1 是其 0.28 系列的第一个补丁版本，重点修复了三类问题：从git archive生成的发布归档解压后能否正常构建、test-web 与 test-meta 在较新 OS X 及 Homebrew rsync 环境下的兼容性，以及cmd/bup-python文件权限是否正确遵循 umask。本文以 note/0.28.1-from-0.28.md 为主干，结合仓库内 GNUmakefile、lib/cmd/bup.c、lib/bup/io.py 等源码，逐条还原这三个修复的实现机制与验证方式，帮助读者理解 bup 发布流程、构建系统与权限处理细节。

版本背景：0.28 引入的变化与 0.28.1 的定位

0.28 是一个功能密集的版本。根据 note/0.28-from-0.27.1.md，它在上一版本基础上引入了多项结构性改动：

• 默认安装前缀改为/usr/local，BINDIR/DOCDIR/LIBDIR/MANDIR不再绕过DESTDIR；
• 索引（index）格式变更，下一次索引运行会触发全量重建；
• 新增实验性的rm与gc子命令（需要--unsafe参数），gc为概率式清理；
• 构建系统开始创建并使用cmd/bup-python，它指向./configure阶段选定的 Python 解释器；
• bup web支持unix://...文件系统套接字并能在收到 SIGTERM 时有序退出。

0.28.1 正是为修补这批新机制中的缺陷而来，改动集中在三处：发布归档构建、OS X 下的测试、以及cmd/bup-python的权限行为。整体变更内容见 note/0.28.1-from-0.28.md。

从git archive发布归档重新构建

问题现象

0.28.1 的第一个修复是："Builds from unpacked release archives (created viagit archive TAG) should work again"，即从解压后的发布归档（用git archive TAG制作）重新构建应当恢复工作。

要理解这一修复，需要先明白 bup 源码树中存在一类构建时生成文件。以 GNUmakefile 为例，构建系统在配置阶段执行：

$(shell dev/update-checkout-info lib/bup/checkout_info.py)

该命令调用 dev/update-checkout-info，在普通 git 检出中生成lib/bup/checkout_info.py，其中包含当前提交的 SHA-1、分支等检出信息。而git archive生成的归档不包含这一生成文件——归档内容只来自版本库中被标记跟踪的文件，构建时生成的中间产物不会入包。

源码中的应对机制

GNUmakefile 的安装规则给出了完整逻辑：

if test -e lib/bup/checkout_info.py; then \ $(INSTALL) -pm 0644 lib/bup/checkout_info.py \ $(dest_libdir)/bup/source_info.py; \ else \ ! grep -qF '$$Format' lib/bup/source_info.py; \ $(INSTALL) -pm 0644 lib/bup/source_info.py $(dest_libdir)/bup/; \ fi

也就是说：

• 若存在lib/bup/checkout_info.py（普通 git 检出场景），安装时以source_info.py之名装入库目录；
• 若不存在（归档构建场景），则先检查随源码分发的lib/bup/source_info.py中是否残留未替换的$Format占位符（grep -qF '$$Format'），确认无占位符后直接安装。

$Format:...$是 git 的export-subst 属性占位符：当仓库配置了.gitattributes中的export-subst且通过git archive打包时，git 会就地替换这些占位符为对应元数据。因此归档发布版自带的source_info.py中信息已经是替换好的，不再依赖 checkout 钩子。

0.28.1 之所以要"恢复"这一能力，是因为 0.28 引入cmd/bup-python等新构建目标后，构建规则对 checkout 环境的假设变严格了，导致归档构建路径失败。该版本把归档场景与检出场景统一梳理，并配合 0.31 起对git archive内容漂移问题的持续处理（见 note/0.31-from-0.30.1.md），使发布归档成为可复现的构建输入。仓库中 test/ext/test-versioning-and-archive 的测试脚本也体现了发布与归档验证流程：

WVPASS git archive --prefix=bup/ -o "$tmpdir"/bup.tgz HEAD

OS X 与 Homebrew rsync 下的 test-web / test-meta 修复

第二条构建系统修复是："test-web.sh and test-meta.sh should now work on newer versions of OS X, and with Homebrew rsync"。

test-web 与 test-meta 分别对应 test/ext/test-web 与 test/ext/test-meta 两个扩展测试脚本，它们早期是独立的.sh测试（0.28.1 时期分别名为 test-web.sh / test-meta.sh，后续随 bup 将扩展测试收敛为统一命名）。二者的共同特点是：

• test-web 依赖 tornado Web 框架（0.29 起在 note/0.29-from-0.28.1.md 中明确"web tests should be skipped if tornado is not detected"），并常通过bup web起一个本地服务器进行 HTTP 层面的验证；
• test-meta 会大量读写文件元数据（xattr、ACL、mtime 等），测试过程中依赖 rsync 来传输并比对目录树的元数据差异。

问题根源在 macOS 环境的两个特性：其一，新版 OS X 对fsync、xattr 与 ACL 的语义遵循与 Linux 不同（0.28 的修复列表中也有"OS X 对fsync()规范有出乎意料的解释"的条目，见 note/0.28-from-0.27.1.md）；其二，Homebrew 安装的 rsync 与系统自带 rsync 版本差异较大，其-a/-X/-A等选项对元数据（尤其是 OS X 扩展属性与 resource fork）的处理行为不同，导致测试在元数据比对环节失败。

0.28.1 的修复方式是让这些测试脚本对 rsync 版本与 OS X 行为做适配，而不是假设所有环境下 rsync 的元数据语义一致。这也是 bup 元数据处理一贯谨慎态度的延续——仓库 lib/bup/metadata.py 在 macOS 上处理符号链接权限时，甚至会临时修改 umask 来保证结果可复现。修复之后，make -j check（0.28 起支持的并行测试，见 note/0.28-from-0.27.1.md）在 macOS + Homebrew 环境下也能完整跑通。

cmd/bup-python 权限遵循 umask

bup-python 的由来

cmd/bup-python是 0.28 引入的构建产物。为了让 bup 的所有脚本（尤其是 dev 目录下的辅助脚本与安装后的命令包装器）统一使用./configure阶段选定的 Python，构建系统从 lib/cmd/bup.c 用不同的编译宏编译出多个变体（见 GNUmakefile）：

dev/bup-exec.o: bup_common_cflags += -D BUP_DEV_BUP_EXEC=1 dev/bup-python.o: bup_common_cflags += -D BUP_DEV_BUP_PYTHON=1

其中dev/bup-python通过-D BUP_DEV_BUP_PYTHON=1编译，链接src/bup/io.o后生成一个内嵌了所选 Python 解释器的可执行文件，仓库内大量 dev 脚本都以它运行（例如 dev/lib.sh 中bup-python() { "$bup_dev_lib_top/dev/bup-python" "$@"; }）。./configure阶段会把选定的解释器信息写入 config/config.var/bup-python-config，安装后相关的脚本 shebang 会替换为明确的#!/...行。

权限问题的本质

0.28 期间，cmd/bup-python在构建时通过$(CC) ... -o $@（见 GNUmakefile 的ld_py_bin）直接由链接器生成，其文件模式（权限位）取决于编译器/链接器的默认输出权限，而不是调用者当前 umask 所期望的值。对于多用户系统或遵循严格安全策略（例如默认umask 077）的环境，这会导致生成的可执行文件权限过宽或与预期不一致。

0.28.1 的修复是让cmd/bup-python的权限遵循 umask——从源码结构看，最直接的实现途径是让该二进制在构建/安装阶段以install -m显式设置模式位（GNUmakefile 中对安装文件统一使用$(INSTALL) -pm 0755这类规则，见 GNUmakefile），install工具会在给定模式上叠加当前 umask 取交集，从而既保证可执行位，又尊重用户的权限收缩策略。

仓库中对 umask 的系统性处理

bup 对 umask 的重视并非孤立修复。在 lib/bup/io.py，模块加载伊始就读取并恢复 umask：

# Get the umask once, early, so we can avoid further global changes. initial_umask = os.umask(0o777) os.umask(initial_umask)

initial_umask被全库复用：例如 lib/bup/bloom.py 创建 bloom 过滤器时执行os.fchmod(fd, 0o666 & ~initial_umask)，确保临时文件权限也受 umask 约束。后续版本持续强化这一行为——0.33 的变更说明中即包含"bup should now respect the current umask, directory sgid bit, ..."（见 note/0.33-from-0.32.md），test/ext/test-empty-metadata 等测试还会显式切换 umask 验证行为。0.28.1 对cmd/bup-python的修复，正是这条权限纪律在构建产物上的补全。

修复影响与升级建议

综合来看，0.28.1 是一个小步快走的补丁版本，三项改动分别落在发布可复现性、测试平台兼容性与构建产物权限正确性上：

对使用者而言：如果你是从官方 tag 归档而非 git 检出构建 bup，0.28.1 是值得升级的版本——它恢复了归档构建路径；如果你在 macOS 且使用 Homebrew rsync 跑测试，此版本让 test-web 与 test-meta 不再因 rsync 元数据语义差异而误报。权限相关改动则让cmd/bup-python在受控 umask 环境下的行为可预期，与 bup 整体对文件权限、元数据的严谨态度保持一致。

0.28.1 由 Gernot Schulz、Karl Semich、Rob Browning 与 ilovezfs 等贡献者共同完成（见 note/0.28.1-from-0.28.md 末尾致谢）。后续的 note/0.29-from-0.28.1.md 则在此基础上继续推进 Python 2.6 兼容、索引格式调整、实验性prune-older命令与gc性能优化，感兴趣的读者可以沿着 note 目录下的版本变更序列追踪 bup 的演进脉络。

• 灾备
• CLI
• 存储