doc lint: make "lint-docs" non-.PHONY

Speed up the "lint-docs" target by making it non-.PHONY. Similar to my c234e8a0ecf (Makefile: make the "sparse" target non-.PHONY, 2021-09-23). We'll now create empty files corresponding to a dependency graph for each of these lint scripts. This speeds things up a bit[1], and makes the output correspond to any in-tree changes we have: $ touch git-add.txt; make lint-docs; make lint-docs GEN cmd-list.made GEN doc.dep LINT GITLINK git-add.txt LINT MAN END git-add.txt LINT MAN SEC git-add.txt make: Nothing to be done for 'lint-docs'. As with the "sparse" target changes this has a hard dependency on the use of ".DELETE_ON_ERROR" in the Makefile, added here in db10fc6c09f (doc: simplify Makefile using .DELETE_ON_ERROR, 2021-05-21). This method also depends on the output for us emitting any errors on STDERR (fixed in a preceding commit), as well us these scripts exiting with non-zero on any errors (which they were already doing). 1. $ git show HEAD~:Documentation/Makefile >Makefile.old $ hyperfine --warmup 2 -L f ",.old" 'make -j1 -f Makefile{f} lint-docs' Benchmark #1: make -j1 -f Makefile lint-docs Time (mean ± σ): 60.8 ms ± 1.4 ms [User: 58.7 ms, System: 2.5 ms] Range (min … max): 58.9 ms … 64.0 ms 48 runs Benchmark #2: make -j1 -f Makefile.old lint-docs Time (mean ± σ): 84.0 ms ± 1.5 ms [User: 78.6 ms, System: 5.7 ms] Range (min … max): 81.8 ms … 87.8 ms 35 runs Summary 'make -j1 -f Makefile lint-docs' ran 1.38 ± 0.04 times faster than 'make -j1 -f Makefile.old lint-docs' Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Ævar Arnfjörð Bjarmason committed Oct 15, 2021 at 14:39 UTC 8650c6298c1cde720ffe3fe9f222662f61e7a0dc
3 files changed +64 -8
Documentation/.gitignore
+1
@@ -14,4 +14,5 @@ manpage-base-url.xsl
14 SubmittingPatches.txt
15 tmp-doc-diff/
16 GIT-ASCIIDOCFLAGS
17 +/.build/
18 /GIT-EXCLUDED-PROGRAMS
Documentation/Makefile
+59 -6
@@ -223,6 +223,7 @@ endif
223
224 ifneq ($(findstring $(MAKEFLAGS),s),s)
225 ifndef V
226 + QUIET = @
227 QUIET_ASCIIDOC = @echo ' ' ASCIIDOC $@;
228 QUIET_XMLTO = @echo ' ' XMLTO $@;
229 QUIET_DB2TEXI = @echo ' ' DB2TEXI $@;
@@ -230,11 +231,15 @@ ifndef V
231 QUIET_DBLATEX = @echo ' ' DBLATEX $@;
232 QUIET_XSLTPROC = @echo ' ' XSLTPROC $@;
233 QUIET_GEN = @echo ' ' GEN $@;
233 - QUIET_LINT = @echo ' ' LINT $@;
234 QUIET_STDERR = 2> /dev/null
235 QUIET_SUBDIR0 = +@subdir=
236 QUIET_SUBDIR1 = ;$(NO_SUBDIR) echo ' ' SUBDIR $$subdir; \
237 $(MAKE) $(PRINT_DIR) -C $$subdir
238 +
239 + QUIET_LINT_GITLINK = @echo ' ' LINT GITLINK $<;
240 + QUIET_LINT_MANSEC = @echo ' ' LINT MAN SEC $<;
241 + QUIET_LINT_MANEND = @echo ' ' LINT MAN END $<;
242 +
243 export V
244 endif
245 endif
@@ -344,6 +349,7 @@ GIT-ASCIIDOCFLAGS: FORCE
349 fi
350
351 clean:
352 + $(RM) -rf .build/
353 $(RM) *.xml *.xml+ *.html *.html+ *.1 *.5 *.7
354 $(RM) *.texi *.texi+ *.texi++ git.info gitman.info
355 $(RM) *.pdf
@@ -478,14 +484,61 @@ quick-install-html: require-htmlrepo
484 print-man1:
485 @for i in $(MAN1_TXT); do echo $$i; done
486
481 -lint-docs::
482 - $(QUIET_LINT)$(PERL_PATH) lint-gitlink.perl \
487 +## Lint: Common
488 +.build:
489 + $(QUIET)mkdir $@
490 +.build/lint-docs: | .build
491 + $(QUIET)mkdir $@
492 +
493 +## Lint: gitlink
494 +.build/lint-docs/gitlink: | .build/lint-docs
495 + $(QUIET)mkdir $@
496 +.build/lint-docs/gitlink/howto: | .build/lint-docs
497 + $(QUIET)mkdir $@
498 +.build/lint-docs/gitlink/config: | .build/lint-docs
499 + $(QUIET)mkdir $@
500 +LINT_DOCS_GITLINK = $(patsubst %.txt,.build/lint-docs/gitlink/%.ok,$(HOWTO_TXT) $(DOC_DEP_TXT))
501 +$(LINT_DOCS_GITLINK): | .build/lint-docs/gitlink
502 +$(LINT_DOCS_GITLINK): | .build/lint-docs/gitlink/howto
503 +$(LINT_DOCS_GITLINK): | .build/lint-docs/gitlink/config
504 +$(LINT_DOCS_GITLINK): lint-gitlink.perl
505 +$(LINT_DOCS_GITLINK): .build/lint-docs/gitlink/%.ok: %.txt
506 + $(QUIET_LINT_GITLINK)$(PERL_PATH) lint-gitlink.perl \
507 + $< \
508 $(HOWTO_TXT) $(DOC_DEP_TXT) \
509 --section=1 $(MAN1_TXT) \
510 --section=5 $(MAN5_TXT) \
486 - --section=7 $(MAN7_TXT) && \
487 - $(PERL_PATH) lint-man-end-blurb.perl $(MAN_TXT) && \
488 - $(PERL_PATH) lint-man-section-order.perl $(MAN_TXT)
511 + --section=7 $(MAN7_TXT) >$@
512 +.PHONY: lint-docs-gitlink
513 +lint-docs-gitlink: $(LINT_DOCS_GITLINK)
514 +
515 +## Lint: man-end-blurb
516 +.build/lint-docs/man-end-blurb: | .build/lint-docs
517 + $(QUIET)mkdir $@
518 +LINT_DOCS_MAN_END_BLURB = $(patsubst %.txt,.build/lint-docs/man-end-blurb/%.ok,$(MAN_TXT))
519 +$(LINT_DOCS_MAN_END_BLURB): | .build/lint-docs/man-end-blurb
520 +$(LINT_DOCS_MAN_END_BLURB): lint-man-end-blurb.perl
521 +$(LINT_DOCS_MAN_END_BLURB): .build/lint-docs/man-end-blurb/%.ok: %.txt
522 + $(QUIET_LINT_MANEND)$(PERL_PATH) lint-man-end-blurb.perl $< >$@
523 +.PHONY: lint-docs-man-end-blurb
524 +lint-docs-man-end-blurb: $(LINT_DOCS_MAN_END_BLURB)
525 +
526 +## Lint: man-section-order
527 +.build/lint-docs/man-section-order: | .build/lint-docs
528 + $(QUIET)mkdir $@
529 +LINT_DOCS_MAN_SECTION_ORDER = $(patsubst %.txt,.build/lint-docs/man-section-order/%.ok,$(MAN_TXT))
530 +$(LINT_DOCS_MAN_SECTION_ORDER): | .build/lint-docs/man-section-order
531 +$(LINT_DOCS_MAN_SECTION_ORDER): lint-man-section-order.perl
532 +$(LINT_DOCS_MAN_SECTION_ORDER): .build/lint-docs/man-section-order/%.ok: %.txt
533 + $(QUIET_LINT_MANSEC)$(PERL_PATH) lint-man-section-order.perl $< >$@
534 +.PHONY: lint-docs-man-section-order
535 +lint-docs-man-section-order: $(LINT_DOCS_MAN_SECTION_ORDER)
536 +
537 +## Lint: list of targets above
538 +.PHONY: lint-docs
539 +lint-docs: lint-docs-gitlink
540 +lint-docs: lint-docs-man-end-blurb
541 +lint-docs: lint-docs-man-section-order
542
543 ifeq ($(wildcard po/Makefile),po/Makefile)
544 doc-l10n install-l10n::
Documentation/lint-gitlink.perl
+4 -2
@@ -5,11 +5,12 @@ use warnings;
5
6 # Parse arguments, a simple state machine for input like:
7 #
8 -# howto/*.txt config/*.txt --section=1 git.txt git-add.txt [...] --to-lint git-add.txt a-file.txt [...]
8 +# <file-to-check.txt> <valid-files-to-link-to> --section=1 git.txt git-add.txt [...] --to-lint git-add.txt a-file.txt [...]
9 my %TXT;
10 my %SECTION;
11 my $section;
12 my $lint_these = 0;
13 +my $to_check = shift @ARGV;
14 for my $arg (@ARGV) {
15 if (my ($sec) = $arg =~ /^--section=(\d+)$/s) {
16 $section = $sec;
@@ -36,7 +37,8 @@ sub report {
37 }
38
39 @ARGV = sort values %TXT;
39 -die "BUG: Nothing to process!" unless @ARGV;
40 +die "BUG: No list of valid linkgit:* files given" unless @ARGV;
41 +@ARGV = $to_check;
42 while (<>) {
43 my $line = $_;
44 while ($line =~ m/linkgit:((.*?)\[(\d)\])/g) {