可复现构建与确定性输出

# 验证可复现性的最小流程
git clone https://example.com/proj && cd proj && git checkout v1.2.3
make -j8 && sha256sum out/app > /tmp/hash1
rm -rf out && make -j8 && sha256sum out/app > /tmp/hash2
diff /tmp/hash1 /tmp/hash2 && echo "可复现"

# 用 diffoscope 定位两次构建的差异到底在哪
diffoscope out1/app out2/app --text /tmp/diff.txt
# 常见输出：section .comment 不同、嵌入的路径字符串不同

// 宏 __DATE__ 与 __TIME__ 会把构建时刻写进产物
const char *built = __DATE__ " " __TIME__;   // 两次构建必然不同

// 对策：可复现构建模式下把这两个宏固定为源码提交时间
// GCC: -D__DATE__=\"...\" 或使用 SOURCE_DATE_EPOCH

# SOURCE_DATE_EPOCH 是可复现构建的通用约定：用它替代「当前时间」
export SOURCE_DATE_EPOCH=$(git log -1 --format=%ct)
# 支持该约定的工具（gzip、tar、部分编译器与打包器）会据此生成固定时间戳

# 产物里嵌入的构建路径
strings out/app | grep -m3 "$(pwd)"
# /home/alice/proj/src/main.c
# /home/alice/proj/include/config.h

# GCC 与 Clang 的路径重映射
gcc -ffile-prefix-map=$(pwd)=/build -fdebug-prefix-map=$(pwd)=/build main.c -o app
clang -fdebug-prefix-map=$(pwd)=/build main.c -o app
# Rust 对应的是 --remap-path-prefix
cargo build --release --config 'build.rustflags=["--remap-path-prefix", "'"$PWD"'=/build"]'

# 经典陷阱：遍历字典/集合的顺序在不同运行中可能不同
env_vars = set(["PATH", "HOME", "LANG"])
with open("env.txt", "w") as f:
    for k in env_vars:          # 顺序不确定
        f.write(f"{k}\n")

# 修复：显式排序
for k in sorted(env_vars):
    f.write(f"{k}\n")

# 另一个常见来源：归档文件的成员顺序与时间戳
ar rcs libfoo.a a.o b.o c.o     # 顺序取决于命令行
ar rcs libfoo.a $(ls *.o | sort)  # 显式排序

# tar 归档的时间戳与属主
tar --sort=name --mtime="@$SOURCE_DATE_EPOCH" --owner=0 --group=0 \
    --numeric-owner -cf out.tar dir/

// 错误：按指针地址排序（每次运行不同）
std::sort(syms.begin(), syms.end(),
          [](const Sym *a, const Sym *b) { return a < b; });

// 正确：按内容（名称）排序，地址只作为稳定的次键
std::sort(syms.begin(), syms.end(), [](const Sym &a, const Sym &b) {
    if (a.name != b.name) return a.name < b.name;
    return a.section < b.section;      // 内容相同才用次键
});

# 哈希相关的陷阱：PYTHONHASHSEED 影响字符串哈希，从而影响集合顺序
# 对策：显式设置，或彻底避免依赖哈希顺序
import os
os.environ["PYTHONHASHSEED"] = "0"

# 并行构建时固定任务数量与调度，减少调度差异的影响
make -j1                      # 完全串行，最稳但最慢
make -j8 --output-sync=target # 输出同步，减少交错

# 段级归一化：把易变的段固定或剥离
gcc -frandom-seed=0 -Wl,--build-id=sha1 main.c -o app
strip --strip-unneeded app            # 剥离调试信息（会牺牲可调试性）
objcopy --remove-section=.comment app # 去掉编译器版本注释

# 用 build-id 做内容指纹：它由内容哈希得到，天然确定
readelf -n out/app | grep "Build ID"

# 用 random-seed 消除编译器内部的随机化命名
gcc -frandom-seed=fixed main.c -o app

缓存键的构成（必须覆盖全部影响输出的输入）：
  源码内容哈希
  编译命令行（规范化后，去掉绝对路径与临时目录）
  编译器版本与二进制哈希
  依赖库的内容哈希
  影响行为的受控环境变量
  目标平台三元组

# ccache：本地编译缓存
export CCACHE_BASEDIR=$(pwd)          # 把路径相对化，提高命中率
export CCACHE_SLOPPINESS=time_macros  # 允许忽略 __TIME__（有风险）
ccache -s                             # 查看命中统计

# sccache：支持跨机器共享的编译缓存
sccache --start-server
export RUSTC_WRAPPER=sccache
sccache --show-stats

# 缓存失效的诊断：为什么这次没命中
CCACHE_DEBUG=1 ccache gcc -c main.c
# 会生成 .ccache-input-*.log，逐项对比缓存键的哪个分量变了

构建图的基本模型：
  节点 = 目标（目标文件、库、可执行文件、生成的头文件）
  边   = 依赖（源文件、头文件、工具、命令行）

正确性条件：
  1. 图的传递闭包覆盖所有真实依赖（无漏边）
  2. 每个节点的输出只由它的输入决定（无隐藏输入）
  3. 时间戳或内容哈希能正确判定「是否需要重建」

# Makefile 的经典陷阱：头文件依赖没有自动生成
app: main.o util.o
	$(CC) $^ -o $@

main.o: main.c
	$(CC) -c $< -o $@        # 缺少 main.h 依赖！

# 对策：让编译器自动生成依赖文件并包含进来
CFLAGS += -MMD -MP
-include $(wildcard *.d)

# 头文件依赖的实际内容
# main.d 里会写：main.o: main.c main.h util.h config.h

# 增量正确性的最小判定
def needs_rebuild(target, deps):
    """所有依赖的哈希集合与上次记录比较，任一变化则重建"""
    cur = {d: content_hash(d) for d in deps}
    if cur != target.stored_deps:
        return True
    return not exists(target.path)     # 产物缺失也要重建

# CI 中的双构建比对
steps:
  - name: 第一次构建
    run: ./build.sh && sha256sum out/app > h1.txt
  - name: 第二次构建（不同目录、不同时刻）
    run: rm -rf out && ./build.sh && sha256sum out/app > h2.txt
  - name: 比对
    run: diff h1.txt h2.txt

# 跨机器验证：在容器里构建，比对不同机器的产物
docker build -t buildenv -f Dockerfile.build .
docker run --rm -v "$PWD:/src" buildenv bash -c "cd /src && ./build.sh && sha256sum out/app"

# 用容器做完全隔离的构建环境
FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y gcc make
ENV SOURCE_DATE_EPOCH=1700000000
ENV LC_ALL=C
WORKDIR /src

# 陷阱：strip 之后可复现了，但线上崩溃无法调试
# 对策：保留调试信息并单独发布（debug info 与二进制分离）
objcopy --only-keep-debug out/app out/app.dbg
objcopy --strip-debug out/app
objcopy --add-gnu-debuglink=out/app.dbg out/app

# 陷阱：--build-id 默认可能基于时间，改为内容哈希
ld --build-id=sha1 -o app main.o

# 逐项排查不确定性的实用清单
# 1. 产物里是否有路径字符串
strings out/app | grep -c "/home\|/Users\|/tmp"
# 2. 产物里是否有时间戳
strings out/app | grep -cE "[0-9]{4}-[0-9]{2}-[0-9]{2}"
# 3. 两次构建的段级差异
diffoscope a.out b.out --exclude-directory-metadata --text diff.txt