Skip to contentSkip to conversation

perf doc improvements to man page reproducibility

PATCH Applied Ben Hutchings 2 participants 4 messages May 13, 2023 – May 15, 2023 1 message not in the archive perf events

lore
Share & tools
lore
#0 lore raw

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(-)
#1 lore raw

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
index ba5d942e4c6a..8a7d7078e386 100644
@@ -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
#2 lore raw

PATCH v2 2/2 perf doc: Add support for KBUILD_BUILD_TIMESTAMP

In reply to Ben Hutchings

From: 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
index 8a7d7078e386..4407b106d977 100644
@@ -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

maintainer Applied
#4 lore raw

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_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.

Quoted 8 lines
Quoted 6 lines

Ben.

Ben Hutchings (2):
perf doc: Define man page date when using asciidoctor perf doc: Add support for KBUILD_BUILD_TIMESTAMP

Thanks, applied.

- Arnaldo