Re: automake 1.7d feedback

[Alexandre Duret-Lutz <adl at src dot lip6 dot fr>]

>>> "Bruno" == Bruno Haible <bruno@clisp.org> writes:

[...]
 Bruno> However, there is an important change in behaviour that
 Bruno> IMO should be mentioned in the NEWS file (or maybe even
 Bruno> undone): While it was possible to add dependencies to
 Bruno> automake targets in automake-1.7.x, such dependencies
 Bruno> are now interpreted as *overriding* the automake
 Bruno> definition. 
[...]

Thanks for raising this.  This indeed deserves more
documentation.  I'm installing the following patch.

I sympathize with the feeling that rules without commands are
not expected to behave like rules with commands in make, and
that the more Automake follows Make the easier it is to use.
Maybe some work can be done on this in the future.  For now I
believe 1.8 is more consistent than 1.7 in this area and I'm
reluctant to change this behavior.

 1) the philosophy of Automake has always been that user definitions
    override other definitions
 2) this behavior was documented
 3) automake is not yet able to distinguish rule with commands from
    rule without commands (no kidding)
 4) in previous versions adding dependencies to a target without
    overriding it was possible only for a handful of targets (well, 
    possibly with a large hand), because the output of these rules did 
    not pass through the dedicated function to output rules.
 5) there have been a lot of work to streamline the variable and rule
    handling in Automake 1.8 (with this "fix" as a side effect), and 
    there is still a lot to do (carrying ugly hacks for bugward 
    compatibility would impede further developments)
 6) adding dependencies to these targets has been supported
    via *-local targets for eons, so we don't seem to loose
    any feature

2003-11-25  Alexandre Duret-Lutz  <adl@gnu.org>

	* doc/automake.texi (Extending): Elaborate on overriding.
	* NEWS: Likewise.
	Suggested by Bruno Haible.

Index: NEWS
===================================================================
RCS file: /cvs/automake/automake/NEWS,v
retrieving revision 1.247
diff -u -r1.247 NEWS
--- NEWS	18 Nov 2003 21:23:02 -0000	1.247
+++ NEWS	25 Nov 2003 21:07:26 -0000
@@ -209,6 +209,38 @@
   - 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.
Index: doc/automake.texi
===================================================================
RCS file: /cvs/automake/automake/doc/automake.texi,v
retrieving revision 1.9
diff -u -r1.9 automake.texi
--- doc/automake.texi	11 Nov 2003 00:07:16 -0000	1.9
+++ doc/automake.texi	25 Nov 2003 21:07:34 -0000
@@ -5948,19 +5948,55 @@
 @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
-- 
Alexandre Duret-Lutz