FYI: Flag Variables Ordering section.

[Alexandre Duret-Lutz]

I'm installing this on HEAD and branch-1-9.

2004-12-05  Alexandre Duret-Lutz  <address@hidden>

        * doc/automake.texi (Flag Variables Ordering): New section.
        (User Variables, Program and Library Variables): @xref it.

Index: doc/automake.texi
===================================================================
RCS file: /cvs/automake/automake/doc/automake.texi,v
retrieving revision 1.44.2.20
diff -u -r1.44.2.20 automake.texi
--- doc/automake.texi   24 Nov 2004 22:44:31 -0000      1.44.2.20
+++ doc/automake.texi   5 Dec 2004 13:04:29 -0000
@@ -255,6 +255,7 @@
 * maintainer-mode::             missing and AM_MAINTAINER_MODE
 * wildcards::                   Why doesn't Automake support wildcards?
 * distcleancheck::              Files left in build directory after distclean
+* Flag Variables Ordering::     CFLAGS vs. AM_CFLAGS vs. mumble_CFLAGS
 * renamed objects::             Why are object files sometimes renamed?
 * Multiple Outputs::            Writing rules for tools with many output files
 
@@ -675,6 +676,8 @@
 user variable's name.  For instance, the shadow variable for
 @code{YFLAGS} is @code{AM_YFLAGS}.
 
address@hidden Variables Ordering}, for more discussion about these
+variables and how they interact with per-target variables.
 
 @node Auxiliary Programs
 @section Programs automake might require
@@ -3600,6 +3603,9 @@
 maude_CFLAGS = @dots{} your flags @dots{} $(AM_CFLAGS)
 @end example
 
address@hidden Variables Ordering}, for more discussion about the
+interaction between user variables, @code{AM_} shadow variables, and
+per-target variables.
 
 @item maude_SHORTNAME
 On some platforms the allowable file names are very short.  In order to
@@ -7339,6 +7345,7 @@
 * maintainer-mode::             missing and AM_MAINTAINER_MODE
 * wildcards::                   Why doesn't Automake support wildcards?
 * distcleancheck::              Files left in build directory after distclean
+* Flag Variables Ordering::     CFLAGS vs. AM_CFLAGS vs. mumble_CFLAGS
 * renamed objects::             Why are object files sometimes renamed?
 * Multiple Outputs::            Writing rules for tools with many output files
 @end menu
@@ -7808,6 +7815,229 @@
 complains before you do this.  @code{distcleancheck_listfiles} is a
 way to @emph{hide} errors, not to fix them.  You can always do better.
 
address@hidden Flag Variables Ordering
address@hidden Flag Variables Ordering
address@hidden Ordering flag variables
address@hidden Flag variables, ordering
+
address@hidden
+What is the difference between @code{AM_CFLAGS}, @code{CFLAGS}, and
address@hidden
address@hidden display
+
address@hidden
+Why does @command{automake} output @code{CPPFLAGS} after
address@hidden on compile lines?  Shouldn't it be the converse?
address@hidden display
+
address@hidden
+My @file{configure} adds some warning flags into @code{CXXFLAGS}.  In
+one @file{Makefile.am} I would like to append a new flag, however if I
+put the flag into @code{AM_CXXFLAGS} it is prepended to the other
+flags, not appended.
address@hidden display
+
address@hidden Compile Flag Variables
address@hidden @code{AM_CCASFLAGS} and @code{CCASFLAGS}
address@hidden @code{AM_CFLAGS} and @code{CFLAGS}
address@hidden @code{AM_CPPFLAGS} and @code{CPPFLAGS}
address@hidden @code{AM_CXXFLAGS} and @code{CXXFLAGS}
address@hidden @code{AM_FCFLAGS} and @code{FCFLAGS}
address@hidden @code{AM_FFLAGS} and @code{FFLAGS}
address@hidden @code{AM_GCJFLAGS} and @code{GCJFLAGS}
address@hidden @code{AM_LDFLAGS} and @code{LDFLAGS}
address@hidden @code{AM_LFLAGS} and @code{LFLAGS}
address@hidden @code{AM_OBJCFLAGS} and @code{OBJCFLAGS}
address@hidden @code{AM_RFLAGS} and @code{RFLAGS}
address@hidden @code{AM_YFLAGS} and @code{YFLAGS}
address@hidden @code{CCASFLAGS} and @code{AM_CCASFLAGS}
address@hidden @code{CFLAGS} and @code{AM_CFLAGS}
address@hidden @code{CPPFLAGS} and @code{AM_CPPFLAGS}
address@hidden @code{CXXFLAGS} and @code{AM_CXXFLAGS}
address@hidden @code{FCFLAGS} and @code{AM_FCFLAGS}
address@hidden @code{FFLAGS} and @code{AM_FFLAGS}
address@hidden @code{GCJFLAGS} and @code{AM_GCJFLAGS}
address@hidden @code{LDFLAGS} and @code{AM_LDFLAGS}
address@hidden @code{LFLAGS} and @code{AM_LFLAGS}
address@hidden @code{OBJCFLAGS} and @code{AM_OBJCFLAGS}
address@hidden @code{RFLAGS} and @code{AM_RFLAGS}
address@hidden @code{YFLAGS} and @code{AM_YFLAGS}
+
+This section attempts to answer all the above questions.  We will
+mostly discuss @code{CPPFLAGS} in our examples, but actually the
+answer holds for all the compile flags used in Automake:
address@hidden, @code{CFLAGS}, @code{CPPFLAGS}, @code{CXXFLAGS},
address@hidden, @code{FFLAGS}, @code{GCJFLAGS}, @code{LDFLAGS},
address@hidden, @code{OBJCFLAGS}, @code{RFLAGS}, and @code{YFLAGS}.
+
address@hidden, @code{AM_CPPFLAGS}, and @code{mumble_CPPFLAGS} are
+three variables that can be used to pass flags to the C preprocessor
+(actually these variables are also used for other languages like C++
+or preprocessed Fortran).  @code{CPPFLAGS} is the user variable
+(@pxref{User Variables}), @code{AM_CPPFLAGS} is the Automake variable,
+and @code{mumble_CPPFLAGS} is the variable specific to the
address@hidden target (we call this a per-target variable,
+see @ref{Program and Library Variables}).
+
+Automake always uses two of these variables when compiling C sources
+files.  When compiling an object file for the @code{mumble} target,
+the first variable will be @code{mumble_CPPFLAGS} if it is defined, or
address@hidden otherwise.  The second variable is always
address@hidden
+
+In the following example,
+
address@hidden
+bin_PROGRAMS = foo bar
+foo_SOURCES = xyz.c
+bar_SOURCES = main.c
+foo_CPPFLAGS = -DFOO
+AM_CPPFLAGS = -DBAZ
address@hidden example
+
address@hidden
address@hidden will be compiled with @code{$(foo_CPPFLAGS) $(CPPFLAGS)},
+(because @file{xyz.o} is part of the @code{foo} target), while
address@hidden will be compiled with @code{$(AM_CPPFLAGS) $(CPPFLAGS)}
+(because there is no per-target variable for target @code{bar}).
+
+The difference between @code{mumble_CPPFLAGS} and @code{AM_CPPFLAGS}
+being clear enough, let's focus on @code{CPPFLAGS}.  @code{CPPFLAGS}
+is a user variable, i.e., a variable that users are entitled to modify
+in order to compile the package.  This variable, like many others,
+is documented at the end of the output of @code{configure --help}.
+
+For instance, someone who needs to add @file{/home/my/usr/include} to
+the C compiler's search path would configure a package with
+
address@hidden
+./configure CPPFLAGS='-I /home/my/usr/include'
address@hidden example
+
address@hidden
+and this flag would be propagated to the compile rules of all
address@hidden
+
+It is also not uncommon to override a user variable at
address@hidden  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
+specific object file, you can run something like
+
address@hidden
+rm file.o
+make CXXFLAGS=-O0 file.o
+make
address@hidden example
+
+The reason @code{$(CPPFLAGS)} appears after @code{$(AM_CPPFLAGS)} or
address@hidden(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 @code{CXXFLAGS=-O0} above, which
+should supersede any other switch from @code{AM_CXXFLAGS} or
address@hidden (and this of course replaces the previous value
+of @code{CXXFLAGS}).
+
+You should never redefine a user variable such as @code{CPPFLAGS} in
address@hidden  Use @code{automake -Woverride} to diagnose such
+mistakes.  Even something like
+
address@hidden
+CPPFLAGS = -DDATADIR=\"$(datadir)\" @@CPPFLAGS@@
address@hidden example
+
address@hidden
+is erroneous.  Although this preserves @file{configure}'s value of
address@hidden, the definition of @code{DATADIR} will disappear if a
+user attempts to override @code{CPPFLAGS} from the @command{make}
+command line.
+
address@hidden
+AM_CPPFLAGS = -DDATADIR=\"$(datadir)\"
address@hidden example
+
address@hidden
+is all what is needed here if no per-target flags are used.
+
+You should not add options to these variables from inside
address@hidden either, for the same reason.  Occasionally you need
+to modify these variables to perform a test, but you should reset
+their value afterwards.
+
+What we recommend is that you define extra flags in separate
+variables.  For instance you may write an Autoconf macro that computes
+a set of warning options for the C compiler, and @code{AC_SUBST} them
+in @code{WARNINGCFLAGS}; you may also have an Autoconf macro that
+determines which compiler and which linker flags should be used to
+link with library @file{libfoo}, and @code{AC_SUBST} these in
address@hidden and @code{LIBFOOLDFLAGS}.  Then, a
address@hidden could use these variables as follows:
+
address@hidden
+AM_CFLAGS = $(WARNINGCFLAGS)
+bin_PROGRAMS = prog1 prog2
+prog1_SOURCES = @dots{}
+prog2_SOURCES = @dots{}
+prog2_CFLAGS = $(LIBFOOCFLAGS) $(AM_CFLAGS)
+prog2_LDFLAGS = $(LIBFOOLDFLAGS)
address@hidden example
+
+In this example both programs will be compiled with the flags
+substituted into @code{$(WARNINGCFLAGS)}, and @code{prog2} will
+additionally be compiled with the flags required to link with
address@hidden
+
+Note that listing @code{AM_CFLAGS} in a per-target @code{CFLAGS}
+variable is a common idiom to ensure that @code{AM_CFLAGS} applies to
+every target in a @file{Makefile.in}.
+
+Using variables like this gives you full control over the ordering of
+the flags.  For instance if there is a flag in $(WARNINGCFLAGS) that
+you want to negate for a particular target, you can use something like
address@hidden = $(AM_CFLAGS) -no-flag}.  If all these flags had
+been forcefully appended to @code{CFLAGS}, there would be no way to
+disable one flag.  Yet another reason to leave user variables to
+users.
+
+Finally, we have avoided naming the variable of the example
address@hidden (with an underscore) because that would cause
+Automake to think that this is actually a per-target variable (like
address@hidden) for some non-declared @code{LIBFOO} target.
+
address@hidden Other Variables
+
+There are other variables in Automake that follow similar principles
+to allow user options.  For instance Texinfo rules (@pxref{Texinfo})
+uses @code{MAKEINFOFLAGS} and @code{AM_MAKEINFOFLAGS}.  Similarly,
+DejaGnu tests @pxref{Tests} use @code{RUNTESTDEFAULTFLAGS} and
address@hidden  The tags and ctags rules
+(@pxref{Tags}) use @code{ETAGSFLAGS}, @code{AM_ETAGSFLAGS},
address@hidden, and @code{AM_CTAGSFLAGS}.  Java rules
+(@pxref{Java}) use @code{JAVACFLAGS} and @code{AM_JAVACFLAGS}.  None
+of these rules do support per-target flags (yet).
+
+To some extent, even @code{AM_MAKEFLAGS} (@pxref{Subdirectories})
+obeys this naming scheme.  The slight difference is that
address@hidden is passed to address@hidden implicitly by
address@hidden itself.
+
+However you should not think that all variables ending with
address@hidden follow this convention.  For instance
address@hidden (@pxref{Dist}),
address@hidden (@pxref{Rebuilding} and @ref{Local Macros}),
+are two variables that are only useful to the maintainer and have no
+user counterpart.
+
address@hidden (@pxref{A Library}) is usually defined by Automake and
+has neither @code{AM_} nor per-target cousin.
+
+Finally you should not think either that the existence of a per-target
+variable implies that of an @code{AM_} variable or that of a user
+variable.  For instance the @code{mumble_LDADD} per-target variable
+overrides the global @code{LDADD} variable (which is not a user
+variable), and @code{mumble_LIBADD} exists only as a per-target
+variable.  (@pxref{Program and Library Variables}.)
+
 @node renamed objects
 @section Why are object files sometimes renamed?
 
@@ -9281,5 +9511,6 @@
 @c  LocalWords:  grep backported screenshots libgcj KB unnumberedsubsubsec pre
 @c  LocalWords:  precomputing hacky makedepend inline clearmake LD PRELOAD Rel
 @c  LocalWords:  syscalls perlhist acl pm multitable headitem fdl appendixsec
address@hidden  LocalWords:  LTALLOCA MALLOC malloc memcmp strdup alloca 
libcompat
address@hidden  LocalWords:  unprefixed buildable
address@hidden  LocalWords:  LTALLOCA MALLOC malloc memcmp strdup alloca 
libcompat xyz DFOO
address@hidden  LocalWords:  unprefixed buildable preprocessed DBAZ DDATADIR 
WARNINGCFLAGS
address@hidden  LocalWords:  LIBFOOCFLAGS LIBFOOLDFLAGS
-- 
Alexandre Duret-Lutz