FYI: empty library doco

[Alexandre Duret-Lutz]

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

2005-01-09  Alexandre Duret-Lutz  <address@hidden>

        * doc/automake.texi (A Library, LIBOBJS): Mention that empty
        libraries are not portable.

Index: doc/automake.texi
===================================================================
RCS file: /cvs/automake/automake/doc/automake.texi,v
retrieving revision 1.84
diff -u -r1.84 automake.texi
--- doc/automake.texi   3 Jan 2005 21:32:18 -0000       1.84
+++ doc/automake.texi   9 Jan 2005 12:04:25 -0000
@@ -3082,13 +3082,14 @@
 
 @example
 noinst_LIBRARIES = libcpio.a
+libcpio_a_SOURCES = @dots{}
 @end example
 
 The sources that go into a library are determined exactly as they are
 for programs, via the @samp{_SOURCES} variables.  Note that the library
 name is canonicalized (@pxref{Canonicalization}), so the @samp{_SOURCES}
-variable corresponding to @file{liblob.a} is @samp{liblob_a_SOURCES},
-not @samp{liblob.a_SOURCES}.
+variable corresponding to @file{libcpio.a} is @samp{libcpio_a_SOURCES},
+not @samp{libcpio.a_SOURCES}.
 
 @vindex maude_LIBADD
 Extra objects can be added to a library using the
@@ -3115,6 +3116,11 @@
 @file{configure.ac}, or by defining a per-library @code{maude_AR}
 variable (@pxref{Program and Library Variables}).
 
address@hidden Empty libraries
+Be careful when selecting library components conditionally.  Because
+building an empty library is not portable, you should ensure that any
+library contains always at least one object.
+
 @node A Shared Library
 @section Building a Shared Library
 
@@ -3877,7 +3883,7 @@
 @end example
 
 @node LIBOBJS
address@hidden Special handling for LIBOBJS and ALLOCA
address@hidden Special handling for @code{LIBOBJS} and @code{ALLOCA}
 
 @cindex @code{LIBOBJS}, example
 @cindex @code{ALLOCA}, example
@@ -3959,12 +3965,21 @@
 libcompat_a_LIBADD = $(LIBOBJS) $(ALLOCA)
 @end example
 
-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.
+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.
+
address@hidden Empty libraries and @code{$(LIBOBJS)}
address@hidden @code{$(LIBOBJS)} and empty libraries
+There is a small trap here, though: @code{$(LIBOBJS)} and
address@hidden(ALLOCA)} might be empty, and building an empty library is not
+portable.  You should ensure that there is always something to put in
address@hidden  Most projects will also add some utility
+functions in that directory, and list them in
address@hidden, so in practice @file{libcompat.a} cannot
+be empty.
 
 Finally here is how this library could be used from the @file{src/}
 directory.
-- 
Alexandre Duret-Lutz