Re: GNU make troubleshooting

[Alejandro Colomar]

Hi Paul,

On 2023-08-27 15:52, Paul Smith wrote:
> On Sun, 2023-08-27 at 15:47 +0200, Alejandro Colomar wrote:
>> In fact, I'm going to define .SILENT always in the Linux man-pages,
>> since V=1 is just an unnecessary duplicate for --degub=print.
>> I'll make V=1 only have the effect of redirecting stderr of certain
>> programs.
> 
> Just be aware that --debug=print is a new feature as of GNU Make 4.4.

Hmm.

> 
> You shouldn't rely on users having access to it, unless you're willing
> to recommend that version (or higher).

Well, I'm the only one developing that Makefile.  I don't expect others
to need it often, as long as I don't break it too badly.  And since I
already require some latest versions of software for development,
requiring make-4.4 is not too much of a stretch.  I can live with it.

This reminded me that Debian still has make-4.3.  I've added the
maintainer to the thread, in case they hadn't noticed that there was a
new version.

Cheers,
Alex

> 
> I reminded myself that the --trace option is a shortcut for
> --debug=print,why and so I will rework all this help text to just
> recommend this instead.  It gives you most of the information you would
> want.
> 

-- 

GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5



OpenPGP_signature
Description: OpenPGP digital signature

Re: GNU make troubleshooting

[Paul Smith]

On Sun, 2023-08-27 at 15:47 +0200, Alejandro Colomar wrote:
> In fact, I'm going to define .SILENT always in the Linux man-pages,
> since V=1 is just an unnecessary duplicate for --degub=print.
> I'll make V=1 only have the effect of redirecting stderr of certain
> programs.

Just be aware that --debug=print is a new feature as of GNU Make 4.4.

You shouldn't rely on users having access to it, unless you're willing
to recommend that version (or higher).

I reminded myself that the --trace option is a shortcut for
--debug=print,why and so I will rework all this help text to just
recommend this instead.  It gives you most of the information you would
want.

-- 
Paul D. Smith 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

Re: GNU make troubleshooting

[Paul Smith]

On Sun, 2023-08-27 at 16:33 +0300, Eli Zaretskii wrote:
> That error code 2 means file not found, and -1 means a command was
> not found or completely failed to run.  It is easy to show a couple
> of examples for each one, we see those every day.

That might be true in Windows but it's not the case in POSIX systems:

$ make
make: foobar: No such file or directory
make: *** [Makefile:3: all] Error 127

And, even 127 is just a convention which is adopted by some shells;
there's no reason why a program couldn't exit with that code as well
for example.

As for -1, that's not a valid POSIX error code.

It's true that "2" is the exit code for a shell if it fails to parse
the shell script due to a syntax error or something; maybe that's worth
mentioning.

-- 
Paul D. Smith 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

Re: GNU make troubleshooting

[Alejandro Colomar]

On 2023-08-27 15:35, Alejandro Colomar wrote:
> On 2023-08-27 15:33, Paul Smith wrote:
>> On Sun, 2023-08-27 at 09:26 -0400, Paul Smith wrote:
>>> Yes, that's a good idea to mention .SILENT.
>>
>> Actually I think I will simply recomment using --debug=print instead as
>> that's simpler.
> 
> LGTM.  That's much better, as you don't modify the Makefile,
> and seems to have been added explicitly for this reason.  :)

In fact, I'm going to define .SILENT always in the Linux man-pages,
since V=1 is just an unnecessary duplicate for --degub=print.
I'll make V=1 only have the effect of redirecting stderr of certain
programs.

Cheers,
Alex

> 
> Cheers,
> Alex
> 
>>
> 

-- 

GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5



OpenPGP_signature
Description: OpenPGP digital signature

Re: GNU make troubleshooting

[Alejandro Colomar]

On 2023-08-27 15:33, Paul Smith wrote:
> On Sun, 2023-08-27 at 09:26 -0400, Paul Smith wrote:
>> Yes, that's a good idea to mention .SILENT.
> 
> Actually I think I will simply recomment using --debug=print instead as
> that's simpler.

LGTM.  That's much better, as you don't modify the Makefile,
and seems to have been added explicitly for this reason.  :)

Cheers,
Alex

> 

-- 

GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5



OpenPGP_signature
Description: OpenPGP digital signature

Re: GNU make troubleshooting

[Eli Zaretskii]

> From: Paul Smith 
> Cc: br...@clisp.org, bug-make@gnu.org
> Date: Sun, 27 Aug 2023 09:16:59 -0400
> 
> 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:

Yes, I know.  But a single @xref after each item in the "checklist"
will be a great help, IMO.

> > 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?

That error code 2 means file not found, and -1 means a command was not
found or completely failed to run.  It is easy to show a couple of
examples for each one, we see those every day.

> > 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?

It shows the full command instead of something like

  CC foo.o

> 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.

The V=1 stuff is nowadays standard in the GNU project's makefiles, so
I think it would be a good addition.  Of course, it's your call.

Re: GNU make troubleshooting

[Paul Smith]

On Sun, 2023-08-27 at 09:26 -0400, Paul Smith wrote:
> Yes, that's a good idea to mention .SILENT.

Actually I think I will simply recomment using --debug=print instead as
that's simpler.

-- 
Paul D. Smith 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

Re: GNU make troubleshooting

[Paul Smith]

On Sun, 2023-08-27 at 15:21 +0200, Alejandro Colomar wrote:
> Maybe mention that removing .SILENT: would be necessary, if
> it is defined.  Here's what the Linux man-pages makefiles do.

Yes, that's a good idea to mention .SILENT.

I really don't want to get into documenting all the different ways that
some makefiles might enable a "debug mode".  I've seen other makefile
systems that use VERBOSE not V, and some that use DEBUG, etc.

I will mention something about checking the makefile to see if it has a
debug setting and maybe mention some common variables to set.

-- 
Paul D. Smith 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

Re: GNU make troubleshooting

[Alejandro Colomar]

Hi Paul,

On 2023-08-27 15:16, Paul Smith wrote:
> On Sun, 2023-08-27 at 08:51 +0300, Eli Zaretskii wrote:> 
>> 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.
> 

Removing the '@' is not enough.  Consider that someone might be using
.SILENT.  Maybe mention that removing .SILENT: would be necessary, if
it is defined.  Here's what the Linux man-pages makefiles do.

Cheers,
Alex


$ cat share/mk/verbose.mk 

# Copyright 2022, Alejandro Colomar 
# SPDX-License-Identifier: GPL-3.0-or-later



ifndef MAKEFILE_VERBOSE_INCLUDED
MAKEFILE_VERBOSE_INCLUDED := 1


ifdef V
HIDE_ERR :=
else
HIDE_ERR := 2>/dev/null
.SILENT:
endif


endif  # include guard


-- 

GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5


OpenPGP_signature
Description: OpenPGP digital signature

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 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

Re: GNU make troubleshooting

[Alejandro Colomar]

Hi Paul,

On 2023-08-26 18:48, Paul Smith wrote:
> I added a new appendix to the GNU make manual for troubleshooting help;
> I haven't pushed it yet.  See below.  Comments welcome.
> 
> I think the outline you provided earlier, Bruno, has the problem that a
> lot of it isn't really about troubleshooting per se, it's about how to
> write makefiles in general.  I tried to restrict this specifically to
> describing the types of problems you might see and the steps you might
> take to troubleshoot them.
> 
> I'm thinking of adding another chapter on hints and tips for writing
> good makefiles.
> 
> -
> Appendix C Troubleshooting Make and Makefiles
> *
> 
> Troubleshooting 'make' and makefiles can be tricky.  There are two
> reasons: first, makefiles are not procedural programs and many users are
> used to procedural languages and scripts.  Second, makefiles consist of
> two different syntaxes in one file: makefile syntax, that 'make' reads,
> and shell syntax, which is sent to a shell program for parsing and
> execution.
> 
>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.
> 
>The strategies for troubleshooting differ for different types of
> problems.  For issues related to how makefiles are parsed, strategies
> include:
> 
>* Using the '-p' option to show the makefile database, after
>  evaluation (*note Summary of Options: Options Summary.).
> 
>* Using the 'info' function to understand how elements of the
>  makefile are expanded (*note Functions That Control Make: Make
>  Control Functions.).
> 
>For issues related to how rules are applied, strategies include:
> 
>* Removing the '@' prefix from recipes, so you can see the commands
>  make is invoking to rebuild the target (*note Recipe Echoing:
>  Echoing.).
> 
>* Using the '--trace' option to explain which rules 'make' invokes
>  and why (*note Summary of Options: Options Summary.).
> 
>* Using the '--debug=v,i' or '-d' options to show how 'make' is
>  determining which recipes should be used, or why targets do not
>  need to be rebuilt (*note Summary of Options: Options Summary.).
> 
> * 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.
> 
> 
> C.1 Errors When Parsing Makefiles
> =
> 
> This type of error is the simplest to resolve.  The error output you
> will see will have a format like this:
> 
>  Makefile:10: *** missing separator.  Stop.
> 
>This message gives you all the information you need to address the
> error: it gives the name of the makefile (here 'Makefile') and the line
> number (here '10') in that makefile where GNU Make's parser failed.
> Following that is a description of the error.  Further explanations of
> these error messages can be found in *note Errors Generated by Make:
> Error Messages.
> 

When using .SECONDEXPANSION, this becomes a bit more tricky.  It would
be interesting to recommend to put an $(info $(SUSPECT_VARIABLE)) right
before lines where you don't see the issue at first glance.

You already mention $(info) in the overview above, but I think a
reminder here might be useful.

Cheers,
Alex



-- 

GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5


OpenPGP_signature
Description: OpenPGP digital signature