FYI: doc for integrating non-Automake Makefiles

[Alexandre Duret-Lutz]

I'm installing this on HEAD and branch-1-8.

2004-01-28  Alexandre Duret-Lutz  <address@hidden>

        * doc/automake.texi (Not Enough, Third-Party Makefiles): New nodes.
        (Extending): Make it a subsection of Not Enough.

Index: doc/automake.texi
===================================================================
RCS file: /cvs/automake/automake/doc/automake.texi,v
retrieving revision 1.23
diff -u -r1.23 automake.texi
--- doc/automake.texi   20 Jan 2004 21:57:42 -0000      1.23
+++ doc/automake.texi   28 Jan 2004 17:03:58 -0000
@@ -105,7 +105,7 @@
 * Conditionals::                Conditionals
 * Gnits::                       The effect of @code{--gnu} and @code{--gnits}
 * Cygnus::                      The effect of @code{--cygnus}
-* Extending::                   Extending Automake
+* Not Enough::                  When Automake is not Enough
 * Distributing::                Distributing the Makefile.in
 * API versioning::              About compatibility between Automake versions
 * Upgrading::                   Upgrading to a Newer Automake Version
@@ -232,6 +232,11 @@
 * Suffixes::                    Handling new file extensions
 * Multilibs::                   Support for multilibs.
 
+When Automake Isn't Enough
+
+* Extending::                   Adding new rules or overriding existing ones.
+* Third-Party Makefiles::       Integrating Non-Automake @file{Makefile}s.
+
 Frequently Asked Questions about Automake
 
 * CVS::                         CVS and generated files
@@ -6234,9 +6239,20 @@
 removed.
 
 
address@hidden Extending
address@hidden Not Enough
 @chapter When Automake Isn't Enough
 
+In some situations, where Automake is not up to one task, one has to
+resort to handwritten rules or even handwritten @file{Makefile}s.
+
address@hidden
+* Extending::                   Adding new rules or overriding existing ones.
+* Third-Party Makefiles::       Integrating Non-Automake @file{Makefile}s.
address@hidden menu
+
address@hidden Extending
address@hidden Extending Automake Rules
+
 With some minor exceptions (like @code{_PROGRAMS} variables being
 rewritten to append @code{$(EXEEXT)}), the contents of a
 @file{Makefile.am} is copied to @file{Makefile.in} verbatim.
@@ -6385,13 +6401,192 @@
 @c FIXME should include discussion of variables you can use in these
 @c rules
 
address@hidden Third-Party Makefiles
address@hidden Third-Party @file{Makefile}s
+
address@hidden Third-party packages, interfacing with
address@hidden Interfacing with third-party packages
+
+In most projects all @file{Makefile}s are generated by Automake.  In
+some cases, however, projects need to embed subdirectories with
+handwritten @file{Makefile}s.  For instance one subdirectory could be
+a third-party project with its own build system, not using Automake.
+
+It is possible to list arbitrary directories in @code{SUBDIRS} or
address@hidden provided each of these directories has a
address@hidden that recognizes all the following recursive targets.
+
address@hidden recursive targets and third-party @file{Makefile}s
+When a user runs one of these targets, that target is run recursively
+in all subdirectories.  This is why it is important that even
+third-party @file{Makefile}s support them.
+
address@hidden @code
address@hidden all
+Compile the entire package.  This is the default target in
+Automake-generated @file{Makefile}s, but it does not need to be the
+default in third-party @file{Makefile}s.
+
address@hidden distdir
address@hidden distdir
address@hidden distdir
address@hidden top_distdir
+Copy files to distribute into @code{$(distdir)}, before a tarball is
+constructed.  Of course this target is not required if the
address@hidden option (@pxref{Options}) is used.
+
+The variables @code{$(top_distdir)} and @code{$(distdir)}
+(@pxref{Dist}) will be passed from the outer package to the subpackage
+when the @code{distdir} target is invoked.  These two variables have
+been adjusted for the directory which is being recursed into, so they
+are ready to use.
+
address@hidden install
address@hidden install-data
address@hidden install-exec
address@hidden uninstall
+Install or uninstall files (@pxref{Install}).
+
address@hidden install-info
+Install only the Texinfo documentation (@pxref{Texinfo}).
+
address@hidden installdirs
+Create install directories, but do not install any files.
+
address@hidden check
address@hidden installcheck
+Check the package (@pxref{Tests}).
+
address@hidden mostlyclean
address@hidden clean
address@hidden distclean
address@hidden maintainer-clean
+Cleaning rules (@pxref{Clean}).
+
address@hidden dvi
address@hidden pdf
address@hidden ps
address@hidden info
address@hidden html
+Build the documentation in various formats (@pxref{Texinfo}).
+
address@hidden tags
address@hidden ctags
+Build @code{TAGS} and @code{CTAGS} (@pxref{Tags}).
address@hidden table
+
+If you have ever used Gettext in a project, this is a good example of
+how third-party @file{Makefile}s can be used with Automake.  The
address@hidden @command{gettextize} puts in the @file{po/} and
address@hidden/} directories are handwritten @file{Makefile}s that
+implement all these targets.  That way they can be added to
address@hidden in Automake packages.
+
+Directories which are only listed in @code{DIST_SUBDIRS} but not in
address@hidden need only the @code{distclean},
address@hidden, and @code{distdir} rules (@pxref{Top level}).
+
+Usually, many of these rules are irrelevant to the third-party
+subproject, but they are required for the whole package to work.  It's
+OK to have a rule that does nothing, so if you are integrating a
+third-party project with no documentation or tag support, you could
+simply augment its @file{Makefile} as follows:
+
address@hidden
+EMPTY_AUTOMAKE_TARGETS = dvi pdf ps info html tags ctags
+.PHONY: $(EMPTY_AUTOMAKE_TARGETS)
+$(EMPTY_AUTOMAKE_TARGETS):
address@hidden example
+
+Another aspect of integrating third-party build systems is whether
+they support VPATH builds.  Obviously if the subpackage does not
+support VPATH builds the whole package will not support VPATH builds.
+This in turns means that @code{make distcheck} will not work, because
+it relies on VPATH builds.  Some people can live without this
+(actually, many Automake users have never heard of @code{make
+distcheck}).  Other people may prefer to revamp the existing
address@hidden to support VPATH.  Doing so does not necessarily
+require Automake, only Autoconf is needed (@pxref{Build Directories, ,
+Build Directories, autoconf, The Autoconf Manual}).  The necessary
+substitutions: @code{@@scrdir@@}, @code{@@top_srcdir@@}, and
address@hidden@@top_buildir@@} are defined by @file{configure} when it
+processes a @file{Makefile} (@pxref{Preset Output Variables, , Preset
+Output Variables, autoconf, The Autoconf Manual}), they are not
+computed by the Makefile like the aforementioned @code{$(distdir)} and
address@hidden(top_distdir)} variables..
+
+It is sometimes inconvenient to modify a third-party @file{Makefile}
+to introduce the above required targets.  For instance one may want to
+keep the third-party sources untouched to ease upgrades to new
+versions.
+
address@hidden @file{GNUmakefile} including @file{Makefile}
+Here are two other ideas.  If GNU make is assumed, one possibility is
+to add to that subdirectory a @file{GNUmakefile} that defines the
+required targets and include the third-party @file{Makefile}.  For
+this to work in VPATH builds, @file{GNUmakefile} must lie in the build
+directory; the easiest way to do this is to write a
address@hidden instead, and have it processed with
address@hidden from the outer package.  For example if we
+assume @file{Makefile} defines all targets except the documentation
+targets, and that the @code{check} target is actually called
address@hidden, we could write @file{GNUmakefile} (or
address@hidden) like this:
+
address@hidden
+# First, include the real Makefile
+include Makefile
+# Then, define the other targets needed by Automake Makefiles.
+.PHONY: dvi pdf ps info html check
+dvi pdf ps info html:
+check: test
address@hidden example
+
address@hidden Proxy @file{Makefile} for third-party packages
+A similar idea that does not use @code{include} is to write a proxy
address@hidden that dispatches rules to the real @file{Makefile},
+either with @code{$(MAKE) -f Makefile.real $(AM_MAKEFLAGS) target} (if
+it's OK to rename the original @file{Makefile}) or with @code{cd
+subdir && $(MAKE) $(AM_MAKEFLAGS) target} (if it's OK to store the
+subdirectory project one directory deeper).  The good news is that
+this proxy @file{Makefile} can be generated with Automake.  All we
+need are -local targets (@pxref{Extending}) that perform the dispatch.
+Of course the other Automake features are available, so you could
+decide to let Automake perform distribution or installation.  Here is
+a possible @file{Makefile.am}:
+
address@hidden
+all-local:
+        cd subdir && $(MAKE) $(AM_MAKEFLAGS) all
+check-local:
+        cd subdir && $(MAKE) $(AM_MAKEFLAGS) test
+clean-local:
+        cd subdir && $(MAKE) $(AM_MAKEFLAGS) clean
+
+# Assuming the package knows how to install itself
+install-data-local:
+        cd subdir && $(MAKE) $(AM_MAKEFLAGS) install-data
+install-exec-local:
+        cd subdir && $(MAKE) $(AM_MAKEFLAGS) install-exec
+uninstall-local:
+        cd subdir && $(MAKE) $(AM_MAKEFLAGS) uninstall
+
+# Distribute files from here.
+EXTRA_DIST = subdir/Makefile subdir/program.c ...
address@hidden example
+
+Pushing this idea to the extreme, it is also possible to ignore the
+subproject build system and build everything from this proxy
address@hidden  This might sounds very sensible if you need VPATH
+builds but the subproject does not support them.
+
 @node Distributing
 @chapter Distributing @file{Makefile.in}s
 
 Automake places no restrictions on the distribution of the resulting
address@hidden  We still encourage software authors to distribute
-their work under terms like those of the GPL, but doing so is not
-required to use Automake.
address@hidden  We still encourage software authors to
+distribute their work under terms like those of the GPL, but doing so
+is not required to use Automake.
 
 Some of the files that can be automatically installed via the
 @code{--add-missing} switch do fall under the address@hidden  However, these 
also
@@ -7137,3 +7332,4 @@
 @c  LocalWords:  LTLIBOBJ Libtool's libtool's libltdl dlopening itutions libbar
 @c  LocalWords:  WANTEDLIBS libhello sublibraries libtop libsub dlopened Ratfor
 @c  LocalWords:  mymodule timestamps timestamp underquoted MAKEINFOHTMLFLAGS
address@hidden  LocalWords:  GNUmakefile buildir
-- 
Alexandre Duret-Lutz