* 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
* 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
removed.
-@node Extending
+@node 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.
+
+@menu
+* Extending:: Adding new rules or overriding existing ones.
+* Third-Party Makefiles:: Integrating Non-Automake @file{Makefile}s.
+@end menu
+
+@node Extending
+@section 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.
@c FIXME should include discussion of variables you can use in these
@c rules
+@node Third-Party Makefiles
+@section Third-Party @file{Makefile}s
+
+@cindex Third-party packages, interfacing with
+@cindex 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
+@code{DIST_SUBDIRS} provided each of these directories has a
+@file{Makefile} that recognizes all the following recursive targets.
+
+@cindex 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.
+
+@table @code
+@item 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.
+
+@item distdir
+@trindex distdir
+@vindex distdir
+@vindex top_distdir
+Copy files to distribute into @code{$(distdir)}, before a tarball is
+constructed. Of course this target is not required if the
+@code{no-dist} 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.
+
+@item install
+@itemx install-data
+@itemx install-exec
+@itemx uninstall
+Install or uninstall files (@pxref{Install}).
+
+@item install-info
+Install only the Texinfo documentation (@pxref{Texinfo}).
+
+@item installdirs
+Create install directories, but do not install any files.
+
+@item check
+@itemx installcheck
+Check the package (@pxref{Tests}).
+
+@item mostlyclean
+@itemx clean
+@itemx distclean
+@itemx maintainer-clean
+Cleaning rules (@pxref{Clean}).
+
+@item dvi
+@itemx pdf
+@itemx ps
+@itemx info
+@itemx html
+Build the documentation in various formats (@pxref{Texinfo}).
+
+@item tags
+@itemx ctags
+Build @code{TAGS} and @code{CTAGS} (@pxref{Tags}).
+@end 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
+@file{Makefile}s @command{gettextize} puts in the @file{po/} and
+@file{intl/} directories are handwritten @file{Makefile}s that
+implement all these targets. That way they can be added to
+@code{SUBDIRS} in Automake packages.
+
+Directories which are only listed in @code{DIST_SUBDIRS} but not in
+@code{SUBDIRS} need only the @code{distclean},
+@code{maintainer-clean}, 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:
+
+@example
+EMPTY_AUTOMAKE_TARGETS = dvi pdf ps info html tags ctags
+.PHONY: $(EMPTY_AUTOMAKE_TARGETS)
+$(EMPTY_AUTOMAKE_TARGETS):
+@end 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
+@file{Makefile}s 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
+@code{@@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
+@code{$(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.
+
+@cindex @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
+@file{GNUmakefile.in} instead, and have it processed with
+@code{AC_CONFIG_FILES} 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
+@code{test}, we could write @file{GNUmakefile} (or
+@file{GNUmakefile.in}) like this:
+
+@example
+# 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
+@end example
+
+@cindex Proxy @file{Makefile} for third-party packages
+A similar idea that does not use @code{include} is to write a proxy
+@file{Makefile} 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}:
+
+@example
+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 ...
+@end example
+
+Pushing this idea to the extreme, it is also possible to ignore the
+subproject build system and build everything from this proxy
+@file{Makefile.am}. 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
-@file{Makefile.in}s. 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.
+@file{Makefile.in}s. 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 GPL@. However, these also
@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
+@c LocalWords: GNUmakefile buildir
git://sourceware.org / automake.git / commitdiff