Re: GNU make troubleshooting

[Eli Zaretskii]

> From: Paul Smith <psmith@gnu.org>
> Date: Sat, 26 Aug 2023 12:48:05 -0400
> 
> I added a new appendix to the GNU make manual for troubleshooting help;
> I haven't pushed it yet.  See below.  Comments welcome.

Thanks, this sounds very useful.  Some comments below.

>    If you have problems with GNU Make, first consider the type of
> problem you are having.  Problems will generally be in one of these
> categories:
> 
>    * A syntax or other error was reported when 'make' attempted to parse
>      your makefiles.
> 
>    * A command that 'make' invoked failed (exited with a non-0 exit
>      code).
> 
>    * The command that 'make' invoked was not the one you expected.
> 
>    * 'make' was not able to find a rule to build a target.
> 
>    * 'make' rebuilds a target that you didn't think was out of date.
> 
>    * Or, 'make' did not rebuild a target that you expected it to build.

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

It is possible that just a cross-reference could be enough, since you
already have an example of an error message there, but I still suggest
to maybe include it here: the appendix is large, and describes very
different problems, so being able to quickly go to the relevant part
is invaluable IME.

> C.2 Errors Reported by Commands
> ===============================
> 
> If GNU Make parses the makefiles correctly and runs a command to rebuild
> a target, it expects that command to exit with an error code of '0' (for
> success).  Any other exit code will be reported by 'make' as a failure
> and will generate an error message with this form:
> 
>      make: *** [Makefile:10: target] Error 2
> 
>    All the information you need to find that command are given: the name
> of the makefile (here 'Makefile') and line number (here '10') of the
> command make invoked, the target (here 'target') that make was trying to
> build, and finally the exit code of the command (here '2').

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.  For the other, I would tell the reader to
look in the documentation of the failed command.

>    If the makefile doesn't provide a rule for this target, you can add
> one.  If there is a rule which you intended 'make' to use to build this
> target and it wasn't used, the most common reasons for this are:
> 
>    * The target was misspelled.  You should consider following the _DRY_
>      principle (Don't Repeat Yourself) by assigning file names (targets
>      and prerequisites) to makefile variables and using those variables
>      rather than retyping the file names.
> 
>    * The target is in a different directory.  'make' considers the
>      targets 'target' and 'dir/target' (for example) to be different
>      targets.  If you are using rules that create targets outside of the
>      current working directory, be sure you correctly prefix them with
>      their directories everywhere that they appear in the makefile.
> 
>    * A pattern rule didn't match because one of its prerequisites cannot
>      be built.  Pattern rules will only be used when *all* prerequisites
>      can be satisfied: either they exist already or 'make' can find a
>      way to build them.  If any prerequisite cannot be created, then the
>      pattern does not match and 'make' will continue looking for another
>      matching pattern.  If no matching pattern can be found, then 'make'
>      will fail.

I would add one more item: a pattern rule has an error.  It might be
included in the first item above, but it is not obvious, and pattern
rules are sometimes tricky to write.

>    To troubleshoot these issues (*note Strategies for Troubleshooting:
> Troubleshooting Strategies.), remove the '@' prefix in your recipe when
> 'make' does rebuild the target so you can see what command is being
> invoked.

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.

> Remove '@' prefixes
> -------------------
> 
> If your makefile is using the '@' prefix in recipes to prevent 'make'
> from echoing the commands it invokes (*note Recipe Echoing: Echoing.),
> the first thing you should do is remove this token so that you can see
> the full command line that 'make' is running.  This will help you
> understand what your recipe is actually doing.

And here.

Thanks!