sow build

sow build 是显式的 Desired-to-Built 收敛命令。它获取 Repository 写锁，恢复任何可裁决的 未完成 Operation，渲染并验证完整 Generation，最后切换协议指针。

语法

sow build [-j|--jobs N] [-C|--workdir DIR] [-r|--repo NAME] [-d|--dist NAME]... [-T|--timeout DUR | -N|--no-wait] [--json]

不带 -d 时，SOW 收敛所选 Repository 中全部受影响 Dist；带 -d 时只收敛指定 Dist， 未选择的变化继续保持 dirty。

结果

不带 --json 时，build 输出一行人类可读摘要：

sow build -r demo -d el9
built repository=demo operation=2769214987359113555 dists=el9 revision=4 generation=00000000000000000005 dirty=false

需要标准 Envelope 中的命令专属对象时使用 --json。

空操作构建

成员关系、相关策略、渲染设置与签名配置均未变化时，build 是幂等空操作，不增加 Generation：

sow build -r demo -d el9
build repository=demo dists=el9 already current (noop) revision=4 generation=00000000000000000005 dirty=false

策略收敛

build 会重新执行当前 exclude 与 limit 策略。收紧策略可能移除 Desired Membership； 放宽策略不会从残留包池字节恢复历史成员，需要重新运行 sow add。

提交与恢复

SOW 在同一文件系统暂存新元数据，验证完成后再切换可变协议指针。RPM 校验和命名元数据与 APT by-hash 确保新旧读者看到的视图始终自洽。

Pending 包体提升采用有界单写者 group commit。每批最多 512 个对象或 1 GiB：先创建 Pool 链接并持久化所有不同的目标父目录，再删除 pending 名称并持久化共享 pending 目录。中断只会 留下 pending-only、指向同一 inode 的双链接或 Pool-only 状态，都能按 journal 恢复；不会 持久地同时丢失两个名称。

一个 Operation 可以覆盖多个 Dist。每个 Dist 始终暴露完整视图；build 返回时，本次包含的所有 Dist 属于同一个 Built Generation。

开始新工作前，build 会尝试前向恢复或安全回滚非终态 Operation。如果日志、数据库与文件系统 证据互相矛盾，Repository 进入 error，build 拒绝猜测；不存在强制修复参数。

进度事件

耗时较长的构建会向 Operation Log 追加结构化 build_progress 记录。每条事件包含 phase、 completed、total 与 jobs。当前阶段为：

• rendering；
• promoting_payload；
• publishing_dists；
• normalizing_public_tree；
• finalizing。

这些事件不会推进 Operation 状态，也不会在每次更新后 checkpoint SQLite；它们只用于审计 与可观测性，不参与恢复决策。使用 sow log OPERATION 查看明细。

元数据签名

Managed 元数据签名只从 sow.yml 读取，没有命令行 Key 覆盖。配置的 Key 引用或指纹改变时， 相关 Dist 变为 dirty，下一次 build 重新签名。

• RPM：总是生成 repodata/repomd.xml；配置签名后额外生成 repomd.xml.asc。
• DEB：总是生成 Release；配置签名后额外生成 InRelease 与 Release.gpg。

退出码

参见

• sow status —— 判断是否需要收敛
• sow check —— 验证构建结果
• sow changes —— 查看生成的文件差异
• 事务与恢复 —— 完整提交协议