Differences between revisions 22 and 24 (spanning 2 versions)
Revision 22 as of 2016-10-07 12:31:52
Size: 8067
Editor: Infinity0
Comment: update from template [[ReproducibleBuilds/ProposalTemplate]]
Revision 24 as of 2016-10-07 13:32:32
Size: 8332
Editor: Infinity0
Comment: update from template [[ReproducibleBuilds/ProposalTemplate]]
Deletions are marked like this. Additions are marked like this.
Line 5: Line 5:

If you need to edit text inside the "GetVal" parts, edit them in [[ReproducibleBuilds/BuildPathProposal/Dict]].

If you need to edit text outside the "GetVal" parts (but still in this section), please also make the equivalent edit back in the original [[ReproducibleBuilds/ProposalTemplate|template]]!
 * If you need to edit text inside the `GetVal` parts, edit them in [[ReproducibleBuilds/BuildPathProposal/Dict]].
 * If you need to edit text outside the `GetVal` parts (but still in this section), please also make the equivalent edit back in the original [[ReproducibleBuilds/ProposalTemplate|template]]!
Line 23: Line 21:
This is a standard that defines an environment variable <<GetVal(ReproducibleBuilds/BuildPathProposal/Dict, envvar_name)>>, that distributions can implement centrally, and have build tools obey this in order to produce reproducible output even if the upstream project is not specifically aware of reproducible builds. This is a standard that defines an environment variable <<GetVal(ReproducibleBuilds/BuildPathProposal/Dict, envvar_name)>> 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.
Line 31: Line 29:
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, <<GetVal(ReproducibleBuilds/BuildPathProposal/Dict, example_deleteinfo)>>. 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, <<GetVal(ReproducibleBuilds/BuildPathProposal/Dict, example_deleteinfo)>>. See [[#hard-req-envvar]] for more discussion.
Line 35: Line 33:
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, to either avoid generating this information or to generate a reproducible value. For example, <<GetVal(ReproducibleBuilds/BuildPathProposal/Dict, example_toolspecific)>>. 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. 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, <<GetVal(ReproducibleBuilds/BuildPathProposal/Dict, example_toolspecific)>>. 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.
Line 55: Line 53:

If you need to edit text inside the "GetVal" parts, edit them in [[ReproducibleBuilds/BuildPathProposal/Dict]].

If you need to edit text outside the "GetVal" parts (but still in this section), please also make the equivalent edit back in the original [[ReproducibleBuilds/ProposalTemplate|template]]!
 * If you need to edit text inside the `GetVal` parts, edit them in [[ReproducibleBuilds/BuildPathProposal/Dict]].
 * If you need to edit text outside the `GetVal` parts (but still in this section), please also make the equivalent edit back in the original [[ReproducibleBuilds/ProposalTemplate|template]]!
Line 63: Line 59:
Sometimes developers of build tools do not want to support <<GetVal(ReproducibleBuilds/BuildPathProposal/Dict, envvar_name)>>, or they will tweak the suggestion to something related but different. We really do think the best approach is to use <<GetVal(ReproducibleBuilds/BuildPathProposal/Dict, envvar_name)>> exactly as-is describe above in our proposal, without any variation. Here we explain our reasoning versus the arguments we encountered: Sometimes developers of build tools do not want to support <<GetVal(ReproducibleBuilds/BuildPathProposal/Dict, envvar_name)>>, or they will tweak the suggestion to something related but different. We really do think the best approach is to use <<GetVal(ReproducibleBuilds/BuildPathProposal/Dict, envvar_name)>> exactly as-is described above in our proposal, without any variation. Here we explain our reasoning versus the arguments we have encountered:
Line 73: Line 69:

If you need to edit text inside the "GetVal" parts, edit them in [[ReproducibleBuilds/BuildPathProposal/Dict]].

If you need to edit text outside the "GetVal" parts (but still in this section), please also make the equivalent edit back in the original [[ReproducibleBuilds/ProposalTemplate|template]]!
 * If you need to edit text inside the `GetVal` parts, edit them in [[ReproducibleBuilds/BuildPathProposal/Dict]].
 * If you need to edit text outside the `GetVal` parts (but still in this section), please also make the equivalent edit back in the original [[ReproducibleBuilds/ProposalTemplate|template]]!
Line 79: Line 73:
<<Anchor(tool-specific-args)>>
Line 87: Line 82:
<<Anchor(hard-req-envvar)>>
Line 91: Line 87:
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'' <<GetVal(ReproducibleBuilds/BuildPathProposal/Dict, envvar_name)>> to be set. In other words, don't use things like <<GetVal(ReproducibleBuilds/BuildPathProposal/Dict, buildtime_information_example)>>. There are usually better alternatives available, or you can just omit such information. 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 <<GetVal(ReproducibleBuilds/BuildPathProposal/Dict, envvar_name)>> themselves. For example, you could avoid using things like <<GetVal(ReproducibleBuilds/BuildPathProposal/Dict, buildtime_information_example)>> (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.

Background

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.

Description

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.

Proposal

FIXME

Setting the variable

FIXME

Reading the variable

FIXME

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

FIXME