From: Karl Berry <karl@freefriends.org>
Date: Fri, 12 Feb 2021 02:05:15 +0000 (-0800)
Subject: doc: user flags last does not always allow overriding.
X-Git-Tag: v1.16.4~29
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=89a76c9cc283d3f2785548feca6da13571d726a7;p=thirdparty%2Fautomake.git

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

diff --git a/doc/automake.texi b/doc/automake.texi
index 68b015151..c8501aaaf 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@@