(automake-1.16.info)Libtool Convenience Libraries

---

Next: Libtool Modules Prev: Conditional Libtool Sources Up: A Shared Library

---

Enter node , (file) or (file)node

8.3.5 Libtool Convenience Libraries
-----------------------------------

Sometimes you want to build libtool libraries that should not be
installed.  These are called “libtool convenience libraries” and are
typically used to encapsulate many sublibraries, later gathered into one
big installed library.

   Libtool convenience libraries are declared by directory-less
variables such as ‘noinst_LTLIBRARIES’, ‘check_LTLIBRARIES’, or even
‘EXTRA_LTLIBRARIES’.  Unlike installed libtool libraries they do not
need an ‘-rpath’ flag at link time (actually this is the only
difference).

   Convenience libraries listed in ‘noinst_LTLIBRARIES’ are always
built.  Those listed in ‘check_LTLIBRARIES’ are built only upon ‘make
check’.  Finally, libraries listed in ‘EXTRA_LTLIBRARIES’ are never
built explicitly: Automake outputs rules to build them, but if the
library does not appear as a Makefile dependency anywhere it won’t be
built (this is why ‘EXTRA_LTLIBRARIES’ is used for conditional
compilation).

   Here is a sample setup merging libtool convenience libraries from
subdirectories into one main ‘libtop.la’ library.

     # -- Top-level Makefile.am --
     SUBDIRS = sub1 sub2 ...
     lib_LTLIBRARIES = libtop.la
     libtop_la_SOURCES =
     libtop_la_LIBADD = \
       sub1/libsub1.la \
       sub2/libsub2.la \
       ...

     # -- sub1/Makefile.am --
     noinst_LTLIBRARIES = libsub1.la
     libsub1_la_SOURCES = ...

     # -- sub2/Makefile.am --
     # showing nested convenience libraries
     SUBDIRS = sub2.1 sub2.2 ...
     noinst_LTLIBRARIES = libsub2.la
     libsub2_la_SOURCES =
     libsub2_la_LIBADD = \
       sub21/libsub21.la \
       sub22/libsub22.la \
       ...

   When using such setup, beware that ‘automake’ will assume ‘libtop.la’
is to be linked with the C linker.  This is because ‘libtop_la_SOURCES’
is empty, so ‘automake’ picks C as default language.  If
‘libtop_la_SOURCES’ was not empty, ‘automake’ would select the linker as
explained in Note: How the Linker is Chosen.

   If one of the sublibraries contains non-C source, it is important
that the appropriate linker be chosen.  One way to achieve this is to
pretend that there is such a non-C file among the sources of the
library, thus forcing ‘automake’ to select the appropriate linker.  Here
is the top-level ‘Makefile’ of our example updated to force C++ linking.

     SUBDIRS = sub1 sub2 ...
     lib_LTLIBRARIES = libtop.la
     libtop_la_SOURCES =
     # Dummy C++ source to cause C++ linking.
     nodist_EXTRA_libtop_la_SOURCES = dummy.cxx
     libtop_la_LIBADD = \
       sub1/libsub1.la \
       sub2/libsub2.la \
       ...

   ‘EXTRA_*_SOURCES’ variables are used to keep track of source files
that might be compiled (this is mostly useful when doing conditional
compilation using ‘AC_SUBST’, Note: Conditional Libtool Sources), and
the ‘nodist_’ prefix means the listed sources are not to be distributed
(Note: Program and Library Variables).  In effect the file ‘dummy.cxx’
does not need to exist in the source tree.  Of course if you have some
real source file to list in ‘libtop_la_SOURCES’ there is no point in
cheating with ‘nodist_EXTRA_libtop_la_SOURCES’.