perf doc improvements to man page reproducibility
v2 cover perf doc improvements to man page reproducibility
I previously sent a patch in 2016(!) to make the dates in man pages reproducible, with KBUILD_BUILD_TIMESTAMP specifiying the date. That patch partly overlaps with commit d586ac10ce56 "perf docs: Allow man page date to be specified", which implemented generation of dates based on commit timestamps.
However, both of those implementations were specific to the original asciidoc's DocBook backend and had no effect on asciidoctor's direct man page generation.
This series builds on the current definition of perf_date, adding support for asciidoctor and the KBUILD_BUILD_TIMESTAMP variable.
Ben.
Ben Hutchings (2):
perf doc: Define man page date when using asciidoctor perf doc: Add support for KBUILD_BUILD_TIMESTAMP
tools/perf/Documentation/Makefile | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-)
PATCH v2 1/2 perf doc: Define man page date when using asciidoctor
From: Ben Hutchings <[email protected]>
When building perf documentation with asciidoc, we use "git log" to find the last commit date of each doc source and pass that to asciidoc to use as the man page date.
When using asciidoctor, however, the current date is always used instead. Defining perf_date like we do for asciidoc also doesn't work because we're not using DocBook as an intermediate format. The asciidoctor man page backend looks for the variable "docdate", so set that instead.
--- tools/perf/Documentation/Makefile | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-)
tools/perf/Documentation/Makefile +7 -4
@@ -250,11 +250,16 @@ $(MAN_HTML): $(OUTPUT)%.html : %.txt $(ASCIIDOC_EXTRA) -aperf_version=$(PERF_VERSION) -o $@+ $< && \ mv $@+ $@ +# Generate date from git log of the doc input file +PERF_DATE = $(shell git log -1 --pretty="format:%cd" \ + --date=short --no-show-signature $<) + ifdef USE_ASCIIDOCTOR $(OUTPUT)%.1 $(OUTPUT)%.5 $(OUTPUT)%.7 : %.txt $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ $(ASCIIDOC) -b manpage -d manpage \ - $(ASCIIDOC_EXTRA) -aperf_version=$(PERF_VERSION) -o $@+ $< && \ + $(ASCIIDOC_EXTRA) -aperf_version=$(PERF_VERSION) \ + -adocdate=$(PERF_DATE) -o $@+ $< && \ mv $@+ $@ endif
@@ -266,9 +271,7 @@ $(OUTPUT)%.xml : %.txt $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ $(ASCIIDOC) -b docbook -d manpage \ $(ASCIIDOC_EXTRA) -aperf_version=$(PERF_VERSION) \ - -aperf_date=$(shell git log -1 --pretty="format:%cd" \ - --date=short --no-show-signature $<) \ - -o $@+ $< && \ + -aperf_date=$(PERF_DATE) -o $@+ $< && \ mv $@+ $@ XSLT = docbook.xsl
PATCH v2 2/2 perf doc: Add support for KBUILD_BUILD_TIMESTAMP
In reply to Ben HutchingsFrom: Ben Hutchings <[email protected]>
When building man pages from a Git checkout, we consistently set the man page date based on when the input was last changed. Otherwise, it defaults to the build time, which is not reproducible.
Allow the date to be set through the KBUILD_BUILD_TIMESTAMP variable, as for timestamps in the kernel itself.
--- tools/perf/Documentation/Makefile | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-)
tools/perf/Documentation/Makefile +7 -3
@@ -250,9 +250,13 @@ $(MAN_HTML): $(OUTPUT)%.html : %.txt $(ASCIIDOC_EXTRA) -aperf_version=$(PERF_VERSION) -o $@+ $< && \ mv $@+ $@ -# Generate date from git log of the doc input file -PERF_DATE = $(shell git log -1 --pretty="format:%cd" \ - --date=short --no-show-signature $<) +# Generate date from either KBUILD_BUILD_TIMESTAMP or git log of +# the doc input file +PERF_DATE = $(strip \ + $(if $(KBUILD_BUILD_TIMESTAMP), \ + $(shell date -u -d '$(KBUILD_BUILD_TIMESTAMP)' +%Y-%m-%d), \ + $(shell git log -1 --pretty="format:%cd" \ + --date=short --no-show-signature $<))) ifdef USE_ASCIIDOCTOR $(OUTPUT)%.1 $(OUTPUT)%.5 $(OUTPUT)%.7 : %.txt
A message that is not in the archive (sent off-list or not yet received): CAP-5=fXmL509c2rhE7SYj9FW62eZPc7tPEWzG1h0DztF+Qmnww@mail.gmail.com
Em Mon, May 15, 2023 at 07:26:52AM -0700, Ian Rogers escreveu:
Quoted 15 lines · Ben Hutchings
Quoted 14 lines
I previously sent a patch in 2016(!) to make the dates in man pages reproducible, with
KBUILD_BUILD_TIMESTAMPspecifiying the date. That patch partly overlaps with commitd586ac10ce56"perf docs: Allow man page date to be specified", which implemented generation of dates based on commit timestamps.However, both of those implementations were specific to the original asciidoc's DocBook backend and had no effect on asciidoctor's direct man page generation.
This series builds on the current definition of
perf_date, adding support for asciidoctor and theKBUILD_BUILD_TIMESTAMPvariable.
Quoted 8 lines
Quoted 6 lines
Ben.
Ben Hutchings (2):
perf doc: Define man page date when using asciidoctor perf doc: Add support forKBUILD_BUILD_TIMESTAMPAcked-by Ian Rogers<[email protected]>
Thanks, applied.
- Arnaldo