A reproducible build lets another party recreate specified artifacts byte for byte from the stated source, build instructions, and relevant environment. The promise must name its outputs: matching object files is insufficient when the shipped executable differs. Reproduction provides evidence connecting source and distribution, while source review, provenance, and signatures address other questions. Two identical malicious builds are still malicious, and a compromised toolchain can reproduce its own unwanted behavior.

Record the inputs that affect bytes

Source revision and a compiler version are only part of the input. Dependencies, target architecture, SDK, linker, flags, file order, build paths, timestamps, locale, and packaging tools may influence the result. Pin the inputs that matter and describe the comparison boundary. A container image can help specify an environment, but using a container does not automatically remove network downloads, host mounts, or variable timestamps.

Time macros and debug information are common sources of differences. SOURCE_DATE_EPOCH supplies a stable timestamp convention to tools that support it; it does not rewrite every program’s notion of time. Compiler prefix mapping can normalize embedded source paths. A linker may independently record object paths or metadata, so compile-stage normalization must be checked against the final linked output.

When it breaks

Comparing only a selected section can conceal differences in the actual release. State whether the reproducibility claim covers an executable, its debug symbols, an archive, or a signed installer. If signing adds variable data, define and justify the boundary around the reproducible payload, and verify the signed distribution separately. Do not silently strip inconvenient bytes and continue claiming equality of the original files.

A matching hash from two runs on one host is useful evidence of local repeatability under those inputs. It is not independent verification across builders, and it does not establish the correctness of either source or tools. Conversely, a mismatch is a reason to investigate rather than automatic proof of compromise. Identify the differing component before deciding whether an input was missing from the declared environment.

Check it quickly

This fixture was tested on arm64 macOS with Apple clang 21.0.0 and its installed linker. Save it as repro-build.py and run python3 repro-build.py with the command-line developer tools installed. The linker flags are Apple-specific; do not assume a Linux linker accepts them. The script creates two temporary build directories and compiles the same small C program under three treatments.

from hashlib import sha256
from pathlib import Path
from tempfile import TemporaryDirectory
import json
import os
import subprocess

source = '#include <stdio.h>\nint main(void) { puts(__FILE__); puts(__DATE__ " " __TIME__); }\n'
with TemporaryDirectory() as directory:
    base = Path(directory)
    hashes = {mode: {'objects': [], 'executables': []}
              for mode in ('unmapped', 'compiler-only', 'complete')}
    output = []
    for name in ('one', 'two'):
        root = base / name
        root.mkdir()
        src = root / 'main.c'
        src.write_text(source)
        env = {'PATH': os.environ['PATH'], 'LC_ALL': 'C', 'SOURCE_DATE_EPOCH': '1700000000'}
        for mode in hashes:
            obj = root / (mode + '.o')
            binary = root / mode
            flags = [] if mode == 'unmapped' else [f'-ffile-prefix-map={root}=/src']
            subprocess.run(['clang', '-g', '-O0', *flags, '-c', str(src), '-o', str(obj)],
                           cwd=root, env=env, check=True, capture_output=True)
            os.utime(obj, (1700000000, 1700000000))
            linker = ['-Wl,-reproducible']
            if mode == 'complete':
                linker.append(f'-Wl,-oso_prefix,{root}/')
            subprocess.run(['clang', *linker, str(obj), '-o', str(binary)],
                           cwd=root, env=env, check=True, capture_output=True)
            hashes[mode]['objects'].append(sha256(obj.read_bytes()).hexdigest())
            hashes[mode]['executables'].append(sha256(binary.read_bytes()).hexdigest())
            if mode == 'complete':
                output.append(subprocess.check_output([str(binary)], text=True).splitlines())
    equality = {mode: {kind: pair[0] == pair[1] for kind, pair in records.items()}
                for mode, records in hashes.items()}
    assert equality == {'unmapped': {'objects': False, 'executables': False},
                        'compiler-only': {'objects': True, 'executables': False},
                        'complete': {'objects': True, 'executables': True}}
    assert output == [['/src/main.c', 'Nov 14 2023 22:13:20']] * 2
    print(json.dumps({'sha256': hashes, 'equal_between_directories': equality,
                      'complete_program_output': output,
                      'same_host_only': True}))

All treatments use epoch 1700000000 and fixed object modification times. Without path mapping, the object files and executables differ. With compiler mapping alone, the object hashes match but the executables still differ: the linker debug map retains the different object paths. This intermediate failure is why an object-level check cannot certify a release binary.

The complete treatment also enables the linker’s reproducible mode and removes the build-directory prefix from its object debug map. Both object and executable hashes then match between the two directories. Running the completed binaries prints /src/main.c and Nov 14 2023 22:13:20. The assertions compare whole files, including the resulting Mach-O metadata, rather than deleting differences after building.

These results cover one compiler, SDK, architecture, and simple program on one host. They do not establish that a larger package, another toolchain, or an independently signed release will reproduce. The script prints every digest and the equality decisions so the observed boundary remains explicit.

Investigate before broadening the claim

When a production comparison fails, retain both artifacts and their build manifests. Locate differences in archives, sections, and metadata, then remove the responsible uncontrolled input and rebuild. Keep the expected output set stable throughout the investigation. Once local repeatability is established, ask an independent environment to follow the published instructions and compare the declared release artifacts. That adds evidence that another party can reproduce the result, without turning reproducibility into a substitute for security review.

Sources