FYI: document how to link a program with a library

[Alexandre Duret-Lutz]

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

2005-02-26  Alexandre Duret-Lutz  <address@hidden>

        * doc/automake.texi (A Library, Libtool Libraries): Show how to link
        a program with a static or libtool library.
        (Program and Library Variables): Make clearer that _LDADD and
        _LIBADD may also list libraries.
        Prompted by a mail from Bruce Korb.

Index: doc/automake.texi
===================================================================
RCS file: /cvs/automake/automake/doc/automake.texi,v
retrieving revision 1.100
diff -u -r1.100 automake.texi
--- doc/automake.texi   26 Feb 2005 10:33:10 -0000      1.100
+++ doc/automake.texi   26 Feb 2005 21:18:38 -0000
@@ -3378,6 +3378,20 @@
 building an empty library is not portable, you should ensure that any
 library contains always at least one object.
 
+To use a static library when building a program, add it to
address@hidden for this program.  In the following example, the program
address@hidden is statically linked with the library @file{libcpio.a}.
+
address@hidden
+noinst_LIBRARIES = libcpio.a
+libcpio_a_SOURCES = @dots{}
+
+bin_PROGRAMS = cpio
+cpio_SOURCES = cpio.c @dots{}
+cpio_LDADD = libcpio.a
address@hidden example
+
+
 @node A Shared Library
 @section Building a Shared Library
 
@@ -3474,6 +3488,38 @@
 @code{pkglib_LTLIBRARIES} to install libraries in
 @code{$(libdir)/@@PACKAGE@@/}.
 
+If @file{gettext.h} is a public header file that needs to be installed
+in order for people to use the library, it should be declared using a
address@hidden variable, not in @code{libgettext_la_SOURCES}.
+Headers listed in the latter should be internal headers that are not
+part of the public interface.
+
address@hidden
+lib_LTLIBRARIES = libgettext.la
+libgettext_la_SOURCES = gettext.c @dots{}
+include_HEADERS = gettext.h @dots{}
address@hidden example
+
+A package can build and install such a library along with other
+programs that use it.  This dependency should be specified using
address@hidden  The following example builds a program named
address@hidden that is linked with @code{libgettext.la}.
+
address@hidden
+lib_LTLIBRARIES = libgettext.la
+libgettext_la_SOURCES = gettext.c @dots{}
+
+bin_PROGRAMS = hello
+hello_SOURCES = hello.c @dots{}
+hello_LDADD = libgettext.la
address@hidden example
+
address@hidden
+Whether @file{hello} is statically or dynamically linked with
address@hidden is not yet known: this will depend on the
+configuration of libtool and the capabilities of the host.
+
+
 @node Conditional Libtool Libraries
 @subsection Building Libtool Libraries Conditionally
 @cindex libtool libraries, conditional
@@ -3939,8 +3985,12 @@
 variable.  For instance this should be used for objects determined by
 @code{configure} (@pxref{A Library}).
 
+In the case of libtool libraries, @code{maude_LIBADD} can also refer
+to other libtool libraries.
+
 @item maude_LDADD
-Extra objects can be added to a @emph{program} by listing them in the
+Extra objects (@file{*.$(OBJDIR)}) and libraries (@file{*.a},
address@hidden) can be added to a @emph{program} by listing them in the
 @samp{_LDADD} variable.  For instance this should be used for objects
 determined by @code{configure} (@pxref{Linking}).
 

-- 
Alexandre Duret-Lutz