[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[SCM] GNU Autoconf source repository branch, master, updated. v2.63-221-
From: |
Eric Blake |
Subject: |
[SCM] GNU Autoconf source repository branch, master, updated. v2.63-221-g26ba3d5 |
Date: |
Fri, 21 Nov 2008 13:57:06 +0000 |
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=26ba3d53187631bd8febe617a957df5063ed2fe6
The branch, master has been updated
via 26ba3d53187631bd8febe617a957df5063ed2fe6 (commit)
via 54dd8a93795219ca8e51bb58963be5ea64e48d34 (commit)
from abe172f4ba8d375a8b078534e9cef1e084ff59ab (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 26ba3d53187631bd8febe617a957df5063ed2fe6
Author: Eric Blake <address@hidden>
Date: Fri Nov 21 06:54:51 2008 -0700
Add @anchors within Builtins and Usual Tools lists.
* doc/autoconf.texi (Limitations of Builtins)
(Limitatations of Usual Tools): Add anchors for tools called out
by name. Adjust callers to narrow in on tool of interest.
Signed-off-by: Eric Blake <address@hidden>
commit 54dd8a93795219ca8e51bb58963be5ea64e48d34
Author: Eric Blake <address@hidden>
Date: Fri Nov 21 06:35:35 2008 -0700
Move case statement style discussion to m4 quoting section.
* doc/autoconf.texi (Limitations of Builtins): Move comparison of
quoting styles...
(Balancing Parentheses): ...to this new node.
Suggested by Ralf Wildenhues.
Signed-off-by: Eric Blake <address@hidden>
-----------------------------------------------------------------------
Summary of changes:
ChangeLog | 13 +++
doc/autoconf.texi | 282 ++++++++++++++++++++++++++++++-----------------------
2 files changed, 173 insertions(+), 122 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index 8381688..a1b8a46 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,16 @@
+2008-11-21 Eric Blake <address@hidden>
+
+ Add @anchors within Builtins and Usual Tools lists.
+ * doc/autoconf.texi (Limitations of Builtins)
+ (Limitatations of Usual Tools): Add anchors for tools called out
+ by name. Adjust callers to narrow in on tool of interest.
+
+ Move case statement style discussion to m4 quoting section.
+ * doc/autoconf.texi (Limitations of Builtins): Move comparison of
+ quoting styles...
+ (Balancing Parentheses): ...to this new node.
+ Suggested by Ralf Wildenhues.
+
2008-11-20 Eric Blake <address@hidden>
Factor more common code out of AT_CHECK into shell function.
diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index 7a154b7..e5e2b3a 100644
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -445,6 +445,7 @@ M4 Quotation
* Quotation and Nested Macros:: Macros calling macros
* Changequote is Evil:: Worse than INTERCAL: M4 + changequote
* Quadrigraphs:: Another way to escape special characters
+* Balancing Parentheses:: Dealing with unbalanced parentheses
* Quotation Rule Of Thumb:: One parenthesis, one quote
Using @command{autom4te}
@@ -2957,7 +2958,8 @@ them does not change their contents. This feature avoids
unnecessary
recompilation. You should include the file @file{stamp-h.in} your
package's distribution, so that @command{make} considers
@file{config.h.in} up to date. Don't use @command{touch}
-(@pxref{Limitations of Usual Tools}); instead, use @command{echo} (using
+(@pxref{touch, , Limitations of Usual Tools}); instead, use
address@hidden (using
@command{date} would cause needless differences, hence @acronym{CVS}
conflicts, etc.).
@@ -3767,7 +3769,7 @@ best implementation.
Look for the best available @code{grep} or @code{ggrep} that accepts the
longest input lines possible, and that supports multiple @option{-e} options.
Set the output variable @code{GREP} to whatever is chosen.
address@hidden of Usual Tools}, for more information about
address@hidden, , Limitations of Usual Tools}, for more information about
portability problems with the @command{grep} command family.
@end defmac
@@ -3950,7 +3952,7 @@ is found, and otherwise to @samp{:} (do nothing).
@ovindex SED
Set output variable @code{SED} to a Sed implementation that conforms to
Posix and does not have arbitrary length limits. Report an error if no
-acceptable Sed is found. @xref{Limitations of Usual Tools}, for more
+acceptable Sed is found. @xref{sed, , Limitations of Usual Tools}, for more
information about portability problems with Sed.
@end defmac
@@ -9292,6 +9294,7 @@ former helps one to follow the latter.
* Quotation and Nested Macros:: Macros calling macros
* Changequote is Evil:: Worse than INTERCAL: M4 + changequote
* Quadrigraphs:: Another way to escape special characters
+* Balancing Parentheses:: Dealing with unbalanced parentheses
* Quotation Rule Of Thumb:: One parenthesis, one quote
@end menu
@@ -9778,6 +9781,126 @@ invention, and I suppose it could have been a common
pun around the
Cambridge University computer lab at the time.
@end quotation
+
address@hidden Balancing Parentheses
address@hidden Dealing with unbalanced parentheses
address@hidden balancing parentheses
address@hidden parentheses, balancing
address@hidden unbalanced parentheses, managing
+
+One of the pitfalls of portable shell programming is that @command{case}
+statements require unbalanced parentheses (@pxref{case, , Limitations of
+Shell Builtins}). With syntax highlighting
+editors, the presence of unbalanced @samp{)} can interfere with editors
+that perform syntax highlighting of macro contents based on finding the
+matching @samp{(}. Another concern is how much editing must be done
+when transferring code snippets between shell scripts and macro
+definitions. But most importantly, the presence of unbalanced
+parentheses can introduce expansion bugs.
+
+For an example, here is an underquoted attempt to use the macro
address@hidden, which happens to expand to a portable @command{case}
+statement:
+
address@hidden
+AC_DEFUN([my_case],
+[case $file_name in
+ *.c) echo "C source code";;
+esac])
+AS_IF(:, my_case)
address@hidden example
+
address@hidden
+In the above example, the @code{AS_IF} call underquotes its arguments.
+As a result, the unbalanced @samp{)} generated by the premature
+expansion of @code{my_case} results in expanding @code{AS_IF} with a
+truncated parameter, and the expansion is syntactically invalid:
+
address@hidden
+if :; then
+ case $file_name in
+ *.c
+fi echo "C source code";;
+esac)
address@hidden example
+
+If nothing else, this should emphasize the importance of the quoting
+arguments to macro calls. On the other hand, there are several
+variations for defining @code{my_case} to be more robust, even when used
+without proper quoting, each with some benefits and some drawbacks.
+
address@hidden @asis
address@hidden Creative literal shell comment
address@hidden
+AC_DEFUN([my_case],
+[case $file_name in #(
+ *.c) echo "C source code";;
+esac])
address@hidden example
address@hidden
+This version provides balanced parentheses to several editors, and can
+be copied and pasted into a terminal as is. Unfortunately, it is still
+unbalanced as an Autoconf argument, since @samp{#(} is an M4 comment
+that masks the normal properties of @samp{(}.
+
address@hidden Quadrigraph shell comment
address@hidden
+AC_DEFUN([my_case],
+[case $file_name in @@%:@@(
+ *.c) echo "C source code";;
+esac])
address@hidden example
address@hidden
+This version provides balanced parentheses to even more editors, and can
+be used as a balanced Autoconf argument. Unfortunately, it requires
+some editing before it can be copied and pasted into a terminal, and the
+use of the quadrigraph @samp{@@%:@@} for @samp{#} reduces readability.
+
address@hidden Quoting just the parenthesis
address@hidden
+AC_DEFUN([my_case],
+[case $file_name in
+ *.c[)] echo "C source code";;
+esac])
address@hidden example
address@hidden
+This version quotes the @samp{)}, so that it can be used as a balanced
+Autoconf argument. As written, this is not balanced to an editor, but
+it can be coupled with @samp{[#(]} to meet that need, too. However, it
+still requires some edits before it can be copied and pasted into a
+terminal.
+
address@hidden Double-quoting the entire statement
address@hidden
+AC_DEFUN([my_case],
+[[case $file_name in #(
+ *.c) echo "C source code";;
+esac]])
address@hidden example
address@hidden
+Since the entire macro is double-quoted, there is no problem with using
+this as an Autoconf argument; and since the double-quoting is over the
+entire statement, this code can be easily copied and pasted into a
+terminal. However, the double quoting prevents the expansion of any
+macros inside the case statement, which may cause its own set of
+problems.
+
address@hidden Using @code{AS_CASE}
address@hidden
+AC_DEFUN([my_case],
+[AS_CASE([$file_name],
+ [*.c], [echo "C source code"])])
address@hidden example
address@hidden
+This version avoids the balancing issue altogether, by relying on
address@hidden (@pxref{Common Shell Constructs}); it also allows for the
+expansion of @code{AC_REQUIRE} to occur prior to the entire case
+statement, rather than within a branch of the case statement that might
+not be taken. However, the abstraction comes with a penalty that it is
+no longer a quick copy, paste, and edit to get back to shell code.
address@hidden itemize
+
+
@node Quotation Rule Of Thumb
@subsection Quotation Rule Of Thumb
@@ -12009,6 +12132,8 @@ if @code{$file} is @samp{/one/two/three}, the command
Expand into a shell @samp{case} statement, where @var{word} is matched
against one or more patterns. @var{if-matched} is run if the
corresponding pattern matched @var{word}, else @var{default} is run.
+Avoids several portability issues (@pxref{case, , Limitations of Shell
+Builtins}).
@end defmac
@c Deprecated, to be replaced by a better API
@@ -12026,7 +12151,9 @@ if @code{$file} is @samp{/one/two/three}, the command
Emits @var{word} to the standard output, followed by a newline. @var{word}
must be a single shell word (typically a quoted string). The bytes of
@var{word} are output as-is, even if it starts with "-" or contains "\".
-Redirections can be placed outside the macro invocation.
+Redirections can be placed outside the macro invocation. This is much
+more portable than using @command{echo} (@pxref{echo, , Limitations of
+Shell Builtins}).
@end defmac
@defmac AS_ECHO_N (@var{word})
@@ -12045,8 +12172,8 @@ omitted, then @samp{$?} is used, except that a status
of zero is
converted to @samp{1}. To exit with successful status, it is necessary
to supply an explicit @var{status} that expands to @samp{0}. This macro
works around shells that see the exit status of the command prior to
address@hidden inside a @samp{trap 0} handler (@pxref{Limitations of
-Builtins, , Limitations of Shell Builtins}).
address@hidden inside a @samp{trap 0} handler (@pxref{trap, , Limitations
+of Shell Builtins}).
@end defmac
@defmac AS_IF (@var{test1}, @ovar{run-if-true1}, @dots{}, @ovar{run-if-false})
@@ -12074,7 +12201,8 @@ Make the directory @var{file-name}, including
intervening directories
as necessary. This is equivalent to @samp{mkdir -p -- @var{file-name}},
except that it is portable to older versions of @command{mkdir} that
lack support for the @option{-p} option or for the @option{--}
-delimiter. Also, @code{AS_MKDIR_P}
+delimiter (@pxref{mkdir, , Limitations of Usual Tools}). Also,
address@hidden
succeeds if @var{file-name} is a symbolic link to an existing directory,
even though Posix is unclear whether @samp{mkdir -p} should
succeed in that case. If creation of @var{file-name} fails, exit the
@@ -12087,8 +12215,7 @@ Also see the @code{AC_PROG_MKDIR_P} macro
(@pxref{Particular Programs}).
@asindex{SET_STATUS}
Emit shell code to set the value of @samp{$?} to @var{status} without
forking. However, this is not guaranteed to abort a shell running with
address@hidden -e} (@pxref{Limitations of Builtins, , Limitations of Shell
-Builtins}).
address@hidden -e} (@pxref{set, , Limitations of Shell Builtins}).
@end defmac
@defmac AS_TR_CPP (@var{expression})
@@ -12125,7 +12252,7 @@ optimizing the common cases (@var{dir} or @var{file} is
@samp{.},
@defmac AS_UNSET (@var{var})
@asindex{UNSET}
Unsets the shell variable @var{var}, working around bugs in older
-shells (@pxref{Limitations of Builtins, , Limitations of Shell
+shells (@pxref{unset, , Limitations of Shell
Builtins}). @var{var} can be a literal or indirect variable name.
@end defmac
@@ -13682,8 +13809,7 @@ esac
@noindent
Make sure you quote the brackets if appropriate and keep the backslash as
-first character (@pxref{Limitations of Builtins, , Limitations of Shell
-Builtins}).
+first character (@pxref{case, , Limitations of Shell Builtins}).
Also, because the colon is used as part of a drivespec, these systems don't
use it as path separator. When creating or accessing paths, you can use the
@@ -14413,7 +14539,7 @@ PS4='+ '
@noindent
(actually, there is some complication due to bugs in @command{unset};
-see @pxref{Limitations of Builtins, , Limitations of Shell Builtins}).
+see @pxref{unset, , Limitations of Shell Builtins}).
@item FPATH
The Korn shell uses @env{FPATH} to find shell functions, so avoid
@@ -14748,8 +14874,8 @@ arguments of the script were lost after the first
function invocation.
It is probably not worth worrying about these shells any more.
With @acronym{AIX} sh, a @command{trap} on 0 installed in a shell function
-triggers at function exit rather than at script exit, see @xref{Limitations
-of Builtins}.
+triggers at function exit rather than at script exit, see @xref{trap, ,
+Limitations of Shell Builtins}.
@node Limitations of Builtins
@section Limitations of Shell Builtins
@@ -14873,6 +14999,7 @@ $ @kbd{pdksh -c 'false; @{ @}; echo $?' || echo $?}
The use of @samp{break 2} etc.@: is safe.
address@hidden
@item @command{case}
@c -----------------
@prindex @command{case}
@@ -14901,113 +15028,13 @@ $ @kbd{case foo in (foo) echo foo;; esac}
@end example
@noindent
address@hidden balancing parentheses
address@hidden parentheses, balancing
The leading @samp{(} can be omitted safely. Unfortunately, there are
contexts where unbalanced parentheses cause other problems, such as when
using a syntax-highlighting editor that searches for the balancing
counterpart, or more importantly, when using a case statement as an
-underquoted argument to an Autoconf macro:
-
address@hidden
-AC_DEFUN([my_case],
-[case $file_name in
- *.c) echo "C source code";;
-esac])
-AS_IF(:, my_case)
address@hidden example
-
address@hidden
-In the above example, the unbalanced @samp{)} in the premature expansion
-of @code{my_case} results in expanding @code{AS_IF} with a truncated
-parameter, and the expansion is syntactically invalid:
-
address@hidden
-if :; then
- case $file_name in
- *.c
-fi echo "C source code";;
-esac)
address@hidden example
-
address@hidden
-If nothing else, this should emphasize the importance of the quoting
-rule of thumb (@pxref{Quotation Rule Of Thumb}), that you should single
-quote all macro arguments that might be re-expanded, and double-quote
-macro arguments that are literal text. On the other hand, there are
-several variations for defining @code{my_case} to be more robust, each
-with some benefits and some drawbacks.
-
address@hidden @asis
address@hidden Creative literal shell comment
address@hidden
-AC_DEFUN([my_case],
-[case $file_name in #(
- *.c) echo "C source code";;
-esac])
address@hidden example
address@hidden
-This version provides balanced parentheses to several editors, and can
-be copied and pasted into a terminal as is. Unfortunately, it is still
-unbalanced as an Autoconf argument, since @samp{#(} is an M4 comment
-that masks the normal properties of @samp{(}.
-
address@hidden Quadrigraph shell comment
address@hidden
-AC_DEFUN([my_case],
-[case $file_name in @@%:@@(
- *.c) echo "C source code";;
-esac])
address@hidden example
address@hidden
-This version provides balanced parentheses to even more editors, and can
-be used as a balanced Autoconf argument. Unfortunately, it requires
-some editing before it can be copied and pasted into a terminal, and the
-use of the quadrigraph @samp{@@%:@@} for @samp{#} reduces readability.
-
address@hidden Quoting just the parenthesis
address@hidden
-AC_DEFUN([my_case],
-[case $file_name in
- *.c[)] echo "C source code";;
-esac])
address@hidden example
address@hidden
-This version quotes the @samp{)}, so that it can be used as a balanced
-Autoconf argument. As written, this is not balanced to an editor, but
-it can be coupled with @samp{[#(]} to meet that need, too. However, it
-still requires some edits before it can be copied and pasted into a
-terminal.
-
address@hidden Double-quoting the entire statement
address@hidden
-AC_DEFUN([my_case],
-[[case $file_name in #(
- *.c) echo "C source code";;
-esac]])
address@hidden example
address@hidden
-Since the entire macro is double-quoted, there is no problem with using
-this as an Autoconf argument; and since the double-quoting is over the
-entire statement, this code can be easily copied and pasted into a
-terminal. However, the double quoting prevents the expansion of any
-macros inside the case statement, which may cause its own set of
-problems.
-
address@hidden Using @code{AS_CASE}
address@hidden
-AC_DEFUN([my_case],
-[AS_CASE([$file_name],
- [*.c], [echo "C source code"])])
address@hidden example
address@hidden
-This version avoids the balancing issue altogether, by relying on
address@hidden (@pxref{Common Shell Constructs}); it also allows for the
-expansion of @code{AC_REQUIRE} to occur prior to the entire case
-statement, rather than within a branch of the case statement that might
-not be taken. However, the abstraction comes with a penalty that it is
-no longer a quick copy, paste, and edit to get back to shell code.
address@hidden table
+underquoted argument to an Autoconf macro. @xref{Balancing
+Parentheses}, for tradeoffs involved in various styles of dealing with
+unbalanced @samp{)}.
Zsh handles pattern fragments derived from parameter expansions or
command substitutions as though quoted:
@@ -15115,6 +15142,7 @@ See @xref{Special Shell Variables}, for portability
problems involving
Also please see the discussion of the @command{pwd} command.
address@hidden
@item @command{echo}
@c -----------------
@prindex @command{echo}
@@ -15278,6 +15306,7 @@ cannot determine whether it was invoked by plain
@code{exit} or by
@code{AC_MSG_ERROR} macro that has a workaround for this problem.
address@hidden
@item @command{export}
@c -------------------
@prindex @command{export}
@@ -15496,6 +15525,7 @@ No options are portable, not even support @option{-r}
(Solaris
@command{/bin/sh} for example).
address@hidden
@item @command{set}
@c ----------------
@prindex @command{set}
@@ -15704,6 +15734,7 @@ expr "X$ac_feature" : 'X.*[^-a-zA-Z0-9_]' >/dev/null &&
@address@hidden contains backslashes.
address@hidden
@item @command{trap}
@c -----------------
@prindex @command{trap}
@@ -15780,6 +15811,7 @@ for @command{true}.
@end quotation
address@hidden
@item @command{unset}
@c ------------------
@prindex @command{unset}
@@ -15811,7 +15843,7 @@ something like
@noindent
@xref{Special Shell Variables}, for some neutralizing values. Also, see
address@hidden of Builtins}, documentation of @command{export}, for
address@hidden, , Limitations of Builtins}, for
the case of environment variables.
@item @command{wait}
@@ -16197,7 +16229,8 @@ foo
|bar
@end example
address@hidden also suffers the limitations of @command{grep}.
address@hidden also suffers the limitations of @command{grep}
+(@pxref{grep, , Limitations of Usual Tools}).
@item @command{expr}
@c -----------------
@@ -16364,6 +16397,7 @@ $ @kbd{find . -name foo -exec echo
"@address@hidden@address@hidden" \;}
while @acronym{GNU} @command{find} reports @samp{./foo-./foo}.
address@hidden
@item @command{grep}
@c -----------------
@prindex @command{grep}
@@ -16490,6 +16524,7 @@ was equivalent to @samp{sources='*.c not found'} in the
absence of
@samp{.c} files. This is no longer a practical problem, since current
@command{ls} implementations send diagnostics to standard error.
address@hidden
@item @command{mkdir}
@c ------------------
@prindex @command{mkdir}
@@ -16652,6 +16687,7 @@ perfectly portable among Posix hosts.
Just as with @command{rm}, some platforms refuse to remove a working
directory.
address@hidden
@item @command{sed}
@c ----------------
@prindex @command{sed}
@@ -16919,6 +16955,7 @@ There are multiple file formats for @command{tar}; if
you use Automake,
the macro @code{AM_INIT_AUTOMAKE} has some options controlling which
level of portability to use.
address@hidden
@item @command{touch}
@c ------------------
@prindex @command{touch}
@@ -17028,7 +17065,8 @@ affected simple-commands so that they always succeed,
e.g., @samp{touch
T || :; rm -f U}.
However, even this approach can run into common bugs in @acronym{BSD}
implementations of the @option{-e} option of @command{sh} and
address@hidden (@pxref{Limitations of Builtins}), so if you are worried
address@hidden (@pxref{set, , Limitations of Shell Builtins}), so if you
+are worried
about porting to buggy @acronym{BSD} shells it may be simpler to migrate
complicated @command{make} actions into separate scripts.
@@ -17901,7 +17939,7 @@ is not a problem, but in some extreme cases you may
need to use tricks
like @samp{sleep 1} to work around timestamp truncation bugs.
Commands like @samp{cp -p} and @samp{touch -r} typically do not copy
-file timestamps to their full resolutions (@pxref{Limitations of Usual
+file timestamps to their full resolutions (@pxref{touch, , Limitations of Usual
Tools}). Hence you should be wary of rules like this:
@example
hooks/post-receive
--
GNU Autoconf source repository
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [SCM] GNU Autoconf source repository branch, master, updated. v2.63-221-g26ba3d5,
Eric Blake <=