Re: CFLAGS is for the user in GNU

[Eric Blake]

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 <address@hidden>
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 <address@hidden>
---
 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  <address@hidden>
 
+       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
address@hidden 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