Eric Blake <ebb9 <at> byu.net> writes:
> > I'm not trying to solve anything. I'm trying to suggest CFLAGS's
> > meaning should be documented in a place where maintainers might look
> > during development. I don't see how it hurts to add a sentence or two.
>
> The automake manual already mentions this, but yes, I agree that adding
> another sentence in the autoconf manual can't hurt.
Done as follows, with some liberal copy-n-paste from automake as the basis for
this patch.
>From bf9349266bd3c4d80b27d7668fc03869df404924 Mon Sep 17 00:00:00 2001
From: Eric Blake <e...@byu.net>
Date: Tue, 3 Feb 2009 09:15:54 -0700
Subject: [PATCH] Mention that packagers should not pre-set CFLAGS.
* doc/autoconf.texi (Preset Output Variables) <CFLAGS>: Copy
advice given by automake on handling variables reserved by GNU
Coding Standards.
Reported by Karl Berry.
Signed-off-by: Eric Blake <e...@byu.net>
---
ChangeLog | 6 ++++++
doc/autoconf.texi | 16 ++++++++++++++++
2 files changed, 22 insertions(+), 0 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index 7ae64b9..3d1cea4 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,11 @@
2009-02-03 Eric Blake <e...@byu.net>
+ Mention that packagers should not pre-set CFLAGS.
+ * doc/autoconf.texi (Preset Output Variables) <CFLAGS>: Copy
+ advice given by automake on handling variables reserved by GNU
+ Coding Standards.
+ Reported by Karl Berry.
+
Document lib64 in config.site.
* doc/autoconf.texi (Site Defaults): Fix typo in FHS sample file.
Mention use of lib64.
diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index 4e487df..a8cf779 100644
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -2351,6 +2351,22 @@ Preset Output Variables
@code{CC}, e.g., @code{CC='gcc -m64'}. Another is to put them into both
@code{CPPFLAGS} and @code{LDFLAGS}, but not into @code{CFLAGS}.
+However, remember that some @file{Makefile} variables are reserved by
+the GNU Coding Standards for the use of the ``user''---the person
+building the package. For instance, @code{CFLAGS} is one such variable.
+
+Sometimes package developers are tempted to set user variables such as
+...@code{cflags} because it appears to make their job easier. However, the
+package itself should never set a user variable, particularly not to
+include switches that are required for proper compilation of the
+package. Since these variables are documented as being for the package
+builder, that person rightfully expects to be able to override any of
+these variables at build time. If the package developer needs to add
+switches without interfering with the user, the proper way to do that is
+to introduce an additional variable. Automake makes this easy by
+introducing @code{AM_CFLAGS} (@pxref{Flag Variables Ordering, , ,
+automake, @acronym{GNU} Automake}), but the concept is the same even if
+Automake is not used.
@end defvar
@defvar configure_input
--
1.6.0.4
