taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

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:
MMakefile | 25+++++++++++++++++++++++++
MREADME | 9+++++++++
Mconf.py | 28++++++++++++++++++++++++++++
Acontrib/reproducible-epub.py | 87+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
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))