FYI: more doc and example for LIBOBJS/ALLOCA

[Alexandre Duret-Lutz]

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

2004-10-31  Alexandre Duret-Lutz  <address@hidden>

        * doc/automake.texi (LIBOBJS): Augment with an example setup.
        (LTLIBOBJ): Rename as ...
        (LTLIBOBJS): ... this.  Link to LIBOBJS, and mention LTALLOCA.

Index: doc/automake.texi
===================================================================
RCS file: /cvs/automake/automake/doc/automake.texi,v
retrieving revision 1.44.2.15
diff -u -r1.44.2.15 automake.texi
--- doc/automake.texi   25 Oct 2004 19:00:06 -0000      1.44.2.15
+++ doc/automake.texi   31 Oct 2004 22:09:51 -0000
@@ -197,7 +197,7 @@
 * Libtool Convenience Libraries::  Building Convenience Libtool Libraries
 * Libtool Modules::             Building Libtool Modules
 * Libtool Flags::               Using _LIBADD and _LDFLAGS
-* LTLIBOBJ::                    Using $(LTLIBOBJ)
+* LTLIBOBJS::                   Using $(LTLIBOBJS) and $(LTALLOCA)
 * Libtool Issues::              Common Issues Related to Libtool's Use
 
 Fortran 77 Support
@@ -2977,7 +2977,7 @@
 * Libtool Convenience Libraries::  Building Convenience Libtool Libraries
 * Libtool Modules::             Building Libtool Modules
 * Libtool Flags::               Using _LIBADD and _LDFLAGS
-* LTLIBOBJ::                    Using $(LTLIBOBJ)
+* LTLIBOBJS::                   Using $(LTLIBOBJS) and $(LTALLOCA)
 * Libtool Issues::              Common Issues Related to Libtool's Use
 @end menu
 
@@ -3283,16 +3283,22 @@
 @samp{-static}, and a lot more.  See @xref{Link mode, , Using libltdl,
 libtool, The Libtool Manual}.
 
address@hidden LTLIBOBJ, Libtool Issues, Libtool Flags, A Shared Library
address@hidden @code{LTLIBOBJS}
address@hidden LTLIBOBJS, Libtool Issues, Libtool Flags, A Shared Library
address@hidden @code{LTLIBOBJS} and @code{LTALLOCA}
 @cindex @code{LTLIBOBJS}, special handling
address@hidden @code{LIBOBJS}, and Libtool
address@hidden @code{LTALLOCA}, special handling
address@hidden @code{ALLOCA}, and Libtool
 @vindex LTLIBOBJS
 @vindex LIBOBJS
address@hidden LTALLOCA
address@hidden ALLOCA
 @cvindex AC_LIBOBJ
 
-Where an ordinary library might include @code{$(LIBOBJS)}, a libtool
-library must use @code{$(LTLIBOBJS)}.  This is required because the
-object files that libtool operates on do not necessarily end in
+Where an ordinary library might include @code{$(LIBOBJS)} or
address@hidden(ALLOCA)} (@pxref{LIBOBJS}), a libtool library must use
address@hidden(LTLIBOBJS)} or @code{$(LTALLOCA)}.  This is required because
+the object files that libtool operates on do not necessarily end in
 @file{.o}.
 
 Nowadays, the computation of @code{LTLIBOBJS} from @code{LIBOBJS} is
@@ -3664,18 +3670,126 @@
 @node LIBOBJS
 @section Special handling for LIBOBJS and ALLOCA
 
address@hidden @code{LIBOBJS}, example
address@hidden @code{ALLOCA}, example
 @cindex @code{LIBOBJS}, special handling
 @cindex @code{ALLOCA}, special handling
address@hidden LTLIBOBJS
address@hidden LIBOBJS
address@hidden LTALLOCA
address@hidden ALLOCA
+
+The @code{$(LIBOBJS)} and @code{$(ALLOCA)} variables list objects
+files that should be compiled into the project to provide an
+implementation for functions that are missing or broken on the host
+system.  They are substituted by @file{configure}.
+
address@hidden AC_LIBOBJ
+
+These variables are defined by Autoconf macros such as
address@hidden, @code{AC_REPLACE_FUNCS} (@pxref{Generic Functions, ,
+Generic Function Checks, autoconf, The Autoconf Manual}), or
address@hidden (@pxref{Particular Functions, , Particular
+Function Checks, autoconf, The Autoconf Manual}).  Many other Autoconf
+macros call @code{AC_LIBOBJ} or @code{AC_REPLACE_FUNCS} to
+populate @code{$(LIBOBJS)}.
+
address@hidden AC_LIBSOURCE
+
+Using these variables is very similar to doing conditional compilation
+using @code{AC_SUBST} variables, as described in @ref{Conditional
+Sources}.  That is, when building a program @code{$(LIBOBJS)} and
address@hidden(ALLOCA)} should be added to the associated @samp{*_LDADD}
+variable, or to the @samp{*_LIBADD} variable when building a library.
+However there is no need to list the corresponding sources in
address@hidden nor to define @code{*_DEPENDENCIES}.  Automake
+automatically adds @code{$(LIBOBJS)} and @code{$(ALLOCA)} to the
+dependencies, and it will discover the list of corresponding source
+files automatically (by tracing the invocations of the
address@hidden Autoconf macros).
+
+These variables are usually used to build a portability library that
+is linked with all the programs of the project.  We now review a
+sample setup.  First, @file{configure.ac} contains some checks that
+affect either @code{LIBOBJS} or @code{ALLOCA}.
+
address@hidden
+# configure.ac
address@hidden
+AC_CONFIG_LIBOBJ_DIR([lib])
address@hidden
+AC_FUNC_MALLOC             dnl May add malloc.$(OBJEXT) to LIBOBJS
+AC_FUNC_MEMCMP             dnl May add memcmp.$(OBJEXT) to LIBOBJS
+AC_REPLACE_FUNCS([strdup]) dnl May add strdup.$(OBJEXT) to LIBOBJS
+AC_FUNC_ALLOCA             dnl May add alloca.$(OBJEXT) to ALLOCA
address@hidden
+AC_CONFIG_FILES([
+  lib/Makefile
+  src/Makefile
+])
+AC_OUTPUT
address@hidden example
+
address@hidden AC_CONFIG_LIBOBJ_DIR
+
+The @code{AC_CONFIG_LIBOBJ_DIR} tells Autoconf the source files of
+these object files are to be found in the @file{lib/} directory.
+Automake does not yet use this information; anyway it knows the source
+files are expected to be in the directory where the @code{$(LIBOBJS)}
+and @code{$(ALLOCA)} variables are used.
 
-Automake explicitly recognizes the use of @code{$(LIBOBJS)} and
address@hidden(ALLOCA)}, and uses this information, plus the list of
address@hidden files derived from @file{configure.ac} to automatically
-include the appropriate source files in the distribution (@pxref{Dist}).
-These source files are also automatically handled in the
-dependency-tracking scheme; see @xref{Dependencies}.
+The @file{lib/} directory should therefore contain @file{malloc.c},
address@hidden, @file{strdup.c}, @file{alloca.c}.  Here is its
address@hidden:
+
address@hidden
+# lib/Makefile.am
+
+noinst_LIBRARIES = libcompat.a
+libcompat_a_SOURCES =
+libcompat_a_LIBADD = $(LIBOBJS) $(ALLOCA)
address@hidden example
 
address@hidden(LIBOBJS)} and @code{$(ALLOCA)} are specially recognized in any
address@hidden or @samp{_LIBADD} variable.
+Nothing else is required.  The library can have any name, of course,
+and anyway it is not going to be installed: it just holds the
+replacement versions of the missing or broken functions so we can
+later link them in.  In many projects also include extra functions,
+specific to the project, in that library: they are simply added on
+the @code{_SOURCES} line.
+
+Finally here is how this library could be used from the @file{src/}
+directory.
+
address@hidden
+# src/Makefile.am
+
+# Link all programs in this directory with libcompat.a
+LDADD = ../lib/libcompat.a
+
+bin_PROGRAMS = tool1 tool2 @dots{}
+tool1_SOURCES = @dots{}
+tool2_SOURCES = @dots{}
address@hidden example
+
+Please note it would be wrong to use the @code{$(LIBOBJS)} or
address@hidden(ALLOCA)} in @file{src/Makefile.am}, because these variables
+contains unprefixed object names, and for instance
address@hidden(OBJEXT)} is not buildable in the @file{src/} directory.
+(Actually if you try using @code{$(LIBOBJS)} in @file{src/}, Automake
+will require a copy of @file{malloc.c}, @file{memcmp.c},
address@hidden, @file{alloca.c} here too.)
+
+Because @code{$(LIBOBJS)} and @code{$(ALLOCA)} contain object
+filenames whose name end with @code{.$(OBJEXT)}, they are not suitable
+for Libtool libraries (where the expected object extension is
address@hidden): @code{LTLIBOBJS} and @code{LTALLOCA} should be used
+instead.
+
address@hidden is defined automatically by Autoconf and should not
+be defined by hand (as in the past), however at the time of writing
address@hidden still needs to be defined from @code{ALLOCA} manually.
+See @ref{AC_LIBOBJ vs LIBOBJS, , @code{AC_LIBOBJ} vs. @code{LIBOBJS},
+autoconf, The Autoconf Manual}.
 
 
 @node Program variables
@@ -9138,3 +9252,5 @@
 @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
-- 
Alexandre Duret-Lutz