automake: Third-Party Makefiles

1 
1 23.2 Third-Party ‘Makefile’s
1 ============================
1 
1 In most projects all ‘Makefile’s are generated by Automake.  In some
1 cases, however, projects need to embed subdirectories with handwritten
1 ‘Makefile’s.  For instance, one subdirectory could be a third-party
1 project with its own build system, not using Automake.
1 
1    It is possible to list arbitrary directories in ‘SUBDIRS’ or
1 ‘DIST_SUBDIRS’ provided each of these directories has a ‘Makefile’ that
1 recognizes all the following recursive targets.
1 
1    When a user runs one of these targets, that target is run recursively
1 in all subdirectories.  This is why it is important that even
1 third-party ‘Makefile’s support them.
1 
1 ‘all’
1      Compile the entire package.  This is the default target in
1      Automake-generated ‘Makefile’s, but it does not need to be the
1      default in third-party ‘Makefile’s.
1 
1 ‘distdir’
1      Copy files to distribute into ‘$(distdir)’, before a tarball is
1      constructed.  Of course this target is not required if the
1      ‘no-dist’ option (⇒Options) is used.
1 
1      Hook::) will be passed from the outer package to the subpackage
1      when the ‘distdir’ target is invoked.  These two variables have
1      been adjusted for the directory that is being recursed into, so
1      they are ready to use.
1 
1 ‘install’
1 ‘install-data’
1 ‘install-exec’
1 ‘uninstall’
1      Install or uninstall files (⇒Install).
1 
1 ‘install-dvi’
1 ‘install-html’
1 ‘install-info’
1 ‘install-ps’
1 ‘install-pdf’
1      Install only some specific documentation format (⇒Texinfo).
1 
1 ‘installdirs’
1      Create install directories, but do not install any files.
1 
1 ‘check’
1 ‘installcheck’
1      Check the package (⇒Tests).
1 
1 ‘mostlyclean’
1 ‘clean’
1 ‘distclean’
1 ‘maintainer-clean’
1      Cleaning rules (⇒Clean).
1 
1 ‘dvi’
1 ‘pdf’
1 ‘ps’
1 ‘info’
1 ‘html’
1      Build the documentation in various formats (⇒Texinfo).
1 
1 ‘tags’
1 ‘ctags’
1      Build ‘TAGS’ and ‘CTAGS’ (⇒Tags).
1 
1    If you have ever used Gettext in a project, this is a good example of
1 how third-party ‘Makefile’s can be used with Automake.  The ‘Makefile’s
1 ‘gettextize’ puts in the ‘po/’ and ‘intl/’ directories are handwritten
1 ‘Makefile’s that implement all of these targets.  That way they can be
1 added to ‘SUBDIRS’ in Automake packages.
1 
1    Directories that are only listed in ‘DIST_SUBDIRS’ but not in
1 ‘SUBDIRS’ need only the ‘distclean’, ‘maintainer-clean’, and ‘distdir’
1 rules (⇒Conditional Subdirectories).
1 
1    Usually, many of these rules are irrelevant to the third-party
1 subproject, but they are required for the whole package to work.  It’s
1 OK to have a rule that does nothing, so if you are integrating a
1 third-party project with no documentation or tag support, you could
1 simply augment its ‘Makefile’ as follows:
1 
1      EMPTY_AUTOMAKE_TARGETS = dvi pdf ps info html tags ctags
1      .PHONY: $(EMPTY_AUTOMAKE_TARGETS)
1      $(EMPTY_AUTOMAKE_TARGETS):
1 
1    Another aspect of integrating third-party build systems is whether
1 they support VPATH builds (⇒VPATH Builds).  Obviously if the
1 subpackage does not support VPATH builds the whole package will not
1 support VPATH builds.  This in turns means that ‘make distcheck’ will
1 not work, because it relies on VPATH builds.  Some people can live
1 without this (actually, many Automake users have never heard of ‘make
1 distcheck’).  Other people may prefer to revamp the existing ‘Makefile’s
1 to support VPATH.  Doing so does not necessarily require Automake, only
11 Autoconf is needed (⇒Build Directories (autoconf)Build
 Directories.).  The necessary substitutions: ‘@srcdir@’, ‘@top_srcdir@’,
1 and ‘@top_builddir@’ are defined by ‘configure’ when it processes a
11 ‘Makefile’ (⇒Preset Output Variables (autoconf)Preset Output
 Variables.), they are not computed by the Makefile like the
1 aforementioned ‘$(distdir)’ and ‘$(top_distdir)’ variables.
1 
1    It is sometimes inconvenient to modify a third-party ‘Makefile’ to
1 introduce the above required targets.  For instance, one may want to
1 keep the third-party sources untouched to ease upgrades to new versions.
1 
1    Here are two other ideas.  If GNU make is assumed, one possibility is
1 to add to that subdirectory a ‘GNUmakefile’ that defines the required
1 targets and includes the third-party ‘Makefile’.  For this to work in
1 VPATH builds, ‘GNUmakefile’ must lie in the build directory; the easiest
1 way to do this is to write a ‘GNUmakefile.in’ instead, and have it
1 processed with ‘AC_CONFIG_FILES’ from the outer package.  For example if
1 we assume ‘Makefile’ defines all targets except the documentation
1 targets, and that the ‘check’ target is actually called ‘test’, we could
1 write ‘GNUmakefile’ (or ‘GNUmakefile.in’) like this:
1 
1      # First, include the real Makefile
1      include Makefile
1      # Then, define the other targets needed by Automake Makefiles.
1      .PHONY: dvi pdf ps info html check
1      dvi pdf ps info html:
1      check: test
1 
1    A similar idea that does not use ‘include’ is to write a proxy
1 ‘Makefile’ that dispatches rules to the real ‘Makefile’, either with
1 ‘$(MAKE) -f Makefile.real $(AM_MAKEFLAGS) target’ (if it’s OK to rename
1 the original ‘Makefile’) or with ‘cd subdir && $(MAKE) $(AM_MAKEFLAGS)
1 target’ (if it’s OK to store the subdirectory project one directory
1 deeper).  The good news is that this proxy ‘Makefile’ can be generated
1 with Automake.  All we need are ‘-local’ targets (⇒Extending)
1 that perform the dispatch.  Of course the other Automake features are
1 available, so you could decide to let Automake perform distribution or
1 installation.  Here is a possible ‘Makefile.am’:
1 
1      all-local:
1              cd subdir && $(MAKE) $(AM_MAKEFLAGS) all
1      check-local:
1              cd subdir && $(MAKE) $(AM_MAKEFLAGS) test
1      clean-local:
1              cd subdir && $(MAKE) $(AM_MAKEFLAGS) clean
1 
1      # Assuming the package knows how to install itself
1      install-data-local:
1              cd subdir && $(MAKE) $(AM_MAKEFLAGS) install-data
1      install-exec-local:
1              cd subdir && $(MAKE) $(AM_MAKEFLAGS) install-exec
1      uninstall-local:
1              cd subdir && $(MAKE) $(AM_MAKEFLAGS) uninstall
1 
1      # Distribute files from here.
1      EXTRA_DIST = subdir/Makefile subdir/program.c ...
1 
1    Pushing this idea to the extreme, it is also possible to ignore the
1 subproject build system and build everything from this proxy
1 ‘Makefile.am’.  This might sound very sensible if you need VPATH builds
1 but the subproject does not support them.
1