[automake-commit] branch master updated: doc: user flags last does not always allow overriding.

[Karl Berry]

This is an automated email from the git hooks/post-receive script.

karl pushed a commit to branch master
in repository automake.

View the commit online:
https://git.savannah.gnu.org/gitweb/?p=automake.git;a=commitdiff;h=89a76c9cc283d3f2785548feca6da13571d726a7

The following commit(s) were added to refs/heads/master by this push:
     new 89a76c9  doc: user flags last does not always allow overriding.
89a76c9 is described below

commit 89a76c9cc283d3f2785548feca6da13571d726a7
Author: Karl Berry <karl@freefriends.org>
AuthorDate: Thu Feb 11 18:05:15 2021 -0800

    doc: user flags last does not always allow overriding.
    
    This change addresses https://bugs.gnu.org/35526.
    
    * doc/automake.texi (Flag Variables Ordering): recognize that
    user flags last does not always allow overriding.
---
 doc/automake.texi | 29 +++++++++++++++++------------
 1 file changed, 17 insertions(+), 12 deletions(-)

diff --git a/doc/automake.texi b/doc/automake.texi
index 68b0151..c8501aa 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -12480,8 +12480,8 @@ and this flag would be propagated to the compile rules 
of all
 
 It is also not uncommon to override a user variable at
 @command{make}-time.  Many installers do this with @code{prefix}, but
-this can be useful with compiler flags too.  For instance, if, while
-debugging a C++ project, you need to disable optimization in one
+this can be useful with compiler flags too.  For instance, while
+debugging a C++ project, if you need to disable optimization in one
 specific object file, you can run something like
 
 @example
@@ -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@@