Re: FYI: more doc and example for LIBOBJS/ALLOCA

[Ralf Wildenhues]

Nitpicking comments:

* Alexandre Duret-Lutz wrote on Sun, Oct 31, 2004 at 11:11:58PM CET:
>
> @@ -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

object

> +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

I'd put a comma after program (I did not understand the sentence at
first try).

> 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

IMVHO: tells Autoconf that the ..

> +these object files are to be found in the @file{lib/} directory.
> +Automake does not yet use this information; anyway it knows the source

I'd put the `anyway' at the very end of the sentence.

> +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

Similiarly, I'd put the `anyway' right before the colon.

> +replacement versions of the missing or broken functions so we can
> +later link them in.  In many projects also include extra functions,

.. we can link them in later.  Many projects..

> +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.)

here or there?

> +
> +Because @code{$(LIBOBJS)} and @code{$(ALLOCA)} contain object
> +filenames whose name end with @code{.$(OBJEXT)}, they are not suitable

whose names

> +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

of this 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

Regards,
Ralf