Re: [PATCH] Documentation/Makefile: fix lint-docs mkdir dependency

["Ævar Arnfjörð Bjarmason" <avarab@gmail.com>]

On Tue, Oct 26 2021, Jeff King wrote:

> Since 8650c6298c (doc lint: make "lint-docs" non-.PHONY, 2021-10-15), we
> put the output for gitlink linter into .build/lint-docs/gitlink. There
> are order-only dependencies to create the sequence of subdirs like:
>
>   .build/lint-docs: | .build
>           $(QUIET)mkdir $@
>   .build/lint-docs/gitlink: | .build/lint-docs
>           $(QUIET)mkdir $@
>
> where each level has to depend on the prior one (since the parent
> directory must exist for us to create something inside it). But the
> "howto" and "config" subdirectories of gitlink have the wrong
> dependency; they depend on "lint-docs", not "lint-docs/gitlink".
>
> This usually works out, because the LINT_DOCS_GITLINK targets which
> depend on "gitlink/howto" also depend on just "gitlink", so the
> directory gets created anyway. But since we haven't given make an
> explicit ordering, things can racily happen out of order.
>
> If you stick a "sleep 1" in the rule to build "gitlink" like this:
>
>    ## Lint: gitlink
>    .build/lint-docs/gitlink: | .build/lint-docs
>   -	$(QUIET)mkdir $@
>   +	$(QUIET)sleep 1 && mkdir $@
>
> then "make clean; make lint-docs" will fail reliably. Or you can see it
> as-is just by building the directory in isolation:
>
>   $ make clean
>   [...]
>   $ make .build/lint-docs/gitlink/howto
>       GEN mergetools-list.made
>       GEN cmd-list.made
>       GEN doc.dep
>       SUBDIR ../
>   make[1]: 'GIT-VERSION-FILE' is up to date.
>       SUBDIR ../
>   make[1]: 'GIT-VERSION-FILE' is up to date.
>   mkdir: cannot create directory ‘.build/lint-docs/gitlink/howto’: No such file or directory
>   make: *** [Makefile:476: .build/lint-docs/gitlink/howto] Error 1
>
> The fix is easy: we just need to depend on the correct parent directory.
>
> Signed-off-by: Jeff King <peff@peff.net>
> ---
> The problem starts in ab/fix-make-lint-docs, which is in master.
>
> I wasn't able to trigger the problem locally even with running 'make
> clean; make lint-docs' in a loop, but I did see it in the wild in a CI
> documentation job:
>
>   https://github.com/peff/git/runs/4005766641?check_suite_focus=true#step:4:60
>
> It would have been a lot easier to diagnose from the CI output if the
> mkdir lines weren't silent. I.e., if we had a $(QUIET_MKDIR) which
> printed "MKDIR $@" rather than nothing at all.
>
>  Documentation/Makefile | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/Makefile b/Documentation/Makefile
> index 911b6bf79c..ed656db2ae 100644
> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -472,9 +472,9 @@ print-man1:
>  ## Lint: gitlink
>  .build/lint-docs/gitlink: | .build/lint-docs
>  	$(QUIET)mkdir $@
> -.build/lint-docs/gitlink/howto: | .build/lint-docs
> +.build/lint-docs/gitlink/howto: | .build/lint-docs/gitlink
>  	$(QUIET)mkdir $@
> -.build/lint-docs/gitlink/config: | .build/lint-docs
> +.build/lint-docs/gitlink/config: | .build/lint-docs/gitlink
>  	$(QUIET)mkdir $@
>  LINT_DOCS_GITLINK = $(patsubst %.txt,.build/lint-docs/gitlink/%.ok,$(HOWTO_TXT) $(DOC_DEP_TXT))
>  $(LINT_DOCS_GITLINK): | .build/lint-docs/gitlink

Thanks a lot for fixing that bug, and sorry for not spotting it. This
fix LGTM and is obviously correct.

I'll try to do something about the $(QUIET*) as a follow-up, I was
trying to find the right balance between over-verbosity & "tracing".