From: Alexandre Duret-Lutz Date: Tue, 25 Nov 2003 21:48:24 +0000 (+0000) Subject: * doc/automake.texi (Extending): Elaborate on overriding. X-Git-Tag: Release-1-7f~4 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=8705c87eb9e3ca2a7d75b0012105f7eb8ed44d65;p=thirdparty%2Fautomake.git * doc/automake.texi (Extending): Elaborate on overriding. * NEWS: Likewise. Suggested by Bruno Haible. --- diff --git a/ChangeLog b/ChangeLog index 06b4d745e..e9f30fd34 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,9 @@ +2003-11-25 Alexandre Duret-Lutz + + * doc/automake.texi (Extending): Elaborate on overriding. + * NEWS: Likewise. + Suggested by Bruno Haible. + 2003-11-24 Alexandre Duret-Lutz * lib/Automake/Variable.pm (output): Add $(am__empty) to variable diff --git a/NEWS b/NEWS index fabd8d874..9fe9e3e46 100644 --- a/NEWS +++ b/NEWS @@ -209,6 +209,38 @@ New in 1.7e: - Fix ylwrap so that it does not overwrite header files that haven't changed, as the inline rule already does. + - User-defined rules override automake-defined rules for the same + targets, even when rules do not have commands. This is not new + (and was documented), however some of the automake-generated + rules have escaped this principle in former Automake versions. + Rules for the following targets are affected by this fix: + + clean, clean-am, dist-all, distclean, distclean-am, dvi, dvi-am, + info, info-am, install-data-am, install-exec-am, install-info, + install-info-am, install-man, installcheck-am, maintainer-clean, + maintainer-clean-am, mostlyclean, mostlyclean-am, pdf, pdf-am, + ps, ps-am, uninstall-am, uninstall-info, uninstall-man + + Practically it means that an attempt to supplement the dependencies + of some target, as in + + clean: my-clean-rule + + will now *silently override* the automake definition of the + rule for this target. Running `automake -Woverride' will diagnose + all such overriding definitions. + + It should be noted that almost all these targets support a *-local + variant that is meant to supplement the automake-defined rule + (See node `Extending' in the manual). The above rule should + be rewritten as + + clean-local: my-clean-rule + + These *-local targets have been documented since at least + Automake 1.2, so you should not fear the change if you have + to support multiple automake versions. + * Miscellaneous - The Automake manual is now distributed under the terms of the GNU FDL. diff --git a/doc/automake.texi b/doc/automake.texi index 4606a6432..e8b0ba2cf 100644 --- a/doc/automake.texi +++ b/doc/automake.texi @@ -5948,19 +5948,55 @@ removed. @node Extending @chapter When Automake Isn't Enough -Automake's implicit copying semantics means that many problems can be -worked around by simply adding some @code{make} targets and rules to -@file{Makefile.in}. Automake will ignore these additions. +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. + +@cindex copying semantics + +These copying semantics means that many problems can be worked around +by simply adding some @code{make} variables and rules to +@file{Makefile.am}. Automake will ignore these additions. + +@cindex conflicting definitions +@cindex rules, conflicting +@cindex variables, conflicting +@cindex definitions, conflicts + +Since a @file{Makefile.in} is built from data gathered from three +different places (@file{Makefile.am}, @file{configure.ac}, and +@command{automake} itself), it is possible to have conflicting +definitions of rules or variables. When building @file{Makefile.in} +the following priorities are respected by @command{automake} to ensure +the user always have the last word. User defined variables in +@file{Makefile.am} have priority over variables @code{AC_SUBST}ed from +@file{configure.ac}, and @code{AC_SUBST}ed variables have priority +over @command{automake}-defined variables. As far rules are +concerned, a user-defined rule overrides any +@command{automake}-defined rule for the same target. + +@cindex overriding rules +@cindex overriding semantics +@cindex rules, overriding + +These overriding semantics make it possible to fine tune some default +settings of Automake, or replace some of its rules. Overriding +Automake rules is often inadvisable, particularly in the topmost +directory of a package with subdirectories. The @code{-Woverride} +option (@pxref{Invoking Automake}) comes handy to catch overridden +definitions. + +Note that Automake does not make any difference between rules with +commands and rules that only specify dependencies. So it is not +possible to append new dependencies to an @code{automake}-defined +target without redefining the entire rule. @cindex -local targets @cindex local targets -There are some caveats to doing this. Although you can overload a -target already used by Automake, it is often inadvisable, particularly -in the topmost directory of a package with subdirectories. However, -various useful targets have a @samp{-local} version you can specify in -your @file{Makefile.in}. Automake will supplement the standard target -with these user-supplied targets. +However, various useful targets have a @samp{-local} version you can +specify in your @file{Makefile.in}. Automake will supplement the +standard target with these user-supplied targets. @trindex all @trindex all-local diff --git a/doc/stamp-vti b/doc/stamp-vti index 756386eb4..a4042ba93 100644 --- a/doc/stamp-vti +++ b/doc/stamp-vti @@ -1,4 +1,4 @@ -@set UPDATED 11 November 2003 +@set UPDATED 25 November 2003 @set UPDATED-MONTH November 2003 @set EDITION 1.7e @set VERSION 1.7e diff --git a/doc/version.texi b/doc/version.texi index 756386eb4..a4042ba93 100644 --- a/doc/version.texi +++ b/doc/version.texi @@ -1,4 +1,4 @@ -@set UPDATED 11 November 2003 +@set UPDATED 25 November 2003 @set UPDATED-MONTH November 2003 @set EDITION 1.7e @set VERSION 1.7e