Re: RFC for new FAQ entry: Flag Variables Ordering

[Ralf Wildenhues]

* Alexandre Duret-Lutz wrote on Tue, Nov 30, 2004 at 01:49:07AM CET:
> There have been questions and even bug reports about this
> lately.  So here is an attempt to document the difference
> between CFLAGS, AM_CFLAGS, and mumble_CFLAGS, how they are
> ordered, and how they should be (or not be) used.

Good idea!

> Suggestions, clarifications, and corrections most welcome.

My set of nits:

> 26.5 Flag Variables Ordering
> ============================
> 
>      What is the difference between `AM_CFLAGS', `CFLAGS', and
>      `mumble_CFLAGS'?
> 
>      Why does `automake' outputs `CPPFLAGS' after
                           output

>      `AM_CPPFLAGS' on compile lines?  Shouldn't it be the converse?
> 
>      My `configure' adds some warning flags into `CXXFLAGS'.  In
>      one `Makefile.am' I would like to append a new flag, however if I
>      put the flag into `AM_CXXFLAGS' it is prepended to the other
>      flags, not appended.
> 
>    This section attempts to answer all these questions.  We will mostly
> discuss `CPPFLAGS' in our examples, but actually the answer holds for
> all the compile flags used in Automake: `CCASFLAGS', `CFLAGS',
> `CPPFLAGS', `CXXFLAGS', `FCFLAGS', `FFLAGS', `GCJFLAGS', `LDFLAGS',
> `LFLAGS', `RFLAGS', and `YFLAGS'.

Are you planning on cross-referencing all these variables here?
Might be a good idea.

>    `CPPFLAGS', `AM_CPPFLAGS', and `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).  `CPPFLAGS' is the user variable, `AM_CPPFLAGS' is the
  Fortran 

> default Automake variable, and `mumble_CPPFLAGS' is the variable
> specific to the `mumble' target (we call this a per-target variable).

Maybe a cross-reference to the node defining the term "per-target
variable" would be helpful here.

>    Automake always uses two of these variables when compiling C sources
> files.  When compiling an object file for the `mumble' target, the
> first variable will be `mumble_CPPFLAGS' if it is defined, or
> `AM_CPPFLAGS' otherwise.  The second variable always is `CPPFLAGS'.
                                                is always

>    In the following example,
> 
>      bin_PROGRAMS = foo bar
>      foo_SOURCES = xyz.c
>      bar_SOURCES = main.c
>      foo_CPPFLAGS = -DFOO
>      AM_CPPFLAGS = -DBAZ
> 
> `xyz.o' will be compiled with `$(foo_CPPFLAGS) $(CPPFLAGS)', (because
> `xyz.o' is part of the `foo' target), while `main.o' will be compiled
> with `$(AM_CPPFLAGS) $(CPPFLAGS)' (because there is no per-target
> variable for target `bar').
> 
>    The difference between `mumble_CPPFLAGS' and `AM_CPPFLAGS' being
> clear enough, let's focus on `CPPFLAGS'.  `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 other, is documented
                                                        ^s

> at the end of the output of `configure --help'.
>    
>    For instance someone who needs to add `/home/my/usr/include' to the
                ^,

> C compiler's search path would configure a package with
                         ^,

>      ./configure CPPFLAGS='-I /home/my/usr/include'
> 
> and this flag would be propagated to the compile rules of all
> `Makefile's.
>    
>    It is also not uncommon to override a user variable at `make'-time.
> Many installers to this with `prefix', but this can be useful with
                  do

> 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
>    
>      rm file.o
>      make CXXFLAGS=-O0 file.o
>      make
> 
>    The reason `$(CPPFLAGS)' appears after `$(AM_CPPFLAGS)' or
> `$(mumble_CPPFLAGS)' on the compile command is that users should always
                                             ^line

> have the last say.  It probably makes more sense if you think about it
> while looking at the `CXXFLAGS=-O0' above, that should supersede any
IMHO:                                        which

> other switch from `AM_CXXFLAGS' or `mumble_CXXFLAGS' (and this of
> course replaces the previous value of `CXXFLAGS').
> 
>    You should never redefine a user variable such as `CPPFLAGS' in
> `Makefile.am'.  Use `automake -Woverride' to diagnose such mistakes.
> Even something like
>      
>      CPPFLAGS = -DDATADIR=\"$(datadir)\" @CPPFLAGS@
> 
> is erroneous.  Although this preserves the configure value of
Maybe                                        configured?

> `CPPFLAGS', the definition of `DATADIR' will disappear if a user
> attempts to override `CPPFLAGS' from the `make' command line.
> 
>      AM_CPPFLAGS = -DDATADIR=\"$(datadir)\"
> 
> is all what is needed here if no per-target flags are used.
         that

>    You should also not add options to these variables from inside
> `configure', for the same reason.  Occasionally you need to modify

IMHO: You should not add ... either, ..

> these variables to perform a test, but you should reset their value
> afterward.

IMHO afterwards, but both is possible.

>    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 `AC_SUBST' them in
> `WARNINGCFLAGS'; you may also have an Autoconf macro that determines
> which compiler and which linker flags should be used to link with
                                        to

> library `libfoo', abd `AC_SUBST' these in `LIBFOOCFLAGS' and
> `LIBFOOLDFLAGS'.  Then, a `Makefile.am' could use these variables as
> follows:
>    
>      AM_CFLAGS = $(WARNINGCFLAGS)
>      bin_PROGRAMS = prog1 prog2
>      prog1_SOURCES = ...
>      prog2_SOURCES = ...
>      prog2_CFLAGS = $(LIBFOOCFLAGS) $(AM_CFLAGS)
>      prog2_LDFLAGS = $(LIBFOOLDFLAGS)
>    
>    In this example both programs will be compiled with the flags
> substituted into `$(WARNINGCFLAGS)', and `prog2' will be additionally
IMHO                                                    additionally be

> compiled with the flags required to link with `libfoo'.
> 
>    Note that listing `AM_CFLAGS' into a per-target `CFLAGS' variable is
                                   in?

> a common idiom to ensure that `AM_CFLAGS' applies to every target in a
> `Makefile.in'.
> 
>    Using variables like this gives you full control on the ordering of
                                                      over

> 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
> `prog1_CFLAGS = $(AM_CFLAGS) -no-flag'.  If all these flags had been
> forcefully appended to `CFLAGS' there would be no way to disable one
                                ^,

> flag.  Yet another reason to leave user variables to users.
> 
>    Finally, we have avoided calling the variable `LIBFOO_LDFLAGS' (with
> an underscore), because that would cause Automake thinking that this is
                                                    to think

> actually a per-target variable (like `mumble_LDFLAGS') for some
> non-declared `LIBFOO' target.

Regards,
Ralf