From: Alexandre Duret-Lutz Date: Wed, 28 Jan 2004 17:08:33 +0000 (+0000) Subject: * doc/automake.texi (Not Enough, Third-Party Makefiles): New nodes. X-Git-Tag: Release-1-8b~71 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=ef1f2dadffe7ac7e61ebce08d1dd745eff12de5d;p=thirdparty%2Fautomake.git * doc/automake.texi (Not Enough, Third-Party Makefiles): New nodes. (Extending): Make it a subsection of Not Enough. --- diff --git a/ChangeLog b/ChangeLog index d5355a46f..200abb987 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,8 @@ 2004-01-28 Alexandre Duret-Lutz + * doc/automake.texi (Not Enough, Third-Party Makefiles): New nodes. + (Extending): Make it a subsection of Not Enough. + * lib/gnupload (GPG): Use an absolute path. Suggestion from Gary V. Vaughan. (passphrase): Unset it this variable before using it, in case it diff --git a/doc/automake.texi b/doc/automake.texi index 1f517396f..e45ccad99 100644 --- a/doc/automake.texi +++ b/doc/automake.texi @@ -105,7 +105,7 @@ published by the Free Software Foundation raise funds for * 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 @@ Miscellaneous Rules * 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 @@ more standards compliant). At that time the special Cygnus mode will be 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. @@ -6385,13 +6401,192 @@ destination directory in order to create relative links. @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 @@ -7137,3 +7332,4 @@ Note that the renaming of objects is also affected by the @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 diff --git a/doc/stamp-vti b/doc/stamp-vti index 0c9658537..452c6057f 100644 --- a/doc/stamp-vti +++ b/doc/stamp-vti @@ -1,4 +1,4 @@ -@set UPDATED 20 January 2004 +@set UPDATED 27 January 2004 @set UPDATED-MONTH January 2004 @set EDITION 1.8a @set VERSION 1.8a diff --git a/doc/version.texi b/doc/version.texi index 0c9658537..452c6057f 100644 --- a/doc/version.texi +++ b/doc/version.texi @@ -1,4 +1,4 @@ -@set UPDATED 20 January 2004 +@set UPDATED 27 January 2004 @set UPDATED-MONTH January 2004 @set EDITION 1.8a @set VERSION 1.8a