Re: GNU make troubleshooting

[Bruno Haible]

Hello Dmitry,

Dmitry Goncharov wrote:
> >    I tried -d a couple of times, and it produced a ton of output, that
> >    was too much for me to make sense of. Probably 10% to 20% of the
> >    developers in general have trace filtering skills, that is, know how
> >    to extract the essential information from a heap of output. It's not
> >    part of my skills.
> 
> 
> i added a patch here https://savannah.gnu.org/bugs/index.php?64428
> which hopefully clarifies how to extract essential information from
> this output.

Thanks for trying to address this. However, your patch opens up a few
questions:

1) The title, and what does the user want?

> Appendix A Debug Output.
> 
> This section demonstrates how to simplify make debug output.

Good documentation that explains a feature or procedure should, IMO,
follow the "From the use-case to the details" principle.
https://gitlab.com/ghwiki/gnow-how/-/wikis/Documentation/Writing
The way it's written here, the user will wonder "Why should I read
this section?", "What can I expect from it?".

More broadly, here's a sketch how I could imagine a troubleshooting
chapter, with section titles *from the user's point of view* :

  Troubleshooting
  * Understanding a Makefile
    - Which are the included sub-Makefiles?
    - What is the total set of rules from the Makefile and all its included
      sub-Makefiles?
    - What's the meaning of a certain expression with function invocations?
  * Understanding a Makefile's action w.r.t. a given file system state
    - What are the values of the variables?
    - Where is the Makefile source for each command that gets executed?
    - Which actions would be executed?
    - What if a file was not present?
    - What if a file was new?
  * Understanding what happened in a build
    - Which files were created in which order?
    - Which files were read during the build? 
  * Making sense of specific error messages

I think your topic would fit in the second section, under a title such as
"Which rules would be executed, and why?"
That would be a better title than "Debug Output".

2)

> all: hello
> hello: hello.o; $(CC) -o $ $<
> hello.o: hello.c hello.d; $(CC) -MMD -MFhello.d -o $ -c $<
> hello.d:;
> include hello.d
> makefile::;
> $ make -d |tail +7 |wc
>      47     259    1931
> 
> These 47 lines are the ones that we were looking for.

What I get is:

$ make -d |tail +7 |wc
     46     250    1921
$ make -d |tail +7 |wc
     35     186    1458

So, subsequent invocations produce different results, because the state
on disk has changed. This is undesired, because when I (as a user) am
analyzing a Makefile (recall the section title
"Understanding a Makefile's action w.r.t. a given file system state"),
I do *not* want the state to be modified.

Therefore, how about changing the example to use "make -n -d" instead of
"make -d" ?

$ make -n -d |tail +7 |wc
     37     183    1434
$ make -n -d |tail +7 |wc
     37     183    1434

This way, it's reproducible.

3)

> Note, we added rule
> 
> makefile::;
> 
> This addition cut the debug output from 1338 to 730 lines.
> ...
> Finally, we can disable built-in rules Catalogue of Built-In Rules.
> 
> $ cat makefile
> MAKEFLAGS:=-r

Hey, you are modifying the Makefile in order to analyze how it works!
Is that really what I want to do and should do, as a user?

Regarding -r, I would prefer to get told to add an option:

  $ make -n -d -r |tail +7 |wc

because that allows me to continue with an unmodified Makefile.

Can the addition of 'makefile::;' be replaced by a make option or
by some (sed-based?) postprocessing?

So that we arrive at the same 37 lines with a common of the form

  $ make -n -d SOME_MORE_OPTIONS | tail +7 | SOME_MORE_FILTER

?

Bruno