`SOURCE_DATE_EPOCH` is a [standardised environment variable](https://reproducible-builds.org/specs/source-date-epoch/) that distributions can set centrally and have build tools consume this in order to produce reproducible output.
`SOURCE_DATE_EPOCH` is a [standardised environment variable](https://reproducible-builds.org/specs/source-date-epoch/) that distributions can set centrally and have build tools consume this in order to produce reproducible output. In practice, `SOURCE_DATE_EPOCH` specifies the last modification of something, usually the source code, measured in the number seconds since the Unix epoch, ie. `January 1st 1970, 00:00:00 UTC`.
In practice `SOURCE_DATE_EPOCH` specifies the last modification of something, usually the source code, (measured) in seconds since the Unix epoch, which is January 1st 1970, 00:00:00 UTC.
Before implementing this, you should scan through [our checklist](https://wiki.debian.org/ReproducibleBuilds/StandardEnvironmentVariables#Checklist) to see if you can avoid implementing it.
If you find that it's ideal for your use-case, please feel free to jump straight to our **[published specification](https://reproducible-builds.org/specs/source-date-epoch/)**.
## Proposal
Please read our [SOURCE_DATE_EPOCH specification](https://reproducible-builds.org/specs/source-date-epoch/) for details.
See [Standard Environment Variables](https://wiki.debian.org/ReproducibleBuilds/StandardEnvironmentVariables) for more detailed discussion of the rationales behind this mechanism.
Below we also have more detailed discussion about this specific variable, as well as documentation on history and alternative proposals.
## Setting the variable
### Debian
In Debian, this is automatically set to the same time as the latest entry in `debian/changelog`, i.e. the same as the output of `dpkg-parsechangelog -SDate`.
1. For packages using debhelper, versions >= 9.20151004 (Bug:791823) exports this variable during builds, so you probably don't need to change anything. One exception is if your `debian/rules` needs this variable in non-debhelper parts, in which case you can try (3) or (4).
2. For packages using CDBS, versions >= 0.4.131 (Bug:794241) exports this variable during builds, so no changes are needed.
3. With dpkg >= 1.18.8 (Bug:824572) you can either `include /usr/share/dpkg/pkg-info.mk` or `include /usr/share/dpkg/default.mk`.
4. If none of the above options are good (you should have a ''very good reason'') then package maintainers may set and export this variable manually in `debian/rules`:
This snippet is believed to work on dpkg versions as far back as 2003.
### Git
To set SOURCE_DATE_EPOCH to the last modification of a git repository you can use 'git log', for example in shell:
```
SOURCE_DATE_EPOCH=$(git log -1 --pretty=%ct)
```
Before added support to a tool for reading this variable, you should scan through [Debian's checklist](https://wiki.debian.org/ReproducibleBuilds/StandardEnvironmentVariables#Checklist) to see if you can avoid implementing it: a number of tools already will do this for you. However, if you find that it's ideal for your use-case, please feel free to jump straight to our **[published specification](https://reproducible-builds.org/specs/source-date-epoch/)**.
## Reading the variable
We are persuading upstream tools to support this directly. You may help by writing patches for these tools; please add links to the bug reports here so we know, and to act as an example resource for future patch writers.
*[ghostscript](https://bugs.debian.org/794004)(Debian >= 9.16~dfsg-1, upstream [unfortunately rejected](http://bugs.ghostscript.com/show_bug.cgi?id=696765) due to additional constraints they have)
Or search in all Debian sources: <https://codesearch.debian.net/search?perpkg=1&q=SOURCE_DATE_EPOCH>
### Python >= 3.x
```
@@ -459,6 +376,80 @@ TODO: document some other nicer options. Generally, all invocations of `date(1)`
NOTE: faketime BREAKS builds on some archs, for example hurd. See #778462 for details.
## Setting the variable
### Debian
In Debian, this is automatically set to the same time as the latest entry in `debian/changelog`, i.e. the same as the output of `dpkg-parsechangelog -SDate`.
1. For packages using `debhelper` versions >= 9.20151004, [this variable is automatically exported during builds](https://bugs.debian.org/791823), so you probably don't need to change anything. One exception is if your `debian/rules` needs this variable in non-debhelper parts, in which case you can try (3) or (4).
2. For packages using CDBS, versions >= 0.4.131 [this variable is also exported automatically during builds](https://bugs.debian.org/794241), so no changes are needed.
3. With `dpkg` >= 1.18.8 you can either `include /usr/share/dpkg/pkg-info.mk` or `include /usr/share/dpkg/default.mk`. This was added in Debian bug [#824572](https://bugs.debian.org/824572).
4. If none of the above options are good (you should have a ''very good reason'') then package maintainers may set and export this variable manually in `debian/rules`:
We are persuading upstream tools to support `SOURCE_DATE_EPOCH` directly. You may help by writing patches for these tools; please add links to the bug reports here so we know, and to act as an example resource for future patch writers.
*[ghostscript](https://bugs.debian.org/794004)(Debian >= 9.16~dfsg-1, upstream [unfortunately rejected](http://bugs.ghostscript.com/show_bug.cgi?id=696765) due to additional constraints they have)
Or you can [search in all Debian sources](https://codesearch.debian.net/search?perpkg=1&q=SOURCE_DATE_EPOCH).
## More detailed discussion
Sometimes developers of build tools do not want to support `SOURCE_DATE_EPOCH`, or they will tweak the suggestion to something related but different. We really do think the best approach is to use `SOURCE_DATE_EPOCH` exactly as-is described above in our proposal, without any variation. Here we explain our reasoning versus the arguments we have encountered.
