PR/346

[Alexandre Duret-Lutz]

| Description:
|   Today we trace for AC_SUBST and AC_LIBOBJ.  We don't
|   have to handle (formerly opaque) macros like
|   AC_PATH_XTRA, AC_FUNC_ALLOCA, AC_FUNC_ERROR_AT_LINE, etc.
|   in any special way.
| 
|   So I suggest we don't document them, otherwise it will
|   be too hard to keep in sync with Autoconf.  For instance
|   AC_FUNC_MALLOC and AC_FUNC_REALLOC have recently been
|   changed to AC_LIBOBJ replacement files.  We shouldn't have
|   to update the manual every time it happens.

Any objection to this?

2002-08-19  Alexandre Duret-Lutz  <address@hidden>

        Fix for PR automake/346:
        * automake.texi (Optional): Supress the documentation for
        AC_PATH_XTRA, AC_FUNC_ALLOCA, AC_FUNC_ERROR_AT_LINE, AC_FUNC_FNMATCH,
        AC_FUNC_GETLOADAVG, AC_FUNC_MEMCMP, AC_FUNC_MKTIME, AC_FUNC_OBSTACK,
        AC_FUNC_STRTOD, AC_REPLACE_FUNCS, AC_REPLACE_GNU_GETOPT,
        AC_STRUCT_ST_BLOCKS, AM_WITH_REGEX, AC_CHECK_TOOL, AC_CHECK_PROG,
        AC_CHECK_PROGS, AC_PATH_PROG, and AC_PATH_PROGS.  Augment the
        documentation of AC_LIBSOURCE and AC_SUBST to explain this
        applies to any macro that calls them.

Index: automake.texi
===================================================================
RCS file: /cvs/automake/automake/automake.texi,v
retrieving revision 1.295
diff -u -r1.295 automake.texi
--- automake.texi       2 Aug 2002 19:52:05 -0000       1.295
+++ automake.texi       19 Aug 2002 14:03:49 -0000
@@ -1140,9 +1140,10 @@
 @cindex Macros Automake recognizes
 @cindex Recognized macros by Automake
 
-Automake will also recognize the use of certain macros and tailor the
-generated @file{Makefile.in} appropriately.  Currently recognized macros
-and their effects are:
+Every time Automake is run it calls Autoconf to trace
address@hidden  This way it can recognize the use of certain
+macros and tailor the generated @file{Makefile.in} appropriately.
+Currently recognized macros and their effects are:
 
 @table @code
 @item AC_CONFIG_HEADERS
@@ -1162,13 +1163,6 @@
 @cvindex AC_CONFIG_AUX_DIR
 FIXME: give complete list of things looked for in this directory
 
address@hidden AC_PATH_XTRA
-Automake will insert definitions for the variables defined by
address@hidden into each @file{Makefile.in} that builds a C program
-or library.  @xref{System Services, , System Services, autoconf, The
-Autoconf Manual}.
address@hidden AC_PATH_XTRA
-
 @item AC_CANONICAL_HOST
 Automake will ensure that @file{config.guess} and @file{config.sub}
 exist.  Also, the @file{Makefile} variables @samp{host_alias} and
@@ -1187,56 +1181,25 @@
 @vindex build_alias
 @vindex target_alias
 
address@hidden  AC_FUNC_ALLOCA
address@hidden AC_FUNC_ERROR_AT_LINE
address@hidden AC_FUNC_FNMATCH
address@hidden AC_FUNC_GETLOADAVG
address@hidden AC_FUNC_MEMCMP
address@hidden AC_FUNC_MKTIME
address@hidden AC_FUNC_OBSTACK
address@hidden AC_FUNC_STRTOD
address@hidden AC_REPLACE_FUNCS
address@hidden AC_REPLACE_GNU_GETOPT
address@hidden AC_STRUCT_ST_BLOCKS
address@hidden AM_WITH_REGEX
-Automake will ensure that the appropriate dependencies are generated for
-the objects corresponding to these macros.  Also, Automake will verify
-that the appropriate source files are part of the distribution.  Note
-that Automake does not come with any of the C sources required to use
-these macros, so @code{automake -a} will not install the sources.
address@hidden Library}, for more information.  Also, see @ref{Particular
-Functions, , Particular Function Checks, autoconf, The Autoconf Manual}.
address@hidden AC_FUNC_ALLOCA
address@hidden AC_FUNC_ERROR_AT_LINE
address@hidden AC_FUNC_FNMATCH
address@hidden AC_FUNC_GETLOADAVG
address@hidden AC_FUNC_MEMCMP
address@hidden AC_FUNC_MKTIME
address@hidden AC_FUNC_OBSTACK
address@hidden AC_FUNC_STRTOD
address@hidden AC_REPLACE_FUNCS
address@hidden AC_REPLACE_GNU_GETOPT
address@hidden AC_STRUCT_ST_BLOCKS
address@hidden AM_WITH_REGEX
-
address@hidden AC_LIBOBJ
address@hidden LIBOBJS
address@hidden AC_LIBSOURCE
address@hidden AC_LIBSOURCE
 @itemx AC_LIBSOURCES
-Automake will detect statements which put @file{.o} files into
address@hidden, or pass @file{.o} files to @code{AC_LIBOBJ}, and will
-treat these additional files as if they were discovered via
address@hidden  Similarly, Automake will also distribute file
-listed in @code{AC_LIBSOURCE} and @code{AC_LIBSOURCES}.
-
-Note that assignments to @code{LIBOBJS} is a construct which is being
-phased out; they will be ignored in a future release of Automake.  You
-should call the @code{AC_LIBOBJ} macro instead.  @xref{Generic
-Functions, , Generic Function Checks, autoconf, The Autoconf Manual}.
-
address@hidden AC_LIBOBJ
+Automake will automatically distribute any file listed in
address@hidden or @code{AC_LIBSOURCES}.
+
+Note that the @code{AC_LIBOBJ} macro calls @code{AC_LIBSOURCE}.  So if
+an Autoconf macro is documented to call @code{AC_LIBOBJ([file])}, then
address@hidden will be distributed automatically by Automake.  This
+encompasses many macros like @code{AC_FUNC_ALLOCA},
address@hidden, @code{AC_REPLACE_FUNCS}, and others.
 @cvindex AC_LIBOBJ
 @cvindex AC_LIBSOURCE
 @cvindex AC_LIBSOURCES
+
+By the way, direct assignments to @code{LIBOBJS} are no longer
+supported.  You should always use @code{AC_LIBOBJ} for this purpose.
address@hidden vs LIBOBJS, , @code{AC_LIBOBJ} vs. @code{LIBOBJS},
+autoconf, The Autoconf Manual}.
 @cvindex LIBOBJS
 
 @item AC_PROG_RANLIB
@@ -1281,6 +1244,19 @@
 Autoconf Manual}.
 @cvindex AC_PROG_LEX
 
address@hidden AC_SUBST
address@hidden AC_SUBST
+The first argument is automatically defined as a variable in each
+generated @file{Makefile.in}.  @xref{Setting Output Variables, , Setting
+Output Variables, autoconf, The Autoconf Manual}.
+
+If the Autoconf manual says that a macro calls @code{AC_SUBST} for
address@hidden, or defined the output variable @var{var} then @var{var} will
+be defined in each generated @file{Makefile.in}.
+E.g. @code{AC_PATH_XTRA} defines @code{X_CFLAGS} and @code{X_LIBS}, so
+you can use the variable in any @file{Makefile.am} if
address@hidden is called.
+
 @item AM_C_PROTOTYPES
 This is required when using automatic de-ANSI-fication; see @ref{ANSI}.
 @cvindex AM_C_PROTOTYPES
@@ -1301,24 +1277,6 @@
 @samp{MAINTAINER_MODE} conditional, which you can use in your own
 @file{Makefile.am}.
 @cvindex AM_MAINTAINER_MODE
-
address@hidden AC_SUBST
address@hidden AC_CHECK_TOOL
address@hidden AC_CHECK_PROG
address@hidden AC_CHECK_PROGS
address@hidden AC_PATH_PROG
address@hidden AC_PATH_PROGS
-For each of these macros, the first argument is automatically defined as
-a variable in each generated @file{Makefile.in}.  @xref{Setting Output
-Variables, , Setting Output Variables, autoconf, The Autoconf Manual},
-and @ref{Generic Programs, , Generic Program Checks, autoconf, The
-Autoconf Manual}.
address@hidden AC_SUBST
address@hidden AC_CHECK_TOOL
address@hidden AC_CHECK_PROG
address@hidden AC_CHECK_PROGS
address@hidden AC_PATH_PROG
address@hidden AC_PATH_PROGS
 
 @end table
 
-- 
Alexandre Duret-Lutz