commit bcbed9397197009cd6cbb3203b4531c23b3cf340
parent 710917ab4c9d138dfd49151912e8de76ebb109d9
Author: Christian Grothoff <christian@grothoff.org>
Date: Sat, 31 Oct 2026 13:17:32 +0100
reproducible build: set SOURCE_DATE_EPOCH (fixes #11905)
Diffstat:
4 files changed, 149 insertions(+), 0 deletions(-)
diff --git a/Makefile b/Makefile
@@ -4,6 +4,7 @@
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
+PYTHON = python3
PAPER =
BUILDDIR = _build
@@ -12,6 +13,26 @@ ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. You can find Sphinx at http://sphinx-doc.org/)
endif
+# Reproducible builds: every builder stamps the time of the build into its
+# output (the date in the .TH line of a manpage, \date{} in LaTeX, <dc:date>
+# and the zip entry times in the EPUB, POT-Creation-Date in the catalogs, the
+# /CreationDate of a PDF), so two builds of the same sources differ. Sphinx
+# and pdftex both take that date from SOURCE_DATE_EPOCH when it is set, so pin
+# it to the commit date of HEAD. A SOURCE_DATE_EPOCH already in the
+# environment or on the command line wins, which is what a distribution
+# building from a release tarball will provide; the fallback stays empty when
+# this is not a git checkout, as there is nothing better to use then.
+# conf.py repeats this for builds that invoke sphinx-build without make.
+ifeq ($(origin SOURCE_DATE_EPOCH), undefined)
+SOURCE_DATE_EPOCH := $(shell git log -1 --pretty=%ct 2>/dev/null)
+endif
+ifneq ($(strip $(SOURCE_DATE_EPOCH)),)
+export SOURCE_DATE_EPOCH
+# pdftex uses SOURCE_DATE_EPOCH for /CreationDate on its own, but only honours
+# it for \today and \pdfcreationdate if told to.
+export FORCE_SOURCE_DATE = 1
+endif
+
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
@@ -107,6 +128,10 @@ devhelp:
epub: diagrams
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+# Sphinx stamps the entries of the epub container with the modification times
+# of the files it just wrote, i.e. with the time of the build; this replaces
+# them with SOURCE_DATE_EPOCH, and is a no-op when that is unset.
+ $(PYTHON) contrib/reproducible-epub.py $(BUILDDIR)/epub/*.epub
@echo
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
diff --git a/README b/README
@@ -16,6 +16,15 @@ Then, do "make html" for HTML, "make texinfo" for Texinfo, etc.
The output is in subdir ‘_build’.
+The build is reproducible: the dates that Sphinx stamps into the output (the
+date in the .TH line of a manpage, \date{} in LaTeX, <dc:date> in the EPUB,
+...) are taken from the commit date of HEAD rather than from the clock, so
+rebuilding unchanged sources produces identical files -- which also keeps the
+‘prebuilt’ branch below free of diffs that are nothing but a new build date.
+Set SOURCE_DATE_EPOCH in the environment to override that date; that is what a
+distribution building from a release tarball, where there is no commit date to
+read, is expected to do.
+
Mermaid diagrams use sphinxcontrib-mermaid (packaged in Debian 13 trixie).
HTML output renders them in the browser using JavaScript from the extension's
default CDN. Mermaid CLI is not needed. Put diagrams inside an "only:: html"
diff --git a/conf.py b/conf.py
@@ -117,6 +117,34 @@ release = "1.0.0"
# Else, today_fmt is used as the format for a strftime call.
# today_fmt = '%B %d, %Y'
+# Reproducible builds: whichever of the two is used, the date it yields is the
+# date of the build, and it ends up in the output of most builders (the date in
+# the .TH line of a manpage, \date{} in LaTeX, <dc:date> in the EPUB, ...), so
+# two builds of the same sources differ. Sphinx takes that date from
+# SOURCE_DATE_EPOCH when it is set, so pin it to the commit date of HEAD. An
+# existing value wins, which is what a distribution building from a release
+# tarball will provide; if this is not a git checkout there is nothing better
+# to use, and the build date remains.
+#
+# The Makefile sets this as well, as it also has to reach the pdflatex run of
+# the latexpdf target; this is here so that calling sphinx-build directly --
+# which is what readthedocs and other hosted builders do -- is reproducible too.
+if not os.environ.get("SOURCE_DATE_EPOCH"):
+ import subprocess
+
+ try:
+ _last_commit_time = subprocess.run(
+ ["git", "log", "-1", "--pretty=%ct"],
+ cwd=os.path.dirname(os.path.abspath(__file__)),
+ check=True,
+ capture_output=True,
+ text=True,
+ ).stdout.strip()
+ except (OSError, subprocess.SubprocessError):
+ _last_commit_time = ""
+ if _last_commit_time:
+ os.environ["SOURCE_DATE_EPOCH"] = _last_commit_time
+
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = [
diff --git a/contrib/reproducible-epub.py b/contrib/reproducible-epub.py
@@ -0,0 +1,87 @@
+#!/usr/bin/env python3
+
+# This file is part of GNU TALER.
+# Copyright (C) 2026 Taler Systems SA
+#
+# TALER is free software; you can redistribute it and/or modify it under the
+# terms of the GNU Lesser General Public License as published by the Free
+# Software Foundation; either version 2.1, or (at your option) any later
+# version.
+#
+# TALER is distributed in the hope that it will be useful, but WITHOUT ANY
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+# FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for
+# more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with TALER; see the file COPYING. If not, see
+# <http://www.gnu.org/licenses/>
+
+"""Set every entry timestamp of an EPUB file to $SOURCE_DATE_EPOCH.
+
+Sphinx uses SOURCE_DATE_EPOCH for the dates it writes into the documents it
+generates, but it assembles the EPUB container with zipfile.ZipFile.write(),
+which reads the modification time of each member off the filesystem -- that is,
+from the moment of the build. Two EPUBs built from identical sources therefore
+differ in all of their entry headers. Rewriting the archive with a single
+fixed timestamp is enough to make them identical; the entry order, the
+compression of each entry and the stored (uncompressed) "mimetype" entry that
+the format requires to come first are all preserved as they were.
+
+Does nothing if SOURCE_DATE_EPOCH is unset, so that calling this unconditionally
+is harmless.
+"""
+
+import os
+import shutil
+import sys
+import tempfile
+import time
+import zipfile
+
+# The DOS timestamps in a zip archive cannot express anything before this.
+ZIP_EPOCH = (1980, 1, 1, 0, 0, 0)
+
+
+def normalize(filename, date_time):
+ """Rewrite the archive at @a filename with all entry times at @a date_time."""
+ with zipfile.ZipFile(filename) as original:
+ infolist = original.infolist()
+ contents = [original.read(info) for info in infolist]
+
+ # Write to a temporary file in the same directory and move it into place, so
+ # that an error cannot leave a half-written archive behind under the name of
+ # a complete one.
+ handle, temporary = tempfile.mkstemp(
+ dir=os.path.dirname(os.path.abspath(filename)), suffix=".epub"
+ )
+ os.close(handle)
+ try:
+ with zipfile.ZipFile(temporary, "w") as rewritten:
+ for info, data in zip(infolist, contents):
+ entry = zipfile.ZipInfo(filename=info.filename, date_time=date_time)
+ entry.compress_type = info.compress_type
+ entry.external_attr = info.external_attr
+ entry.internal_attr = info.internal_attr
+ entry.create_system = info.create_system
+ entry.comment = info.comment
+ rewritten.writestr(entry, data)
+ shutil.move(temporary, filename)
+ except BaseException:
+ if os.path.exists(temporary):
+ os.unlink(temporary)
+ raise
+
+
+def main(argv):
+ source_date_epoch = os.environ.get("SOURCE_DATE_EPOCH")
+ if not source_date_epoch:
+ return 0
+ date_time = max(time.gmtime(int(source_date_epoch))[:6], ZIP_EPOCH)
+ for filename in argv[1:]:
+ normalize(filename, date_time)
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main(sys.argv))