/!\ This is a draft/discussion for a spec in development. Originally we thought to call the variable SOURCE_PREFIX_MAP but it seems we might prefer to call it BUILD_PATH_PREFIX_MAP today. (2017-01-24)

/!\ some code is here: https://github.com/infinity0/rb-prefix-map/tree/master/consume


Sometimes build tools embed into the output. This causes the build to be unreproducible when .

There are different reasons why this is done, most commonly . However, we have never seen nor do we foresee a reasonable use-case where the actual is needed; all the use-cases we have seen, would equally be satisfied by using the . This has the additional benefit of giving reproducible build output.

In fact, it is already possible for upstream projects to do this. They could - as opposed to .

However in many cases, upstream projects are not the ones directly responsible for embedding this information into the build output - it is some intermediate build tool that does it, e.g. . So they (the upstream project) shouldn't have to implement this detection and then supply this information to that build tool, just to get reproducible build output. Therefore, we have chosen to define this standard.


This is a standard that defines an environment variable that distributions can set centrally, and have build tools obey this in order to produce reproducible output even if projects that use these tools are not specifically aware of reproducible builds.

This minimises the work required across the whole software community, to achieve reproducible builds by default. However, it does add a tiny bit of complexity to specific build tools. So, before implementing this, you should go through the following checklist, to see if you can avoid implementing it:

Checklist: Do I really need to use this?

1. See if strip-nondeterminism will get rid of the difference for you, or if it's easy to add this functionality to it. If yes, then you don't need this variable. For example, .

2. See if you can patch the tool that generates this information, to simply not generate this information in the first place. If this is a good idea, then you don't need this variable. For example, . See #hard-req-envvar for more discussion.

3. See if you can patch the tool that generates this information, to use this specification to generate a reproducible value for this information, based on a standardised environment variable set centrally by your distribution. This is what this document is about.

4. See if you can patch the package that uses the tool, to give it some tool-specific options like CLI arguments or its own environment variables, either to avoid generating this information or to generate a reproducible value. For example, . However, this should be avoided in favour of the above options, since you will have to do this for every package that uses the tool. See #tool-specific-args for more discussion.



Setting the variable


Reading the variable


More detailed discussion

Sometimes developers of build tools do not want to support , or they will tweak the suggestion to something related but different. We really do think the best approach is to use exactly as-is described above in our proposal, without any variation. Here we explain our reasoning versus the arguments we have encountered:

FIXME (add other points here, before the "generic" points)

"We'll add a command-line flag instead"

Build tool developers dislike the name or the mechanism of environment variables, and prefer to use command line options, perhaps to be more consistent with the rest of their program.

We understand the desire to avoid inconsistency, or supporting seemingly arbitrary environment variables. However, are by far one of the largest issues that prevents reproducible builds from becoming reality, and every tool supporting a standardised mechanism would greatly lower the cost of that. If every tool supported different mechanisms to do the same thing, the overall cost is greatly higher. In other words, we ask that you consider global consistency across many different projects, over any smaller-scale inconsistency in your own project.

From another point of view: we agree that it is easy for users of your tool to add a command-line option, but then they have to specifically think about reproducible builds. This is not, and ought not to be, in the minds of most software developers. Reproducible builds should be the default situation for all software, and we shouldn't burden developers with these trivialities. Opt-in security is not security, because nobody will take the effort to opt-in even if in general they think it's a good idea. (This is not a paradox; people like getting things for free.)

Hard-requirement on this variable for reproducibility

is meant to be a cost-reduction mechanism, to avoid having to globally patch many hundreds of projects in the same way.

However, if you are a project developer and you want to make your specific project reproducible, the best way is to do it without requiring the user to set themselves. For example, you could avoid using things like (there might be better alternatives available), or you could detect a sensible default value in your top-level Makefile (or equivalent) and set it if unset.

History and alternate proposals