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 <ebb9@byu.net>

diff --git a/ChangeLog b/ChangeLog
index 7ae64b948dc28b085a1d9509aadf2d92b8e0905d..3d1cea4d2270ef3659d141bc46e186d964bcff92 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,11 @@
 2009-02-03  Eric Blake  <ebb9@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 4e487df002d13f31d230afc6542106bcc3c884f5..a8cf779f9bace15a5da000f64144ad7368981215 100644 (file)
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -2351,6 +2351,22 @@ matters get tricky.  One approach to put such options directly into
 @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