Re: GNU make troubleshooting

[Paul Smith]

On Sun, 2023-08-27 at 08:51 +0300, Eli Zaretskii wrote:
> This checklist is very useful, but to make it even more useful, it
> lacks two things:
> 
>  . an example of error message that indicates each kind of problem
>  . a cross-reference to where the details are

There is a menu of links to each type of error just below the list,
because this is a chapter node in texinfo; like:

* Menu:

* Parse Error::                 Syntax errors when parsing makefiles.
* Command Failure::             Recipe commands exit with error codes.
* Wrong Rule::                  'make' chooses the wrong rule.
* No Rule Found::               No rule was found to build a target.
* Extra Rebuilds::              Targets are rebuilt unnecessarily.
* Missing Rebuilds::            Out-of-date targets are not rebuilt.
* Troubleshooting Strategies::  Strategies used for troubleshooting issues.

Texinfo is "old school" and doesn't use the more modern wiki-style
hyperlinking where important words are annotated with hyperlinks
inline.  Instead it always uses a separate link text.

> I would suggest to add here a short description of how to interpret
> these exit codes.  The codes 2 and -1 are very frequent, so maybe
> explain them right here.

What should we explain about them?  They don't mean anything special as
far as I'm aware, any more than an exit code of "1" (probably the most
common exit code) means anything special.  I agree suggesting that the
documentation for the command that was invoked be consulted is a good
idea.

> Removing @ is not always enough.  Many makefiles nowadays need you to
> say "make V=1" to override the default verbosity level.  I suggest to
> mention that.

What does "V=1" do, that removing the "@" doesn't do?  I'm not familiar
with any makefile where "V=1" enables "extra" debugging: normally it
just disables "@".  I would prefer to avoid adding descriptions that
depend on how specific makefiles are implemented, unless that is also
described in the GNU Make manual.  Maybe I will add this trick to the
new "tips" section then that can be discussed here too.

-- 
Paul D. Smith <psmith@gnu.org>            Find some GNU make tips at:
https://www.gnu.org                       http://make.mad-scientist.net
"Please remain calm...I may be mad, but I am a professional." --Mad
Scientist