Some more documentation on the automake variables. I think I'm finally seeing the light...

[[Imported from SVN: r5781]]

doc/buildsystem/buildsystem.tex

@@ -551,136 +551,255 @@ AM_CPPFLAGS = @AM_CPPFLAGS@ $(SUPERLU_CPPFLAGS)
 
 There are five classes of variables in automake-generated makefiles:
 \begin{description}
-\item[automake] Example: \texttt{AM\_CPPFLAGS}.  Values for these variables
-  are determined by \texttt{configure} and substituted by \texttt{config.sub}
-  when generating the \texttt{Makefile} from the \texttt{Makefile.in}.  To
-  make this possible, automake puts something like the following line into the
-  \texttt{Makefile.in}:
+\item[automake] Example: \texttt{AM\_CPPFLAGS}.  These variables are usually
+  undefined by default and the developer may assign them default values in the
+  \texttt{Makefile.am}:
   \begin{lstlisting}[language=make]
-AM_CPPFLAGS = @AM_CPPFLAGS@
+AM_CPPFLAGS = -DMY_DIR=`pwd`
   \end{lstlisting}
-  The names of these variables begin with \texttt{AM\_} most of the time, but
-  there are some variables which don't have that prefix.  Often these
-  variables are used as defaults for {\bf target-specific} variables (they
-  also belong to the {\bf makefile-default} class below.  In that case, the
-  \texttt{configure}-detected value for that variable can be augmented by
-  putting something like
-  \begin{lstlisting}[language=make]
-AM_CPPFLAGS = @AM_CPPFLAGS@ -DMY_DIR=`pwd`
+  {\bf Automake} variables are not automatically substituted by
+  \texttt{configure}, though it is common for the developer to
+  \lstinline[language=make]{AC_SUBST} them.  In this case a different
+  technique must be  used to assign values to them, or the substituted value
+  will be ignored.  See the {\bf configure-substituted} class below.  The
+  names of {\bf automake} variables begin with \texttt{AM\_} most of the time,
+  but there are some variables which don't have that prefix.  These variables
+  give defaults for {\bf target-specific} variables.
+\item[configure-substituted] Example: \lstinline[language=make]{srcdir}.
+  Anything can be made a {\bf configure-substituted} variable by calling
+  \lstinline[language=sh]{AC_SUBST} in \texttt{configure.ac}.  Some
+  variables always substituted by autoconf\footnote{autoconf manual, section
+    ``Preset Output Variables''} or automake, others are only substituted when
+  certain autoconf macros are used.  In Dune, it is quiet common to substitute
+  {\bf automake} variables:
+  \begin{lstlisting}[language=sh]
+AC_SUBST(AM_CPPFLAGS, $DUNE_CPPFLAGS)
   \end{lstlisting}
-  in the \texttt{Makefile.am}.  Automake will then put this line into the
-  \texttt{Makefile.in} instead of the default one.
-\item[makefile-default] Example: \texttt{LDADD}.  These variables usually
-  provide default values and can be overridden by {\bf target-specific}
-  variables.  If they are {\bf automake} variables, a default value will be
-  provided by \texttt{configure}.  Otherwise, they are per default undefined
-  and the developer can give them a default value in the \texttt{Makefile.am}:
+  %$\end{lstlisting}
+  The value substituted by \texttt{configure} can be augmented in the
+  \texttt{Makefile.am} like this:
   \begin{lstlisting}[language=make]
-LDADD = -lm
+AM_CPPFLAGS = @AM_CPPFLAGS@ -DMY_DIR=`pwd`
   \end{lstlisting}
 \item[target-specific] Example: \texttt{\textit{target}\_CPPFLAGS}.  The names
   of these variables are of the form canonical target name followed by an
-  underscore followed some uppercase letters.  If there is a {\bf
-    makefile-default} variable corresponding to this {\bf target-specific}
-  variable, the uppercase letters at the end of the name usually correspond to
-  the name of that {\bf makefile-default} variable.  These variables provide
-  target-specific information.  They are defined by the developer in the
-  \texttt{Makefile.am} and are documented in the automake manual.  If there is
-  corresponding a {\bf makefile-default} variable it provides a default which
-  is used when the {\bf target-specific} is not defined.  Example definition:
+  underscore followed some uppercase letters.  If there is a {\bf automake}
+  variable corresponding to this {\bf target-specific} variable, the uppercase
+  letters at the end of the name usually correspond to the name of that {\bf
+    automake} variable.  These variables provide target-specific information.
+  They are defined by the developer in the \texttt{Makefile.am} and are
+  documented in the automake manual.  If there is corresponding a {\bf
+    automake} variable it provides a default which is used when the {\bf
+    target-specific} variable is not defined.  Example definition:
   \begin{lstlisting}[language=make]
 false_SOURCES = true.c
 false_CPPFLAGS = $(AM_CPPFLAGS) -DEXIT_CODE=1
   \end{lstlisting}
   %$\end{lstlisting}
+  This example also shows how to include the value of the corresponding {\bf
+    automake} variable.
 \item[user] Example: \texttt{CPPFLAGS}.  These variables are for the user to
   set on the make command line:
   \begin{lstlisting}[language=sh]
 make CPPFLAGS=-DNDEBUG
   \end{lstlisting}
   They usually augment some {\bf target-specific} or {\bf makefile-default}
-  variable in the build rules.  Often these variables are {\em precious} (see
-  autoconf manual), so the user can tell \texttt{configure} what values these
-  variables should have.  Thus, the developer should not usually set this
+  variable in the build rules.  Often these variables are {\em
+    precious}\footnote{autoconf manual,
+    \lstinline[language=sh]{AC_ARG_VAR}}, and the user can tell
+  \texttt{configure} what values these variables should have.  These variables
+  are {\bf configure-substituted}.
+
+  The developer should never set this
   variables in the \texttt{Makefile.am}, because that would override the
   user-provided values given to configure.  Instead, \texttt{configure.ac}
   must be tweaked to set a different default if the user does not give a value
   to \texttt{configure}.
-\item[external-library] Example: \texttt{\textit{LIB}\_CPPFLAGS}.  These
+\item[external-library] Example: \texttt{\textit{LIB}CPPFLAGS}.  These
   variables contain settings needed when using external libraries in a
   target.  They should be included in the value for the corresponding {\bf
     target-specific} variable
   \begin{lstlisting}[language=make]
-testprog_CPPFLAGS = $(AM_CPPFLAGS) $(SUPERLU_CPPFLAGS)
+testprog_CPPFLAGS = $(AM_CPPFLAGS) $(SUPERLUCPPFLAGS)
   \end{lstlisting}
   or the {\bf makefile-default} variable
   \begin{lstlisting}[language=make]
-AM_CPPFLAGS = @AM_CPPFLAGS@ $(SUPERLU_CPPFLAGS)
+AM_CPPFLAGS = @AM_CPPFLAGS@ $(SUPERLUCPPFLAGS)
   \end{lstlisting}
   %$\end{lstlisting}
-  Values for these variables are determined by \texttt{configure}.  Usually,
+  Values for these variables are determined by \texttt{configure}, thus they
+  are {\bf configure-substituted}.  Usually,
   \texttt{configure.ac} must call the right autoconf macro to determine these
   variables.
-\end{description}
 
+  Note that the variable name with an underscore
+  \texttt{\textit{LIB}\_CPPFLAGS} is not recommended\footnote{Autoconf
+    manual, section ``Flag Variables Ordering''}, although this pattern is
+  common.
+\end{description}
 
 Commonly used variables are:
 \begin{description}
-\item[C-preprocessor flags] \texttt{CPPFLAGS} (user), \texttt{AM\_CPPFLAGS}
-  (automake),
-  \texttt{\textit{program}\_CPPFLAGS}/\texttt{\textit{library}\_CPPFLAGS}
-  (program/library), \texttt{\textit{LIBRARY}\_CPPFLAGS} (dependend library).
-  These flags contain things like the include path \texttt{-I\textit{path}}
-  and preprocessor defines
-  \texttt{-D\textit{DEFINE}}/\texttt{-U\textit{DEFINE}}.  Include paths should
-  rarely go in the user variable.  For defines it depends on what the define
-  does: things like \texttt{NDEBUG} are a definite candidate for the user
-  variable, while \texttt{HAVE\_CONFIG\_H} is set by autoconf in
-  \texttt{AM\_CPPFLAGS}.
-\item[C++-compiler flags] \texttt{CXXFLAGS} (user), \texttt{AM\_CXXFLAGS}
-  (automake),
-  \texttt{\textit{program}\_CXXFLAGS}/\texttt{\textit{library}\_CXXFLAGS}
-  (program/library), \texttt{\textit{LIBRARY}\_CXXFLAGS} (dependend library).
-  This includes things that change the behaviour of the compiler.  Candidates
-  for the user variable are \texttt{-g}, \texttt{-Wall}, \texttt{-O3} and
-  \texttt{-funroll\_loops}.  Candidates for the other variables are
-  \texttt{-std=c++0x}.  These variables are used not only when compiling, but
-  also when calling the C++-compiler to do linking only.
-\item[C-compiler flags] \texttt{CFLAGS} (user), \texttt{AM\_CFLAGS}
-  (automake),
-  \texttt{\textit{program}\_CFLAGS}/\texttt{\textit{library}\_CFLAGS}
-  (program/library), \texttt{\textit{LIBRARY}\_CFLAGS} (dependend library).
-  Like the variables for C++-compiler, but for the plain C-compiler.  If you
-  link a library written in C to a program or library written in C++, it may
-  be neccessary to include \texttt{\textit{LIBRARY}\_CFLAGS} in
-  \texttt{\textit{program}\_CXXFLAGS}/\texttt{\textit{library}\_CXXFLAGS} or
-  \texttt{AM\_CXXFLAGS}.
-\item[linker flags] \texttt{LDFLAGS} (user), \texttt{AM\_LDFLAGS} (automake),
-  \texttt{\textit{program}\_LDFLAGS}/\texttt{\textit{library}\_LDFLAGS}
-  (program/library), \texttt{\textit{LIBRARY}\_LDFLAGS} (dependend library).
-  This variable should not contain any \texttt{-L\textit{path}} or
-  \texttt{-l\textit{library}} options -- those should go into the following
-  variables.
-\item[libraries to link to] \texttt{LIBS} (automake),
-  \texttt{\textit{program}\_LDADD}/\texttt{\textit{library}\_LIBADD}
-  (program/library), \texttt{\textit{LIBRARY}\_LIBS} (dependend library).
-  Note that there is no user variable.  This variables should contain the
-  libraries to link to -- either directly by file name
-  \texttt{\textit{path/to/library.so}} or by using the
-  \texttt{-L\textit{path}} and \texttt{-l\textit{library}} options.  If
-  \texttt{-l\textit{library}} is used, it must be preceded by a matching
-  \texttt{-L\textit{path}} (except for standard libraries like \texttt{-lm}).
-  This is especially importand for the dependend library variable
-  \texttt{\textit{LIBRARY}\_LIBS} -- otherwise different dependend libraries
-  will fight for control other the linkers search path.  It has happend that
-  one dependend library wanted to link against a library
-  \texttt{-l\textit{foo}}, which was incorrectly found in another libraries
-  linker search path.  Object files \texttt{\textit{foo}.o} should not usually
-  be directly included.
-\item[source files]
-  \texttt{\textit{program}\_SOURCES}/\texttt{\textit{library}\_SOURCES}
-  (program/library).  This is used to list the source files for a binary in a
-  \texttt{Makefile.am}.  See the automake documentation for details.
+\item[preprocessor flags] These flags are passed in any build rule that calls
+  the preprocessor.  If there is a {\bf target-specific} variable
+  \texttt{\textit{target}\_CPPFLAGS} defined, the flags are given by
+\begin{lstlisting}[language=make]
+$(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(target_CPPFLAGS) $(CPPFLAGS)
+\end{lstlisting}
+  %$\end{lstlisting}
+  otherwise
+\begin{lstlisting}[language=make]
+$(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS)
+\end{lstlisting}
+  %$\end{lstlisting}
+  is used.
+  \begin{description}
+  \item[\texttt{DEFS}] Class: {\bf configure-substituted}.  Contains all the
+    preprocessor defines from \lstinline[language=sh]{AC_DEFINE} and friends.
+    If a \texttt{config.h} header is used, contains just the value
+    \texttt{-DHAVE\_CONFIG\_H} instead.
+  \item[\texttt{DEFAULT\_INCLUDES}] Class: {\bf configure-substituted}.  This
+    variables contains a set of default include paths: \texttt{-I.},
+    \texttt{-I\$(srcdir)}, and an path to the directory of \texttt{config.h},
+    if that is used.
+  \item[\texttt{INCLUDES}] Class: {\bf automake}.  This is an obsolete
+    alternative to \texttt{AM\_CPPFLAGS}.  Use that instead.
+  \item[\texttt{\textit{target}\_CPPFLAGS}] Class: {\bf target-specific}.
+    Target-specific preprocessor flags.  If this variable exists, it overrides
+    \texttt{AM\_CPPFLAGS} and causes the renaming of object
+    files\footnote{automake manual, ``Why are object files sometimes
+      renamed?''}.
+  \item[\texttt{AM\_CPPFLAGS}] Class: {\bf automake}.  This is the makefile
+    default for any preprocessor flags.
+  \item[\texttt{CPPFLAGS}] Class: {\bf user}, {\bf configure-substituted}.
+    Flags given by the user, either to \texttt{configure} or when invoking
+    \texttt{make}.  If the user didn't provide any value to
+    \texttt{configure}, it may contain debugging and optimization options per
+    default (like \texttt{-DNDEBUG}).  The value of \texttt{CPPFLAGS} always
+    appears after the other preprocessor flags.
+  \end{description}
+
+\item[C-compiler flags] These flags are passed in any build rule that calls
+  the C compiler or the C linker.  If there is a {\bf target-specific}
+  variable \texttt{\textit{target}\_CFLAGS} defined, the flags are given by
+\begin{lstlisting}[language=make]
+$(target_CFLAGS) $(CFLAGS)
+\end{lstlisting}
+  otherwise
+\begin{lstlisting}[language=make]
+$(AM_CFLAGS) $(CFLAGS)
+\end{lstlisting}
+  is used.
+  \begin{description}
+  \item[\texttt{\textit{target}\_CFLAGS}] Class: {\bf target-specific}.
+    Target-specific C compiler flags.  If this variable exists, it overrides
+    \texttt{AM\_CFLAGS} and causes the renaming of object
+    files\footnote{automake manual, ``Why are object files sometimes
+      renamed?''}.
+  \item[\texttt{AM\_CFLAGS}] Class: {\bf automake}.  This is the makefile
+    default for any C compiler flags.
+  \item[\texttt{CFLAGS}] Class: {\bf user}, {\bf configure-substituted}.
+    Flags given by the user, either to \texttt{configure} or when invoking
+    \texttt{make}.  If the user didn't provide any value to
+    \texttt{configure}, it may contain debugging, optimization and warning
+    options per default (like \texttt{-g -O2 -Wall}).  The value of
+    \texttt{CFLAGS} always appears after the other C compiler flags.
+  \end{description}
+
+\item[C++-compiler flags] These flags are passed in any build rule that calls
+  the C++ compiler or the C++ linker.  If there is a {\bf target-specific}
+  variable \texttt{\textit{target}\_CXXFLAGS} defined, the flags are given by
+\begin{lstlisting}[language=make]
+$(target_CXXFLAGS) $(CXXFLAGS)
+\end{lstlisting}
+  otherwise
+\begin{lstlisting}[language=make]
+$(AM_CXXFLAGS) $(CXXFLAGS)
+\end{lstlisting}
+  is used.
+  \begin{description}
+  \item[\texttt{\textit{target}\_CXXFLAGS}] Class: {\bf target-specific}.
+    Target-specific C++ compiler flags.  If this variable exists, it overrides
+    \texttt{AM\_CXXFLAGS} and causes the renaming of object
+    files\footnote{automake manual, ``Why are object files sometimes
+      renamed?''}.
+  \item[\texttt{AM\_CXXFLAGS}] Class: {\bf automake}.  This is the makefile
+    default for any C++ compiler flags.
+  \item[\texttt{CXXFLAGS}] Class: {\bf user}, {\bf configure-substituted}.
+    Flags given by the user, either to \texttt{configure} or when invoking
+    \texttt{make}.  If the user didn't provide any value to
+    \texttt{configure}, it may contain debugging, optimization and warning
+    options per default (like \texttt{-g -O2 -Wall}).  The value of
+    \texttt{CXXFLAGS} always appears after the other C++ compiler flags.
+  \end{description}
+
+\item[linker flags] These flags are passed in any build rule that calls the
+  linker.  If there is a {\bf target-specific} variable
+  \texttt{\textit{target}\_LDFLAGS} defined, the flags are given by
+\begin{lstlisting}[language=make]
+$(target_LDFLAGS) $(LDFLAGS)
+\end{lstlisting}
+  otherwise
+\begin{lstlisting}[language=make]
+$(AM_LDFLAGS) $(LDFLAGS)
+\end{lstlisting}
+  is used.  These variables are inapropriate to pass any \texttt{-L} or
+  \texttt{-l} options or library files.  Use a variable from the {\em
+    libraries to link to} set to do that.
+  \begin{description}
+  \item[\texttt{\textit{target}\_LDFLAGS}] Class: {\bf target-specific}.
+    Target-specific C++ compiler flags.  If this variable exists, it overrides
+    \texttt{AM\_LDFLAGS}.  The existance of this variable does {\em not} cause
+    renaming of object files\footnote{automake manual, ``Why are object files
+      sometimes renamed?''}.
+  \item[\texttt{AM\_LDFLAGS}] Class: {\bf automake}.  This is the makefile
+    default for any linker flags.
+  \item[\texttt{LDFLAGS}] Class: {\bf user}, {\bf configure-substituted}.
+    Flags given by the user, either to \texttt{configure} or when invoking
+    \texttt{make}.  If the user didn't provide any value to
+    \texttt{configure}, it may contain debugging, optimization and warning
+    options per default.  The value of \texttt{LDFLAGS} always appears after
+    the other linker flags.
+  \end{description}
+
+\item[libraries to link to] These variables are used to determine the
+  libraries to link to.  They are passed whenever the linker is called.  When
+  linking a program, extra libraries and objects to link to are given by
+  \begin{lstlisting}[language=make]
+$(target_LDADD) $(LIBS)
+  \end{lstlisting}
+  If the {\bf target-specific} variable \texttt{\textit{target}\_LDADD} is not
+  defined, automake supplies
+  \begin{lstlisting}[language=make]
+$(target_LDADD) = $(LDADD)
+  \end{lstlisting}
+  When linking a library, extra libraries and objects to link to are given by
+  \begin{lstlisting}[language=make]
+$(target_LIBADD) $(LIBS)
+  \end{lstlisting}
+  If the {\bf target-specific} variable \texttt{\textit{target}\_LIBADD} is
+  not defined, automake defines it empty
+  \begin{lstlisting}[language=make]
+$(target_LIBADD) =
+  \end{lstlisting}
+  %$\end{lstlisting}
+  Linker flags except \texttt{-L} or \texttt{-l} are generally inapropriate
+  for there variables.
+  \begin{description}
+  \item[\texttt{\textit{target}\_LDADD}] Class: {\bf target-specific}.
+    Target-specific libraries and objects to link to {\em for programs}.  If
+    this variable does not exist, it defaults to \texttt{\$(LDADD)}.
+  \item[\texttt{LDADD}] Class: {\bf target-specific}.  Libraries and objects
+    to link to {\em for programs}.  Default for
+    \texttt{\textit{target}\_LDADD}.
+  \item[\texttt{\textit{target}\_LIBADD}] Class: {\bf target-specific}.
+    Target-specific objects to link to {\em for libraries}.  If the target is
+    a libtool library, then other libtool libraries may also be specified
+    here.  This variable has no makefile-wide default, if it does not exist
+    the empty value is assumed.
+  \item[\texttt{LIBS}] Class: {\bf automake}, {\bf configure-substituted}.
+    Libraries discovered by configure.
+  \end{description}
 \end{description}
 
 \minisec{Conditional builds}