Reproducible Compilation

Non-reproducibility is almost never mysterious. It is a small set of recurring causes, and once you know them, diagnosing a difference is a matter of checking the list.

Timestamps. __DATE__ and __TIME__ in C, build times embedded in headers, archive member timestamps in .a files, and file modification times captured into artifacts. The standard remedy is the SOURCE_DATE_EPOCH convention: derive the timestamp from the source — usually the last commit date — so it is an input rather than an observation.

Absolute paths. Debug information records the compilation directory and source paths, so building in /home/alice/proj and /build produces different DWARF. -fdebug-prefix-map and -ffile-prefix-map rewrite them to a canonical form, and __FILE__ needs the same treatment.

Iteration order inside the compiler. This is the subtle one and the most instructive. If a compiler pass iterates over a hash map keyed by pointers, the order depends on allocation addresses, which depend on ASLR — so the same source produces differently-ordered output on every run. Compilers have found and fixed many of these; the general rule is that any container whose iteration order is observable in the output must have a deterministic order.

Parallelism. Anything whose name or number depends on which thread got there first: temporary file names, generated symbol suffixes, the order in which independently-compiled units are combined. A build that is reproducible with -j1 and not with -j8 has one of these.

Deliberately unique identifiers. Build IDs, UUIDs generated per build, and embedded version strings that include a build number. These need to be derived from content — a hash of the inputs — rather than generated, or excluded from the comparison explicitly.

The security argument is the one that funded most of the effort. If a build is reproducible, many independent parties can build the same source and compare artifacts. Agreement means no single builder was compromised; disagreement is a loud, specific signal. That converts "trust the release engineer" into "trust that several unrelated parties were not compromised identically", which is the practical descendant of the reasoning in [[trusting-trust]].

The engineering arguments are less dramatic and probably more valuable day to day. Reproducibility makes build caching sound: if the output is a function of the inputs, a cache keyed by the inputs is correct, which is what makes distributed build caches in Bazel and similar systems work at all. It makes a bisect meaningful, because a behavior difference between two builds must come from a source difference. And it removes an entire class of "works on my machine" where the artifact, not the environment, was different.

It also makes the stage 2 / stage 3 bootstrap comparison meaningful, which is the connection back to [[self-hosting]]: without determinism that check produces differences that prove nothing, and teams eventually disable it.

AtlasLang is a small enough system to have this property for free, and it is worth saying how rather than merely claiming it. Nothing in src/compilers/sim reads a clock, a path, an environment variable or a random source. Every pass iterates arrays and maps in insertion order, virtual registers are numbered from a counter that starts at zero for each function, and there is no parallelism anywhere. There is nothing available to be non-deterministic with.

That is asserted rather than assumed. scripts/compilers-sim.test.ts compiles every example twice and asserts that the IR text, the SSA text, the optimized IR text and the emitted assembly are all byte-identical between the two runs. The test would fail on any of the five causes above, and it is cheap enough to run on every change.

The honest caveat is that this is easy for us and hard for a real compiler. We have no threads, no allocator whose addresses we can accidentally observe, no debug information containing paths, no archives with timestamps, and no build system. Determinism at our scale is a matter of not doing anything careless; determinism at GCC's scale is a decade-long programme. What our test demonstrates is the *shape* of the property and the fact that it is checkable, not that achieving it is easy.

Every reproducibility claim is relative to two things that ought to be stated with it: what counts as the input set, and what is excluded from the comparison. A project that reproduces given the same container image, the same toolchain version and the same source is making a much narrower claim than one that reproduces across distributions and compiler versions, and both are useful.

Exclusions matter just as much. Signatures cannot be reproducible, since a signature depends on a key. Embedded build identifiers are often normalised away. Debug sections are sometimes compared separately or excluded. A claim of byte-identity that quietly excludes a third of the file is not the same claim as one that does not, and reading the exclusion list is part of understanding the guarantee.

The tooling is mature enough that this is checkable rather than aspirational. diffoscope recursively unpacks archives, disassembles binaries and decodes metadata to explain *why* two artifacts differ, which is what turns "these files differ" into an actionable bug. reprotest builds twice under deliberately varied conditions — different paths, times, hostnames, locales, thread counts — to find the causes before someone else does. Running either on a project that has never been checked is usually instructive within minutes.