automake: Libtool Convenience Libraries

1 
1 8.3.5 Libtool Convenience Libraries
1 -----------------------------------
1 
1 Sometimes you want to build libtool libraries that should not be
1 installed.  These are called “libtool convenience libraries” and are
1 typically used to encapsulate many sublibraries, later gathered into one
1 big installed library.
1 
1    Libtool convenience libraries are declared by directory-less
1 variables such as ‘noinst_LTLIBRARIES’, ‘check_LTLIBRARIES’, or even
1 ‘EXTRA_LTLIBRARIES’.  Unlike installed libtool libraries they do not
1 need an ‘-rpath’ flag at link time (actually this is the only
1 difference).
1 
1    Convenience libraries listed in ‘noinst_LTLIBRARIES’ are always
1 built.  Those listed in ‘check_LTLIBRARIES’ are built only upon ‘make
1 check’.  Finally, libraries listed in ‘EXTRA_LTLIBRARIES’ are never
1 built explicitly: Automake outputs rules to build them, but if the
1 library does not appear as a Makefile dependency anywhere it won’t be
1 built (this is why ‘EXTRA_LTLIBRARIES’ is used for conditional
1 compilation).
1 
1    Here is a sample setup merging libtool convenience libraries from
1 subdirectories into one main ‘libtop.la’ library.
1 
1      # -- Top-level Makefile.am --
1      SUBDIRS = sub1 sub2 ...
1      lib_LTLIBRARIES = libtop.la
1      libtop_la_SOURCES =
1      libtop_la_LIBADD = \
1        sub1/libsub1.la \
1        sub2/libsub2.la \
1        ...
1 
1      # -- sub1/Makefile.am --
1      noinst_LTLIBRARIES = libsub1.la
1      libsub1_la_SOURCES = ...
1 
1      # -- sub2/Makefile.am --
1      # showing nested convenience libraries
1      SUBDIRS = sub2.1 sub2.2 ...
1      noinst_LTLIBRARIES = libsub2.la
1      libsub2_la_SOURCES =
1      libsub2_la_LIBADD = \
1        sub21/libsub21.la \
1        sub22/libsub22.la \
1        ...
1 
1    When using such setup, beware that ‘automake’ will assume ‘libtop.la’
1 is to be linked with the C linker.  This is because ‘libtop_la_SOURCES’
1 is empty, so ‘automake’ picks C as default language.  If
1 ‘libtop_la_SOURCES’ was not empty, ‘automake’ would select the linker as
1 explained in ⇒How the Linker is Chosen.
1 
1    If one of the sublibraries contains non-C source, it is important
1 that the appropriate linker be chosen.  One way to achieve this is to
1 pretend that there is such a non-C file among the sources of the
1 library, thus forcing ‘automake’ to select the appropriate linker.  Here
1 is the top-level ‘Makefile’ of our example updated to force C++ linking.
1 
1      SUBDIRS = sub1 sub2 ...
1      lib_LTLIBRARIES = libtop.la
1      libtop_la_SOURCES =
1      # Dummy C++ source to cause C++ linking.
1      nodist_EXTRA_libtop_la_SOURCES = dummy.cxx
1      libtop_la_LIBADD = \
1        sub1/libsub1.la \
1        sub2/libsub2.la \
1        ...
1 
1    ‘EXTRA_*_SOURCES’ variables are used to keep track of source files
1 that might be compiled (this is mostly useful when doing conditional
1 compilation using ‘AC_SUBST’, ⇒Conditional Libtool Sources), and
1 the ‘nodist_’ prefix means the listed sources are not to be distributed
1 (⇒Program and Library Variables).  In effect the file ‘dummy.cxx’
1 does not need to exist in the source tree.  Of course if you have some
1 real source file to list in ‘libtop_la_SOURCES’ there is no point in
1 cheating with ‘nodist_EXTRA_libtop_la_SOURCES’.
1