automake: Subpackages

1 
1 7.4 Nesting Packages
1 ====================
1 
1 In the GNU Build System, packages can be nested to arbitrary depth.
1 This means that a package can embed other packages with their own
1 ‘configure’, ‘Makefile’s, etc.
1 
1    These other packages should just appear as subdirectories of their
1 parent package.  They must be listed in ‘SUBDIRS’ like other ordinary
1 directories.  However the subpackage’s ‘Makefile’s should be output by
1 its own ‘configure’ script, not by the parent’s ‘configure’.  This is
11 achieved using the ‘AC_CONFIG_SUBDIRS’ Autoconf macro (⇒
 AC_CONFIG_SUBDIRS (autoconf)Subdirectories.).
1 
1    Here is an example package for an ‘arm’ program that links with a
1 ‘hand’ library that is a nested package in subdirectory ‘hand/’.
1 
1    ‘arm’’s ‘configure.ac’:
1 
1      AC_INIT([arm], [1.0])
1      AC_CONFIG_AUX_DIR([.])
1      AM_INIT_AUTOMAKE
1      AC_PROG_CC
1      AC_CONFIG_FILES([Makefile])
1      # Call hand's ./configure script recursively.
1      AC_CONFIG_SUBDIRS([hand])
1      AC_OUTPUT
1 
1    ‘arm’’s ‘Makefile.am’:
1 
1      # Build the library in the hand subdirectory first.
1      SUBDIRS = hand
1 
1      # Include hand's header when compiling this directory.
1      AM_CPPFLAGS = -I$(srcdir)/hand
1 
1      bin_PROGRAMS = arm
1      arm_SOURCES = arm.c
1      # link with the hand library.
1      arm_LDADD = hand/libhand.a
1 
1    Now here is ‘hand’’s ‘hand/configure.ac’:
1 
1      AC_INIT([hand], [1.2])
1      AC_CONFIG_AUX_DIR([.])
1      AM_INIT_AUTOMAKE
1      AC_PROG_CC
1      AM_PROG_AR
1      AC_PROG_RANLIB
1      AC_CONFIG_FILES([Makefile])
1      AC_OUTPUT
1 
1 and its ‘hand/Makefile.am’:
1 
1      lib_LIBRARIES = libhand.a
1      libhand_a_SOURCES = hand.c
1 
1    When ‘make dist’ is run from the top-level directory it will create
1 an archive ‘arm-1.0.tar.gz’ that contains the ‘arm’ code as well as the
1 ‘hand’ subdirectory.  This package can be built and installed like any
1 ordinary package, with the usual ‘./configure && make && make install’
1 sequence (the ‘hand’ subpackage will be built and installed by the
1 process).
1 
1    When ‘make dist’ is run from the hand directory, it will create a
1 self-contained ‘hand-1.2.tar.gz’ archive.  So although it appears to be
1 embedded in another package, it can still be used separately.
1 
1    The purpose of the ‘AC_CONFIG_AUX_DIR([.])’ instruction is to force
1 Automake and Autoconf to search for auxiliary scripts in the current
1 directory.  For instance, this means that there will be two copies of
1 ‘install-sh’: one in the top-level of the ‘arm’ package, and another one
1 in the ‘hand/’ subdirectory for the ‘hand’ package.
1 
1    The historical default is to search for these auxiliary scripts in
1 the parent directory and the grandparent directory.  So if the
1 ‘AC_CONFIG_AUX_DIR([.])’ line was removed from ‘hand/configure.ac’, that
1 subpackage would share the auxiliary script of the ‘arm’ package.  This
1 may looks like a gain in size (a few kilobytes), but it is actually a
1 loss of modularity as the ‘hand’ subpackage is no longer self-contained
1 (‘make dist’ in the subdirectory will not work anymore).
1 
1    Packages that do not use Automake need more work to be integrated
1 this way.  ⇒Third-Party Makefiles.
1