automake: Subdirectories

1 
1 7.1 Recursing subdirectories
1 ============================
1 
1 In packages using make recursion, the top level ‘Makefile.am’ must tell
1 Automake which subdirectories are to be built.  This is done via the
1 ‘SUBDIRS’ variable.
1 
1    The ‘SUBDIRS’ variable holds a list of subdirectories in which
1 building of various sorts can occur.  The rules for many targets (e.g.,
1 ‘all’) in the generated ‘Makefile’ will run commands both locally and in
1 all specified subdirectories.  Note that the directories listed in
1 ‘SUBDIRS’ are not required to contain ‘Makefile.am’s; only ‘Makefile’s
1 (after configuration).  This allows inclusion of libraries from packages
11 that do not use Automake (such as ‘gettext’; see also ⇒Third-Party
 Makefiles).
1 
1    In packages that use subdirectories, the top-level ‘Makefile.am’ is
1 often very short.  For instance, here is the ‘Makefile.am’ from the GNU
1 Hello distribution:
1 
1      EXTRA_DIST = BUGS ChangeLog.O README-alpha
1      SUBDIRS = doc intl po src tests
1 
1    When Automake invokes ‘make’ in a subdirectory, it uses the value of
1 the ‘MAKE’ variable.  It passes the value of the variable ‘AM_MAKEFLAGS’
1 to the ‘make’ invocation; this can be set in ‘Makefile.am’ if there are
1 flags you must always pass to ‘make’.
1 
1    The directories mentioned in ‘SUBDIRS’ are usually direct children of
1 the current directory, each subdirectory containing its own
1 ‘Makefile.am’ with a ‘SUBDIRS’ pointing to deeper subdirectories.
1 Automake can be used to construct packages of arbitrary depth this way.
1 
1    By default, Automake generates ‘Makefiles’ that work depth-first in
1 postfix order: the subdirectories are built before the current
1 directory.  However, it is possible to change this ordering.  You can do
1 this by putting ‘.’ into ‘SUBDIRS’.  For instance, putting ‘.’ first
1 will cause a prefix ordering of directories.
1 
1    Using
1 
1      SUBDIRS = lib src . test
1 
1 will cause ‘lib/’ to be built before ‘src/’, then the current directory
1 will be built, finally the ‘test/’ directory will be built.  It is
1 customary to arrange test directories to be built after everything else
1 since they are meant to test what has been constructed.
1 
1    In addition to the built-in recursive targets defined by Automake
1 (‘all’, ‘check’, etc.), the developer can also define his own recursive
1 targets.  That is done by passing the names of such targets as arguments
1 to the m4 macro ‘AM_EXTRA_RECURSIVE_TARGETS’ in ‘configure.ac’.
1 Automake generates rules to handle the recursion for such targets; and
1 the developer can define real actions for them by defining corresponding
1 ‘-local’ targets.
1 
1      % cat configure.ac
1      AC_INIT([pkg-name], [1.0]
1      AM_INIT_AUTOMAKE
1      AM_EXTRA_RECURSIVE_TARGETS([foo])
1      AC_CONFIG_FILES([Makefile sub/Makefile sub/src/Makefile])
1      AC_OUTPUT
1      % cat Makefile.am
1      SUBDIRS = sub
1      foo-local:
1              @echo This will be run by "make foo".
1      % cat sub/Makefile.am
1      SUBDIRS = src
1      % cat sub/src/Makefile.am
1      foo-local:
1              @echo This too will be run by a "make foo" issued either in
1              @echo the 'sub/src/' directory, the 'sub/' directory, or the
1              @echo top-level directory.
1