[SCM] GNU Autoconf source repository branch, master, updated. v2.63-256-g34e2c8d

[Eric Blake]

This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "GNU Autoconf source repository".

http://git.sv.gnu.org/gitweb/?p=autoconf.git;a=commitdiff;h=34e2c8d5484b2e74b7242a19ebca51f9aff82028

The branch, master has been updated
       via  34e2c8d5484b2e74b7242a19ebca51f9aff82028 (commit)
       via  91d1870bb4b1d421bd75b29c007ee541ac5ca5d0 (commit)
      from  ea20cd4c87e622ab53d5787c5a2b65f6d6c8b880 (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.

- Log -----------------------------------------------------------------
commit 34e2c8d5484b2e74b7242a19ebca51f9aff82028
Author: Eric Blake <address@hidden>
Date:   Sat Jan 17 09:36:02 2009 -0700

    Improve AC_REQUIRE documentation.
    
    * doc/autoconf.texi (Macro Definitions) <AC_DEFUN>: Add @defmac,
    and mention interaction with AC_REQUIRE.
    (Prerequisite Macros) <AC_REQUIRE>: Give more detail on user
    ordering constraint bug, and how to fix it.
    * tests/m4sugar.at (m4@&address@hidden: nested): New test.
    
    Signed-off-by: Eric Blake <address@hidden>

commit 91d1870bb4b1d421bd75b29c007ee541ac5ca5d0
Author: Eric Blake <address@hidden>
Date:   Sat Jan 17 08:38:11 2009 -0700

    Speed up m4_require.
    
    * lib/m4sugar/m4sugar.m4 (_m4_divert_dump): Change semantics to
    always be defined, as either empty or a number.
    (_m4_defun_pro_outer, _m4_defun_epi_outer): Treat _m4_divert_dump
    as a stack, rather than a one-shot macro.
    (_m4_require_call): Expect third argument to be pre-expanded.
    (m4_divert_require, m4_require): Adjust clients accordingly.
    * lib/m4sugar/m4sh.m4 (AS_REQUIRE): Likewise.
    
    Signed-off-by: Eric Blake <address@hidden>

-----------------------------------------------------------------------

Summary of changes:
 ChangeLog              |   18 ++++++++
 doc/autoconf.texi      |   93 ++++++++++++++++++++++++++++++++++++++---
 lib/m4sugar/m4sh.m4    |   12 ++----
 lib/m4sugar/m4sugar.m4 |   50 ++++++++++++----------
 tests/m4sugar.at       |  108 +++++++++++++++++++++++++++++++++++++++++++++++-
 5 files changed, 243 insertions(+), 38 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 4d37b38..7029b84 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,21 @@
+2009-01-19  Eric Blake  <address@hidden>
+
+       Improve AC_REQUIRE documentation.
+       * doc/autoconf.texi (Macro Definitions) <AC_DEFUN>: Add @defmac,
+       and mention interaction with AC_REQUIRE.
+       (Prerequisite Macros) <AC_REQUIRE>: Give more detail on user
+       ordering constraint bug, and how to fix it.
+       * tests/m4sugar.at (m4@&address@hidden: nested): New test.
+
+       Speed up m4_require.
+       * lib/m4sugar/m4sugar.m4 (_m4_divert_dump): Change semantics to
+       always be defined, as either empty or a number.
+       (_m4_defun_pro_outer, _m4_defun_epi_outer): Treat _m4_divert_dump
+       as a stack, rather than a one-shot macro.
+       (_m4_require_call): Expect third argument to be pre-expanded.
+       (m4_divert_require, m4_require): Adjust clients accordingly.
+       * lib/m4sugar/m4sh.m4 (AS_REQUIRE): Likewise.
+
 2009-01-17  Eric Blake  <address@hidden>
 
        Avoid underfull hbox.
diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index 9a17308..69d5085 100644
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -183,7 +183,8 @@ a package for creating scripts to configure source code 
packages using
 templates and an M4 macro package.
 
 Copyright @copyright{} 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000,
-2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
+2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software
+Foundation, Inc.
 
 @quotation
 Permission is granted to copy, distribute and/or modify this document
@@ -12800,12 +12801,15 @@ Here are some instructions and guidelines for writing 
Autoconf macros.
 @node Macro Definitions
 @section Macro Definitions
 
address@hidden AC_DEFUN (@var{name}, @ovar{body})
 @acindex{DEFUN}
 Autoconf macros are defined using the @code{AC_DEFUN} macro, which is
-similar to the M4 builtin @code{m4_define} macro.  In addition to
+similar to the M4 builtin @code{m4_define} macro; this creates a macro
+named @var{name} and with @var{body} as its expansion.  In addition to
 defining a macro, @code{AC_DEFUN} adds to it some code that is used to
-constrain the order in which macros are called (@pxref{Prerequisite
-Macros}).
+constrain the order in which macros are called, while avoiding redundant
+output (@pxref{Prerequisite Macros}).
address@hidden defmac
 
 An Autoconf macro definition looks like this:
 
@@ -12817,6 +12821,16 @@ You can refer to any arguments passed to the macro as 
@samp{$1},
 @samp{$2}, etc.  @xref{Definitions, , How to define new macros, m4.info,
 @acronym{GNU} M4}, for more complete information on writing M4 macros.
 
+Most macros fall in one of two general categories.  The first category
+includes macros which take arguments, in order to generate output
+parameterized by those arguments.  Macros in this category are designed
+to be directly expanded, often multiple times, and should not be used as
+the argument to @code{AC_REQUIRE}.  The other category includes macros
+which are shorthand for a fixed block of text, and therefore do not take
+arguments.  For this category of macros, directly expanding the macro
+multiple times results in redundant output, so it is more common to use
+the macro as the argument to @code{AC_REQUIRE}.
+
 Be sure to properly quote both the @var{macro-body} @emph{and} the
 @var{macro-name} to avoid any problems if the macro happens to have
 been previously defined.
@@ -13030,7 +13044,8 @@ square brackets.  @var{macro-name} must have been 
defined using
 that it has been called.
 
 @code{AC_REQUIRE} must be used inside a macro defined by @code{AC_DEFUN}; it
-must not be called from the top level.
+must not be called from the top level.  Also, it does not make sense to
+require a macro that takes parameters.
 @end defmac
 
 @code{AC_REQUIRE} is often misunderstood.  It really implements
@@ -13103,9 +13118,75 @@ SOME_CHECK
 @end group
 @end example
 
+However, this implementation can lead to another class of problems.
+Since dependencies are hoisted prior to the outermost @code{AC_DEFUN}
+body, but only if they have not been previously seen, it is still
+possible to encounter out-of-order expansion.  Given this example:
+
address@hidden
+AC_DEFUN([A], [[in A]])
+AC_DEFUN([B], [AC_REQUIRE([A])[in B]])
+AC_DEFUN([C], [AC_REQUIRE([B])[in C]])
+AC_DEFUN([OUTER], [[in OUTER]
+A
+C])
+OUTER
address@hidden example
+
address@hidden
+observe that the expansion of @code{B} occurred prior to the expansion
+of @code{OUTER}, but because the requirement for @code{B} was not
+encountered until after @code{A} had already been directly expanded,
+there was no reason to hoist @code{A}.  Or, put another way, the fact
+that @code{B} was hoisted but not @code{A} means that @code{B} occurs
+before its prerequisite:
+
address@hidden
+in B
+in OUTER
+in A
+in C
address@hidden example
+
+The bug is not in Autoconf, but in the macro definitions.  If you ever
+pass a particular macro name to @code{AC_REQUIRE}, then you are implying
+that the macro only needs to be expanded once.  But to enforce this, all
+uses of that macro should be through @code{AC_REQUIRE}; directly
+expanding the macro defeats the point of using @code{AC_REQUIRE} to
+eliminate redundant expansion.  In the example, this rule of thumb was
+violated because @code{B} requires @code{A} while @code{OUTER} directly
+expands it.  One way of fixing the bug is to factor @code{A} into two
+macros, the portion designed for direct and repeated use (here, named
address@hidden), and the portion designed for one-shot output and used only
+inside @code{AC_REQUIRE} (here, named @code{A_PREREQ}).  Then, by fixing
+all clients to use the correct macro according to their needs:
+
address@hidden
+AC_DEFUN([A], [AC_REQUIRE([A_PREREQ])[in A]])
+AC_DEFUN([A_PREREQ], [[in A_PREREQ]])
+AC_DEFUN([B], [AC_REQUIRE([A_PREREQ])[in B]])
+AC_DEFUN([C], [AC_REQUIRE([B])[in C]])
+AC_DEFUN([OUTER], [[in OUTER]
+A
+C])
+OUTER
address@hidden example
+
address@hidden
+the resulting output will then obey all dependency rules:
+
address@hidden
+in A_PREREQ
+in B
+in OUTER
+in A
+in C
address@hidden example
+
 The helper macros @code{AS_IF} and @code{AS_CASE} may be used to
 enforce expansion of required macros outside of shell conditional
-constructs.  You are furthermore encouraged to put all @code{AC_REQUIRE} calls
+constructs.  You are furthermore encouraged, although not required, to
+put all @code{AC_REQUIRE} calls
 at the beginning of a macro.  You can use @code{dnl} to avoid the empty
 lines they leave.
 
diff --git a/lib/m4sugar/m4sh.m4 b/lib/m4sugar/m4sh.m4
index be9ff3b..0c4c37f 100644
--- a/lib/m4sugar/m4sh.m4
+++ b/lib/m4sugar/m4sh.m4
@@ -2,8 +2,8 @@
 # M4 sugar for common shell constructs.
 # Requires GNU M4 and M4sugar.
 #
-# Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008
-# Free Software Foundation, Inc.
+# Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008,
+# 2009 Free Software Foundation, Inc.
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -360,17 +360,13 @@ m4_divert_pop[]])
 # given diversion when expanded (required or not).  The expansion
 # goes in the named diversion or an earlier one.
 #
-# Note: we expand _m4_divert_desired before passing it to m4_divert_require,
-# otherwise we would need to use m4_pushdef and m4_popdef instead of
-# simply m4_define.
-#
 # Since $2 can be quite large, this is factored for faster execution, giving
 # either m4_require([$1], [$2]) or m4_divert_require(desired, [$1], [$2]).
 m4_defun([AS_REQUIRE],
 [m4_define([_m4_divert_desired], [m4_default_quoted([$3], [M4SH-INIT])])]dnl
-[m4_if(m4_eval(_m4_divert(_m4_divert_dump) <= _m4_divert(_m4_divert_desired)),
+[m4_if(m4_eval(_m4_divert_dump - 0 <= _m4_divert(_m4_divert_desired)),
        1, [m4_require(],
-         [m4_divert_require(_m4_divert(_m4_divert_desired),]) [$1], [$2])])
+         [m4_divert_require(_m4_divert_desired,]) [$1], [$2])])
 
 # _AS_REQUIRE_SHELL_FN(NAME-TO-CHECK, COMMENT, BODY-TO-EXPAND)
 # ------------------------------------------------------------
diff --git a/lib/m4sugar/m4sugar.m4 b/lib/m4sugar/m4sugar.m4
index 556969f..3b28512 100644
--- a/lib/m4sugar/m4sugar.m4
+++ b/lib/m4sugar/m4sugar.m4
@@ -4,7 +4,7 @@ divert(-1)#                                                  
-*- Autoconf -*-
 # Requires GNU M4.
 #
 # Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007,
-# 2008 Free Software Foundation, Inc.
+# 2008, 2009 Free Software Foundation, Inc.
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -1772,8 +1772,7 @@ m4_define([_m4_defun_pro],
 [m4_expansion_stack_push([$1])m4_pushdef([_m4_expanding($1)])])
 
 m4_define([_m4_defun_pro_outer],
-[m4_define([_m4_divert_dump],
-  m4_defn([_m4_divert_diversion]))m4_divert_push([GROW])])
+[m4_pushdef([_m4_divert_dump], m4_divnum)m4_divert_push([GROW])])
 
 # _m4_defun_epi(MACRO-NAME)
 # -------------------------
@@ -1788,21 +1787,29 @@ m4_define([_m4_defun_epi],
 [m4_provide([$1])])
 
 m4_define([_m4_defun_epi_outer],
-[_m4_undefine([_m4_divert_dump])m4_divert_pop([GROW])m4_undivert([GROW])])
+[_m4_popdef([_m4_divert_dump])m4_divert_pop([GROW])m4_undivert([GROW])])
+
+
+# _m4_divert_dump
+# ---------------
+# If blank, we are outside of any defun'd macro.  Otherwise, expands
+# to the diversion number (not name) where require'd macros should be
+# moved once completed.
+m4_define([_m4_divert_dump])
 
 
 # m4_divert_require(DIVERSION, NAME-TO-CHECK, [BODY-TO-EXPAND])
 # --------------------------------------------------------------
-# Same as m4_require, but BODY-TO-EXPAND goes into the named diversion;
+# Same as m4_require, but BODY-TO-EXPAND goes into the named DIVERSION;
 # requirements still go in the current diversion though.
 #
 m4_define([m4_divert_require],
 [m4_ifdef([_m4_expanding($2)],
   [m4_fatal([$0: circular dependency of $2])])]dnl
-[m4_ifdef([_m4_divert_dump], [],
+[m4_if(_m4_divert_dump, [],
   [m4_fatal([$0($2): cannot be used outside of an m4_defun'd macro])])]dnl
 [m4_provide_if([$2], [],
-  [_m4_require_call([$2], [$3], [$1])])])
+  [_m4_require_call([$2], [$3], _m4_divert([$1]))])])
 
 
 # m4_defun(NAME, EXPANSION, [MACRO = m4_define])
@@ -1923,20 +1930,20 @@ m4_define([m4_before],
 # This is called frequently, so minimize the number of macro invocations
 # by avoiding dnl and other overhead on the common path.
 m4_define([m4_require],
-m4_do([[m4_ifdef([_m4_expanding($1)],
-                [m4_fatal([$0: circular dependency of $1])])]],
-      [[m4_ifdef([_m4_divert_dump], [],
-                [m4_fatal([$0($1): cannot be used outside of an ]dnl
-m4_bmatch([$0], [^AC_], [[AC_DEFUN]], [[m4_defun]])['d macro])])]],
-      [[m4_provide_if([$1],
-                     [],
-                     [_m4_require_call([$1], [$2], 
[_m4_defn([_m4_divert_dump])])])]]))
-
-
-# _m4_require_call(NAME-TO-CHECK, [BODY-TO-EXPAND = NAME-TO-CHECK], DIVERSION)
-# ----------------------------------------------------------------------------
+[m4_ifdef([_m4_expanding($1)],
+  [m4_fatal([$0: circular dependency of $1])])]dnl
+[m4_if(_m4_divert_dump, [],
+  [m4_fatal([$0($1): cannot be used outside of an ]dnl
+m4_if([$0], [m4_require], [[m4_defun]], [[AC_DEFUN]])['d macro])])]dnl
+[m4_provide_if([$1], [],
+              [_m4_require_call([$1], [$2], _m4_divert_dump)])])
+
+
+# _m4_require_call(NAME-TO-CHECK, [BODY-TO-EXPAND = NAME-TO-CHECK],
+#                  DIVERSION-NUMBER)
+# -----------------------------------------------------------------
 # If m4_require decides to expand the body, it calls this macro.  The
-# expansion is placed in DIVERSION.
+# expansion is placed in DIVERSION-NUMBER.
 #
 # This is called frequently, so minimize the number of macro invocations
 # by avoiding dnl and other overhead on the common path.
@@ -1946,8 +1953,7 @@ m4_define([_m4_require_call],
 [m4_if([$2], [], [$1], [$2])
 m4_provide_if([$1], [], [m4_warn([syntax],
   [$1 is m4_require'd but not m4_defun'd])])]dnl
-[_m4_divert_raw(_m4_divert($3))]dnl
-[_m4_undivert(_m4_divert_grow)]dnl
+[_m4_divert_raw($3)_m4_undivert(_m4_divert_grow)]dnl
 [m4_divert_pop(_m4_divert_grow)_m4_popdef([_m4_divert_grow])])
 
 
diff --git a/tests/m4sugar.at b/tests/m4sugar.at
index 0d90ca2..e822ffb 100644
--- a/tests/m4sugar.at
+++ b/tests/m4sugar.at
@@ -2,8 +2,8 @@
 
 AT_BANNER([M4sugar.])
 
-# Copyright (C) 2000, 2001, 2002, 2005, 2006, 2007, 2008 Free Software
-# Foundation, Inc.
+# Copyright (C) 2000, 2001, 2002, 2005, 2006, 2007, 2008, 2009 Free
+# Software Foundation, Inc.
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -379,6 +379,7 @@ AT_CLEANUP
 ## --------------------------- ##
 
 AT_SETUP([m4@&address@hidden: error message])
+AT_KEYWORDS([m4@&address@hidden)
 
 AT_DATA_M4SUGAR([script.4s],
 [[m4_defun([foo], [FOO])
@@ -398,6 +399,7 @@ AT_CLEANUP
 ## ----------------------------------- ##
 
 AT_SETUP([m4@&address@hidden: circular dependencies])
+AT_KEYWORDS([m4@&address@hidden)
 
 AT_DATA_M4SUGAR([script.4s],
 [[m4_defun([foo], [m4_require([bar])])
@@ -427,6 +429,7 @@ AT_CLEANUP
 ## ---------------------- ##
 
 AT_SETUP([m4@&address@hidden: one-shot initialization])
+AT_KEYWORDS([m4@&address@hidden)
 AT_KEYWORDS([m4@&address@hidden m4@&address@hidden)
 
 AT_CHECK_M4SUGAR_TEXT([[
@@ -455,6 +458,107 @@ hello, again
 AT_CLEANUP
 
 
+## -------------------- ##
+## m4_require: nested.  ##
+## -------------------- ##
+
+AT_SETUP([m4@&address@hidden: nested])
+AT_KEYWORDS([m4@&address@hidden m4@&address@hidden)
+
+dnl From the m4sugar.m4 discourse: Require chains, top level
+AT_CHECK_M4SUGAR_TEXT([[dnl
+m4_defun([a], [[a]])dnl aka TEST2a
+m4_defun([b], [[b]m4_require([a])])dnl aka TEST3
+m4_defun([c], [[c]m4_require([b])])dnl aka TEST2b
+m4_defun([d], [[d]m4_require([a])m4_require([c])])dnl aka TEST1
+pre
+d
+d
+post
+]],
+[[pre
+a
+b
+c
+d
+d
+post
+]])
+
+dnl From the m4sugar.m4 discourse: Require chains, nested
+AT_CHECK_M4SUGAR_TEXT([[dnl
+m4_defun([a], [[a]])dnl aka TEST2a
+m4_defun([b], [[b]m4_require([a])])dnl aka TEST3
+m4_defun([c], [[c]m4_require([b])])dnl aka TEST2b
+m4_defun([d], [[d]m4_require([a])m4_require([c])])dnl aka TEST1
+m4_defun([wrap],
+[pre
+d
+d
+post])dnl
+wrap
+]],
+[[a
+b
+c
+pre
+d
+d
+post
+]])
+
+dnl Direct invocation, top level
+AT_CHECK_M4SUGAR_TEXT([[dnl
+m4_defun([a], [[a]])dnl
+m4_defun([b], [[b]m4_require([a])])dnl
+m4_defun([c], [[c]m4_require([b])])dnl
+pre
+a
+c
+a
+c
+post
+]],
+[[pre
+a
+b
+c
+a
+c
+post
+]])
+
+dnl Direct invocation, nested.  This is an example of expansion before
+dnl requirement, such that b occurs before its prerequisite a.  This
+dnl indicates a bug in the macros (but not in autoconf), so we should
+dnl be emitting a warning.
+AT_CHECK_M4SUGAR_TEXT([[dnl
+m4_defun([a], [[a]])dnl
+m4_defun([b], [[b]m4_require([a])])dnl
+m4_defun([c], [[c]m4_require([b])])dnl
+m4_defun([outer],
+[pre
+a
+c
+a
+c
+post])dnl
+outer
+]],
+[[b
+pre
+a
+c
+a
+c
+post
+]], [stderr])
+AT_XFAIL_IF([:])
+AT_CHECK([test -s stderr])
+
+AT_CLEANUP
+
+
 ## --------- ##
 ## m4_cond.  ##
 ## --------- ##


hooks/post-receive
--
GNU Autoconf source repository