GNU bug report logs - #35526
misleading documentation about flag variable ordering

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 35526 in the body.
You can then email your comments to 35526 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Daniel Kahn Gillmor <dkg <at> fifthhorseman.net>
To: bug-automake <at> gnu.org
Subject: misleading documentation about flag variable ordering
Date: Wed, 01 May 2019 13:33:16 -0400

[Message part 1 (text/plain, inline)]

https://www.gnu.org/software/automake/manual/automake.html#Flag-Variables-Ordering

says:

    The reason ‘$(CPPFLAGS)’ appears after ‘$(AM_CPPFLAGS)’ or
    ‘$(mumble_CPPFLAGS)’ in the compile command is that users should
    always have the last say.

The implication here is that for any of the *FLAGS variables, later
options are inherently more effective than earlier options.

This is not the case universally.  For example -Wl,--as-needed is more
effective if it shows up earlier in the command line.  (see
https://bugs.debian.org/347650 for a libtool-related problem for that
kind of ordering/re-ordering)

It would be good if the documentation could avoid implying something
that isn't the case, because that dubious suggestion casts doubt on the
rest of the documentation (or on the user's understanding of the rest of
the buildsystem)

thanks for maintaining automake!

    --dkg

[signature.asc (application/pgp-signature, inline)]

Message #8 received at 35526 <at> debbugs.gnu.org (full text, mbox):

From: Nick Bowler <nbowler <at> draconx.ca>
To: Daniel Kahn Gillmor <dkg <at> fifthhorseman.net>
Cc: 35526 <at> debbugs.gnu.org
Subject: Re: bug#35526: misleading documentation about flag variable ordering
Date: Wed, 1 May 2019 14:28:01 -0400

On 5/1/19, Daniel Kahn Gillmor <dkg <at> fifthhorseman.net> wrote:
> https://www.gnu.org/software/automake/manual/automake.html#Flag-Variables-Ordering
> says:
>
>     The reason ‘$(CPPFLAGS)’ appears after ‘$(AM_CPPFLAGS)’ or
>     ‘$(mumble_CPPFLAGS)’ in the compile command is that users should
>     always have the last say.
>
> The implication here is that for any of the *FLAGS variables, later
> options are inherently more effective than earlier options.
>
> This is not the case universally.  For example -Wl,--as-needed is more
> effective if it shows up earlier in the command line.  (see
> https://bugs.debian.org/347650 for a libtool-related problem for that
> kind of ordering/re-ordering)

It's still mostly true, and it really is more about turning off options
that may be turned on by the package but the user does not want.  Even
in the case of --as-needed, if the package had AM_LDFLAGS = -Wl,--as-needed
the user could (in principle) cancel it with LDFLAGS = -Wl,--no-as-needed,
since the user flags appear later.  If these were reversed then the
package option would override anything the user tried to do.

But it is true that this is not universal.  Not every compiler option
has a way to cancel its effect later on the command line.  In the case
of CPPFLAGS, -I options are an example where later options are in some
sense "less effective" than earlier options.

But on the other hand, -D options are commonly placed in CPPFLAGS and
in that case their effects can be canceled and/or changed by later
options.

Since all the user-provided flags are lumped together in a single
variable they have to go _somewhere_ as a unit, and convention puts them
after the corresponding package-set flags, so compilation commands look
something like:

  cc <package-cppflags> <user-cppflags> <package-cflags> <user-cflags> \
      <operational-switches> <files>

and linking (when the C compiler is used for linking) looks like:

  cc <package-cflags> <user-cflags> <package-ldflags> <user-ldflags> \
      <operational-switches> <objects-and-libraries>

(Note that the convention puts LDFLAGS before libraries so things
like LDFLAGS=-Wl,--as-needed _should_ work as expected, libtool
issues notwithstanding).

Obviously this scheme is not perfect in every possible scenario, but
the only way to handle every possible scenario is probably to have the
user to write all the compiler commands manually, in which case there
is no point in having a build system.

> It would be good if the documentation could avoid implying something
> that isn't the case, because that dubious suggestion casts doubt on the
> rest of the documentation (or on the user's understanding of the rest of
> the buildsystem)

The manual can always be improved.  Do you have a suggestion for how to
write this paragraph to make it better?

Cheers,
  Nick

Message #11 received at 35526 <at> debbugs.gnu.org (full text, mbox):

From: Daniel Kahn Gillmor <dkg <at> fifthhorseman.net>
To: Nick Bowler <nbowler <at> draconx.ca>
Cc: 35526 <at> debbugs.gnu.org
Subject: Re: bug#35526: misleading documentation about flag variable ordering
Date: Wed, 01 May 2019 14:40:44 -0400

On Wed 2019-05-01 14:28:01 -0400, Nick Bowler wrote:
> On 5/1/19, Daniel Kahn Gillmor <dkg <at> fifthhorseman.net> wrote:
>> https://www.gnu.org/software/automake/manual/automake.html#Flag-Variables-Ordering
>> says:
>>
>>     The reason ‘$(CPPFLAGS)’ appears after ‘$(AM_CPPFLAGS)’ or
>>     ‘$(mumble_CPPFLAGS)’ in the compile command is that users should
>>     always have the last say.
 […]
> The manual can always be improved.  Do you have a suggestion for how to
> write this paragraph to make it better?

maybe replace "users should always have the last say." with:

    most configuration options for the standard toolchain can be
    overridden later on the command line, and in those circumstances the
    user should have the last say.

(including some of the nuance you've written upthread here or elsewhere
in the manual would be great too)

Thanks for the prompt and thoughtful rsponse!

       --dg

Message #14 received at 35526 <at> debbugs.gnu.org (full text, mbox):

From: Karl Berry <karl <at> freefriends.org>
To: dkg <at> fifthhorseman.net
Cc: 35526 <at> debbugs.gnu.org
Subject: Re: bug#35526: misleading documentation about flag variable ordering
Date: Tue, 9 Feb 2021 19:23:13 -0700

Back on this bug from May 2019 (https://bugs.gnu.org/35526).
Sorry for the delay.

    The implication here is that for any of the *FLAGS variables, later
    options are inherently more effective than earlier options.
    This is not the case universally.  

Granted. After reading the messages here, here's the change to the
manual I came up with. If any comments before I commit it, let me know.
Thanks. --karl

--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -12491,16 +12491,21 @@ make
 @end example
 
 The reason @samp{$(CPPFLAGS)} appears after @samp{$(AM_CPPFLAGS)} or
-@samp{$(mumble_CPPFLAGS)} in the compile command is that users
-should always have the last say.  It probably makes more sense if you
-think about it while looking at the @samp{CXXFLAGS=-O0} above, which
-should supersede any other switch from @code{AM_CXXFLAGS} or
-@code{mumble_CXXFLAGS} (and this of course replaces the previous value
-of @code{CXXFLAGS}).
-
-You should never redefine a user variable such as @code{CPPFLAGS} in
-@file{Makefile.am}.  Use @samp{automake -Woverride} to diagnose such
-mistakes.  Even something like
+@samp{$(mumble_CPPFLAGS)} in the compile command is that users should
+have the last say.  In the example above, the desire is for the
+@samp{CXXFLAGS=-O0} to supersede any other switch from
+@code{AM_CXXFLAGS} or @code{mumble_CXXFLAGS}.
+
+@c https://bugs.gnu.org/35526
+It's true that not all options to all programs can be overridden.  So
+in general, users could conceivably want to place options at arbitrary
+places in the command line, but Automake does not support this.  It
+would be difficult to make such generality comprehensible.  Being able
+to specify the final options commonly suffices.
+
+Thus, you should never redefine a user variable such as
+@code{CPPFLAGS} in @file{Makefile.am}.  Use @samp{automake -Woverride}
+to diagnose such mistakes.  Even something like
 
 @example
 CPPFLAGS = -DDATADIR=\"$(datadir)\" @@CPPFLAGS@@

compile finished at Tue Feb  9 18:20:52 2021

Message #19 received at 35526-done <at> debbugs.gnu.org (full text, mbox):

From: Karl Berry <karl <at> freefriends.org>
To: 35526-done <at> debbugs.gnu.org
Date: Fri, 12 Feb 2021 15:28:10 -0700

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.