* Setup:: Initialization and output
* Existing Tests:: Macros that check for particular features
* Writing Tests:: How to write new feature checks
-* Portable Shell:: Shell script portability pitfalls
* Results:: What to do with results from feature checks
* Writing Macros:: Adding new macros to Autoconf
+* Portable Shell:: Shell script portability pitfalls
* Manual Configuration:: Selecting features that can't be guessed
* Site Configuration:: Local defaults for @code{configure}
* Running configure scripts:: How to use the Autoconf output
* Guidelines:: General rules for writing test programs
* Test Functions:: Avoiding pitfalls in test programs
-Portable Shell Programming
-
-* Shellology:: A zoology of shells
-* Here-Documents:: Quirks and tricks
-* File Descriptors:: FDs and redirections
-* File System Conventions:: File- and pathnames
-* Shell Substitutions:: Variable and command expansions
-* Assignments:: Varying side effects of assignments
-* Special Shell Variables:: Variables you should not change
-* Limitations of Builtins:: Portable use of not so portable /bin/sh
-* Limitations of Usual Tools:: Portable use of portable tools
-* Limitations of Make:: Portable Makefiles
-
Results of Tests
* Defining Symbols:: Defining C preprocessor symbols
* Prerequisite Macros:: Ensuring required information
* Suggested Ordering:: Warning about possible ordering problems
+Portable Shell Programming
+
+* Shellology:: A zoology of shells
+* Here-Documents:: Quirks and tricks
+* File Descriptors:: FDs and redirections
+* File System Conventions:: File- and pathnames
+* Shell Substitutions:: Variable and command expansions
+* Assignments:: Varying side effects of assignments
+* Special Shell Variables:: Variables you should not change
+* Limitations of Builtins:: Portable use of not so portable /bin/sh
+* Limitations of Usual Tools:: Portable use of portable tools
+* Limitations of Make:: Portable Makefiles
+
Manual Configuration
* Specifying Names:: Specifying the system type
you can use Autoconf template macros to produce custom checks; see
@ref{Writing Tests}, for information about them. For especially tricky
or specialized features, @file{configure.ac} might need to contain some
-hand-crafted shell commands. The @code{autoscan} program can give you a
-good start in writing @file{configure.ac} (@pxref{autoscan Invocation},
-for more information).
+hand-crafted shell commands; see @ref{Portable Shell}. The
+@code{autoscan} program can give you a good start in writing
+@file{configure.ac} (@pxref{autoscan Invocation}, for more information).
Previous versions of Autoconf promoted the name @file{configure.in},
which is somewhat ambiguous (the tool needed to produce this file is not
@c ========================================================= Writing Tests
-@node Writing Tests, Portable Shell, Existing Tests, Top
+@node Writing Tests, Results, Existing Tests, Top
@chapter Writing Tests
If the existing feature tests don't do something you need, you have to
-@c ============================================= Portable Shell Programming
-
-@node Portable Shell, Results, Writing Tests, Top
-@chapter Portable Shell Programming
-
-When writing your own checks, there are some shell-script programming
-techniques you should avoid in order to make your code portable. The
-Bourne shell and upward-compatible shells like the Korn shell and Bash
-have evolved over the years, but to prevent trouble, do not take
-advantage of features that were added after @sc{unix} version 7, circa
-1977. You should not use shell functions, aliases, negated character
-classes, or other features that are not found in all Bourne-compatible
-shells; restrict yourself to the lowest common denominator. Even
-@code{unset} is not supported by all shells! Also, include a space
-after the exclamation point in interpreter specifications, like this:
-
-@example
-#! /usr/bin/perl
-@end example
-
-@noindent
-If you omit the space before the path, then 4.2@sc{bsd} based systems
-(such as Sequent DYNIX) will ignore the line, because they interpret
-@samp{#! /} as a 4-byte magic number.
+@c ====================================================== Results of Tests.
-The set of external programs you should run in a @code{configure} script
-is fairly small. @xref{Utilities in Makefiles,, Utilities in
-Makefiles, standards, GNU Coding Standards}, for the list. This
-restriction allows users to start out with a fairly small set of
-programs and build the rest, avoiding too many interdependencies between
-packages.
+@node Results, Writing Macros, Writing Tests, Top
+@chapter Results of Tests
-Some of these external utilities have a portable subset of features; see
-@ref{Limitations of Usual Tools}.
+Once @code{configure} has determined whether a feature exists, what can
+it do to record that information? There are four sorts of things it can
+do: define a C preprocessor symbol, set a variable in the output files,
+save the result in a cache file for future @code{configure} runs, and
+print a message letting the user know the result of the test.
@menu
-* Shellology:: A zoology of shells
-* Here-Documents:: Quirks and tricks
-* File Descriptors:: FDs and redirections
-* File System Conventions:: File- and pathnames
-* Shell Substitutions:: Variable and command expansions
-* Assignments:: Varying side effects of assignments
-* Special Shell Variables:: Variables you should not change
-* Limitations of Builtins:: Portable use of not so portable /bin/sh
-* Limitations of Usual Tools:: Portable use of portable tools
-* Limitations of Make:: Portable Makefiles
+* Defining Symbols:: Defining C preprocessor symbols
+* Setting Output Variables:: Replacing variables in output files
+* Caching Results:: Speeding up subsequent @code{configure} runs
+* Printing Messages:: Notifying @code{configure} users
@end menu
-@node Shellology, Here-Documents, Portable Shell, Portable Shell
-@section Shellology
+@node Defining Symbols, Setting Output Variables, Results, Results
+@section Defining C Preprocessor Symbols
-There are several families of shells, most prominently the Bourne
-family and the C shell family which are deeply incompatible. If you
-want to write portable shell scripts, avoid members of the C shell
-family.
+A common action to take in response to a feature test is to define a C
+preprocessor symbol indicating the results of the test. That is done by
+calling @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED}.
-Below we describe some of the members of the Bourne shell family.
+By default, @code{AC_OUTPUT} places the symbols defined by these macros
+into the output variable @code{DEFS}, which contains an option
+@option{-D@var{symbol}=@var{value}} for each symbol defined. Unlike in
+Autoconf version 1, there is no variable @code{DEFS} defined while
+@code{configure} is running. To check whether Autoconf macros have
+already defined a certain C preprocessor symbol, test the value of the
+appropriate cache variable, as in this example:
-@table @asis
-@item Ash
-@cindex Ash
-@command{ash} is often used on @sc{gnu}/Linux and @sc{bsd} systems as a
-light-weight Bourne-compatible shell. Ash 0.2 has some bugs that are
-fixed in the 0.3.x series, but portable shell scripts should workaround
-them, since version 0.2 is still shipped with many @sc{gnu}/Linux
-distributions.
+@example
+AC_CHECK_FUNC(vprintf, [AC_DEFINE(HAVE_VPRINTF)])
+if test "$ac_cv_func_vprintf" != yes; then
+ AC_CHECK_FUNC(_doprnt, [AC_DEFINE(HAVE_DOPRNT)])
+fi
+@end example
-To be compatible with Ash 0.2:
+If @code{AC_CONFIG_HEADERS} has been called, then instead of creating
+@code{DEFS}, @code{AC_OUTPUT} creates a header file by substituting the
+correct values into @code{#define} statements in a template file.
+@xref{Configuration Headers}, for more information about this kind of
+output.
-@itemize @minus
-@item
-don't use @samp{$?} after expanding empty or unset variables:
+@defmac AC_DEFINE (@var{variable}, @ovar{value}, @ovar{description})
+@maindex DEFINE
+Define C preprocessor variable @var{variable}. If @var{value} is given,
+set @var{variable} to that value (verbatim), otherwise set it to 1.
+@var{value} should not contain literal newlines, and if you are not
+using @code{AC_CONFIG_HEADERS} it should not contain any @samp{#}
+characters, as @code{make} tends to eat them. To use a shell variable
+(which you need to do in order to define a value containing the M4 quote
+characters @samp{[} or @samp{]}), use @code{AC_DEFINE_UNQUOTED} instead.
+@var{description} is only useful if you are using
+@code{AC_CONFIG_HEADERS}. In this case, @var{description} is put into
+the generated @file{config.h.in} as the comment before the macro define.
+The following example defines the C preprocessor variable
+@code{EQUATION} to be the string constant @samp{"$a > $b"}:
@example
-foo=
-false
-$foo
-echo "Don't use it: $?"
+AC_DEFINE(EQUATION, "$a > $b")
@end example
+@end defmac
-@item
-don't use command substitution within variable expansion:
+@defmac AC_DEFINE_UNQUOTED (@var{variable}, @ovar{value}, @ovar{description})
+@maindex DEFINE_UNQUOTED
+Like @code{AC_DEFINE}, but three shell expansions are
+performed---once---on @var{variable} and @var{value}: variable expansion
+(@samp{$}), command substitution (@samp{`}), and backslash escaping
+(@samp{\}). Single and double quote characters in the value have no
+special meaning. Use this macro instead of @code{AC_DEFINE} when
+@var{variable} or @var{value} is a shell variable. Examples:
@example
-cat $@{FOO=`bar`@}
+AC_DEFINE_UNQUOTED(config_machfile, "$machfile")
+AC_DEFINE_UNQUOTED(GETGROUPS_T, $ac_cv_type_getgroups)
+AC_DEFINE_UNQUOTED($ac_tr_hdr)
@end example
+@end defmac
-@item
-beware that single builtin substitutions are not performed by a sub
-shell, hence their effect applies to the current shell! @xref{Shell
-Substitutions}, item ``Command Substitution''.
-@end itemize
-
-@item Bash
-@cindex Bash
-To detect whether you are running @command{bash}, test if
-@code{BASH_VERSION} is set. To disable its extensions and require
-@sc{posix} compatibility, run @samp{set -o posix}. @xref{Bash POSIX
-Mode,, Bash @sc{posix} Mode, bash, The GNU Bash Reference Manual}, for
-details.
-
-@item @command{/usr/xpg4/bin/sh} on Solaris
-@cindex @command{/usr/xpg4/bin/sh} on Solaris
-The @sc{posix}-compliant Bourne shell on a Solaris system is
-@command{/usr/xpg4/bin/sh} and is part of an extra optional package.
-There is no extra charge for this package, but it is also not part of a
-minimal OS install and therefore some folks may not have it.
-
-@item Zsh
-@cindex Zsh
-To detect whether you are running @command{zsh}, test if
-@code{ZSH_VERSION} is set. By default @command{zsh} is @emph{not}
-compatible with the Bourne shell: you have to run @samp{emulate sh} and
-set @code{NULLCMD} to @samp{:}. @xref{Compatibility,, Compatibility,
-zsh, The Z Shell Manual}, for details.
-
-Zsh 3.0.8 is the native @command{/bin/sh} on Mac OS X 10.0.3.
-@end table
-
-The following discussion between Russ Allbery and Robert Lipe is worth
-reading:
-
-@noindent
-Russ Allbery:
+Due to the syntactical bizarreness of the Bourne shell, do not use
+semicolons to separate @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED}
+calls from other macro calls or shell code; that can cause syntax errors
+in the resulting @code{configure} script. Use either spaces or
+newlines. That is, do this:
-@quotation
-The @sc{gnu} assumption that @command{/bin/sh} is the one and only shell
-leads to a permanent deadlock. Vendors don't want to break user's
-existant shell scripts, and there are some corner cases in the Bourne
-shell that are not completely compatible with a @sc{posix} shell. Thus,
-vendors who have taken this route will @emph{never} (OK@dots{}``never say
-never'') replace the Bourne shell (as @command{/bin/sh}) with a
-@sc{posix} shell.
-@end quotation
+@example
+AC_CHECK_HEADER(elf.h, [AC_DEFINE(SVR4) LIBS="$LIBS -lelf"])
+@end example
@noindent
-Robert Lipe:
-
-@quotation
-This is exactly the problem. While most (at least most System V's) do
-have a bourne shell that accepts shell functions most vendor
-@command{/bin/sh} programs are not the @sc{posix} shell.
-
-So while most modern systems do have a shell _somewhere_ that meets the
-@sc{posix} standard, the challenge is to find it.
-@end quotation
-
-@node Here-Documents, File Descriptors, Shellology, Portable Shell
-@section Here-Documents
-
-Don't rely on @samp{\} being preserved just because it has no special
-meaning together with the next symbol. in the native @command{/bin/sh}
-on OpenBSD 2.7 @samp{\"} expands to @samp{"} in here-documents with
-unquoted delimiter. As a general rule, if @samp{\\} expands to @samp{\}
-use @samp{\\} to get @samp{\}.
-
-With OpenBSD 2.7's @command{/bin/sh}
+or this:
@example
-@group
-$ cat <<EOF
-> \" \\
-> EOF
-" \
-@end group
+AC_CHECK_HEADER(elf.h,
+ [AC_DEFINE(SVR4)
+ LIBS="$LIBS -lelf"])
@end example
@noindent
-and with Bash:
+instead of this:
@example
-@group
-bash-2.04$ cat <<EOF
-> \" \\
-> EOF
-\" \
-@end group
+AC_CHECK_HEADER(elf.h, [AC_DEFINE(SVR4); LIBS="$LIBS -lelf"])
@end example
+@node Setting Output Variables, Caching Results, Defining Symbols, Results
+@section Setting Output Variables
-Many older shells (including the Bourne shell) implement here-documents
-inefficiently. Users can generally speed things up by using a faster
-shell, e.g., by using the command @samp{bash ./configure} rather than
-plain @samp{./configure}.
-
-Some shells can be extremely inefficient when there are a lot of
-here-documents inside a single statement. For instance if your
-@file{configure.ac} includes something like:
-
-@example
-@group
-if <cross_compiling>; then
- assume this and that
-else
- check this
- check that
- check something else
- @dots{}
- on and on forever
- @dots{}
-fi
-@end group
-@end example
-
-A shell parses the whole @code{if}/@code{fi} construct, creating
-temporary files for each here document in it. Some shells create links
-for such here-documents on every @code{fork}, so that the clean-up code
-they had installed correctly removes them. It is creating the links
-that the shell can take forever.
-
-Moving the tests out of the @code{if}/@code{fi}, or creating multiple
-@code{if}/@code{fi} constructs, would improve the performance
-significantly. Anyway, this kind of construct is not exactly the
-typical use of Autoconf. In fact, it's even not recommended, because M4
-macros can't look into shell conditionals, so we may fail to expand a
-macro when it was expanded before in a conditional path, and the
-condition turned out to be false at run-time, and we end up not
-executing the macro at all.
-
-@node File Descriptors, File System Conventions, Here-Documents, Portable Shell
-@section File Descriptors
+Another way to record the results of tests is to set @dfn{output
+variables}, which are shell variables whose values are substituted into
+files that @code{configure} outputs. The two macros below create new
+output variables. @xref{Preset Output Variables}, for a list of output
+variables that are always available.
-Some file descriptors shall not be used, since some systems, admittedly
-arcane, use them for special purpose:
+@defmac AC_SUBST (@var{variable}, @ovar{value})
+@maindex SUBST
+Create an output variable from a shell variable. Make @code{AC_OUTPUT}
+substitute the variable @var{variable} into output files (typically one
+or more @file{Makefile}s). This means that @code{AC_OUTPUT} will
+replace instances of @samp{@@@var{variable}@@} in input files with the
+value that the shell variable @var{variable} has when @code{AC_OUTPUT}
+is called. This value of @var{variable} should not contain literal
+newlines.
-@table @asis
-@item 3
-some systems may open it to @samp{/dev/tty}.
+If @var{value} is given, in addition assign it to @samp{variable}.
+@end defmac
-@item 4
-used on the Kubota Titan.
-@end table
+@defmac AC_SUBST_FILE (@var{variable})
+@maindex SUBST_FILE
+Another way to create an output variable from a shell variable. Make
+@code{AC_OUTPUT} insert (without substitutions) the contents of the file
+named by shell variable @var{variable} into output files. This means
+that @code{AC_OUTPUT} will replace instances of
+@samp{@@@var{variable}@@} in output files (such as @file{Makefile.in})
+with the contents of the file that the shell variable @var{variable}
+names when @code{AC_OUTPUT} is called. Set the variable to
+@file{/dev/null} for cases that do not have a file to insert.
-Don't redirect several times the same file descriptor, as you are doomed
-to failure under Ultrix.
+This macro is useful for inserting @file{Makefile} fragments containing
+special dependencies or other @code{make} directives for particular host
+or target types into @file{Makefile}s. For example, @file{configure.ac}
+could contain:
@example
-ULTRIX V4.4 (Rev. 69) System #31: Thu Aug 10 19:42:23 GMT 1995
-UWS V4.4 (Rev. 11)
-$ eval 'echo matter >fullness' >void
-illegal io
-$ eval '(echo matter >fullness)' >void
-illegal io
-$ (eval '(echo matter >fullness)') >void
-Ambiguous output redirect.
+AC_SUBST_FILE(host_frag)
+host_frag=$srcdir/conf/sun4.mh
@end example
@noindent
-In each case the expected result is of course @file{fullness} containing
-@samp{matter} and @file{void} being empty.
-
-Don't try to redirect the standard error of a command substitution: it
-must be done @emph{inside} the command substitution: when running
-@samp{: `cd /zorglub` 2>/dev/null} expect the error message to
-escape, while @samp{: `cd /zorglub 2>/dev/null`} works properly.
-
-It is worth noting that Zsh (but not Ash nor Bash) makes it possible
-in assignments though: @samp{foo=`cd /zorglub` 2>/dev/null}.
-
-Most shells, if not all (including Bash, Zsh, Ash), output traces on
-stderr, even for sub-shells. This might result in undesired content
-if you meant to capture the standard-error output of the inner command:
+and then a @file{Makefile.in} could contain:
@example
-$ ash -x -c '(eval "echo foo >&2") 2>stderr'
-$ cat stderr
-+ eval echo foo >&2
-+ echo foo
-foo
-$ bash -x -c '(eval "echo foo >&2") 2>stderr'
-$ cat stderr
-+ eval 'echo foo >&2'
-++ echo foo
-foo
-$ zsh -x -c '(eval "echo foo >&2") 2>stderr'
-@i{# Traces on startup files deleted here.}
-$ cat stderr
-+zsh:1> eval echo foo >&2
-+zsh:1> echo foo
-foo
+@@host_frag@@
@end example
+@end defmac
-@noindent
-You'll appreciate the various levels of detail@dots{}
+@node Caching Results, Printing Messages, Setting Output Variables, Results
+@section Caching Results
+@cindex Cache
-One workaround is to grep out uninteresting lines, hoping not to remove
-good ones@dots{}
+To avoid checking for the same features repeatedly in various
+@code{configure} scripts (or in repeated runs of one script),
+@code{configure} can optionally save the results of many checks in a
+@dfn{cache file} (@pxref{Cache Files}). If a @code{configure} script
+runs with caching enabled and finds a cache file, it reads the results
+of previous runs from the cache and avoids rerunning those checks. As a
+result, @code{configure} can then run much faster than if it had to
+perform all of the checks every time.
-@node File System Conventions, Shell Substitutions, File Descriptors, Portable Shell
-@section File System Conventions
+@defmac AC_CACHE_VAL (@var{cache-id}, @var{commands-to-set-it})
+@maindex CACHE_VAL
+Ensure that the results of the check identified by @var{cache-id} are
+available. If the results of the check were in the cache file that was
+read, and @code{configure} was not given the @option{--quiet} or
+@option{--silent} option, print a message saying that the result was
+cached; otherwise, run the shell commands @var{commands-to-set-it}. If
+the shell commands are run to determine the value, the value will be
+saved in the cache file just before @code{configure} creates its output
+files. @xref{Cache Variable Names}, for how to choose the name of the
+@var{cache-id} variable.
-While @command{autoconf} and friends will usually be run on some Unix
-variety, it can and will be used on other systems, most notably @sc{dos}
-variants. This impacts several assumptions regarding file and
-path names.
+The @var{commands-to-set-it} @emph{must have no side effects} except for
+setting the variable @var{cache-id}, see below.
+@end defmac
-@noindent
-For example, the following code:
+@defmac AC_CACHE_CHECK (@var{message}, @var{cache-id}, @var{commands-to-set-it})
+@maindex CACHE_CHECK
+A wrapper for @code{AC_CACHE_VAL} that takes care of printing the
+messages. This macro provides a convenient shorthand for the most
+common way to use these macros. It calls @code{AC_MSG_CHECKING} for
+@var{message}, then @code{AC_CACHE_VAL} with the @var{cache-id} and
+@var{commands} arguments, and @code{AC_MSG_RESULT} with @var{cache-id}.
-@example
-case $foo_dir in
- /*) # Absolute
- ;;
- *)
- foo_dir=$dots$foo_dir ;;
-esac
-@end example
+The @var{commands-to-set-it} @emph{must have no side effects} except for
+setting the variable @var{cache-id}, see below.
+@end defmac
-@noindent
-will fail to properly detect absolute paths on those systems, because
-they can use a drivespec, and will usually use a backslash as directory
-separator. The canonical way to check for absolute paths is:
+It is very common to find buggy macros using @code{AC_CACHE_VAL} or
+@code{AC_CACHE_CHECK}, because people are tempted to call
+@code{AC_DEFINE} in the @var{commands-to-set-it}. Instead, the code that
+@emph{follows} the call to @code{AC_CACHE_VAL} should call
+@code{AC_DEFINE}, by examining the value of the cache variable. For
+instance, the following macro is broken:
@example
-case $foo_dir in
- [\\/]* | ?:[\\/]* ) # Absolute
- ;;
- *)
- foo_dir=$dots$foo_dir ;;
-esac
+@group
+AC_DEFUN([AC_SHELL_TRUE],
+[AC_CACHE_CHECK([whether true(1) works], [ac_cv_shell_true_works],
+ [ac_cv_shell_true_works=no
+ true && ac_cv_shell_true_works=yes
+ if test $ac_cv_shell_true_works = yes; then
+ AC_DEFINE([TRUE_WORKS], 1
+ [Define if `true(1)' works properly.])
+ fi])
+])
+@end group
@end example
@noindent
-Make sure you quote the brackets if appropriate and keep the backslash as
-first character (@pxref{Limitations of Builtins}).
+This fails if the cache is enabled: the second time this macro is run,
+@code{TRUE_WORKS} @emph{will not be defined}. The proper implementation
+is:
-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, use
-@code{$ac_path_separator} instead (or the @code{PATH_SEPARATOR} output
-variable). @command{autoconf} sets this to the appropriate value (@samp{:}
-or @samp{;}) when it starts up.
+@example
+@group
+AC_DEFUN([AC_SHELL_TRUE],
+[AC_CACHE_CHECK([whether true(1) works], [ac_cv_shell_true_works],
+ [ac_cv_shell_true_works=no
+ true && ac_cv_shell_true_works=yes])
+ if test $ac_cv_shell_true_works = yes; then
+ AC_DEFINE([TRUE_WORKS], 1
+ [Define if `true(1)' works properly.])
+ fi
+])
+@end group
+@end example
-File names need extra care as well. While @sc{dos}-based environments
-that are Unixy enough to run @command{autoconf} (such as DJGPP) will
-usually be able to handle long file names properly, there are still
-limitations that can seriously break packages. Several of these issues
-can be easily detected by the
-@href{ftp://ftp.gnu.org/gnu/non-gnu/doschk/doschk-1.1.tar.gz, doschk}
-package.
+Also, @var{commands-to-set-it} should not print any messages, for
+example with @code{AC_MSG_CHECKING}; do that before calling
+@code{AC_CACHE_VAL}, so the messages are printed regardless of whether
+the results of the check are retrieved from the cache or determined by
+running the shell commands.
-A short overview follows; problems are marked with @sc{sfn}/@sc{lfn} to
-indicate where they apply: @sc{sfn} means the issues are only relevant to
-plain @sc{dos}, not to @sc{dos} boxes under Windows, while @sc{lfn}
-identifies problems that exist even under Windows.
+@menu
+* Cache Variable Names:: Shell variables used in caches
+* Cache Files:: Files @code{configure} uses for caching
+* Cache Checkpointing:: Loading and saving the cache file
+@end menu
-@table @asis
-@item No multiple dots (@sc{sfn})
-@sc{dos} cannot handle multiple dots in filenames. This is an especially
-important thing to remember when building a portable configure script,
-as @command{autoconf} uses a .in suffix for template files.
+@node Cache Variable Names, Cache Files, Caching Results, Caching Results
+@subsection Cache Variable Names
+@cindex Cache variable
-This is perfectly OK on Unices:
+The names of cache variables should have the following format:
@example
-AC_CONFIG_HEADER(config.h)
-AC_CONFIG_FILES([source.c foo.bar])
-AC_OUTPUT
+@var{package-prefix}_cv_@var{value-type}_@var{specific-value}_@ovar{additional-options}
@end example
@noindent
-but it causes problems on @sc{dos}, as it requires @samp{config.h.in},
-@samp{source.c.in} and @samp{foo.bar.in}. To make your package more portable
-to @sc{dos}-based environments, you should use this instead:
-
-@example
-AC_CONFIG_HEADER(config.h:config.hin)
-AC_CONFIG_FILES([source.c:source.cin foo.bar:foobar.in])
-AC_OUTPUT
-@end example
+for example, @samp{ac_cv_header_stat_broken} or
+@samp{ac_cv_prog_gcc_traditional}. The parts of the variable name are:
-@item No leading dot (@sc{sfn})
-@sc{dos} cannot handle filenames that start with a dot. This is usually
-not a very important issue for @command{autoconf}.
+@table @asis
+@item @var{package-prefix}
+An abbreviation for your package or organization; the same prefix you
+begin local Autoconf macros with, except lowercase by convention.
+For cache values used by the distributed Autoconf macros, this value is
+@samp{ac}.
-@item Case insensitivity (@sc{lfn})
-@sc{dos} is case insensitive, so you cannot, for example, have both a
-file called @samp{INSTALL} and a directory called @samp{install}. This
-also affects @command{make}; if there's a file called @samp{INSTALL} in
-the directory, @command{make install} will do nothing (unless the
-@samp{install} target is marked as PHONY).
+@item @code{_cv_}
+Indicates that this shell variable is a cache value. This string
+@emph{must} be present in the variable name, including the leading
+underscore.
-@item The 8+3 limit (@sc{sfn})
-Because the @sc{dos} file system only stores the first 8 characters of
-the filename and the first 3 of the extension, those must be unique.
-That means that @file{foobar-part1.c}, @file{foobar-part2.c} and
-@file{foobar-prettybird.c} all resolve to the same filename
-(@file{FOOBAR-P.C}). The same goes for @file{foo.bar} and
-@file{foo.bartender}.
+@item @var{value-type}
+A convention for classifying cache values, to produce a rational naming
+system. The values used in Autoconf are listed in @ref{Macro Names}.
-Note: This is not usually a problem under Windows, as it uses numeric
-tails in the short version of filenames to make them unique. However, a
-registry setting can turn this behaviour off. While this makes it
-possible to share file trees containing long file names between @sc{sfn}
-and @sc{lfn} environments, it also means the above problem applies there
-as well.
+@item @var{specific-value}
+Which member of the class of cache values this test applies to.
+For example, which function (@samp{alloca}), program (@samp{gcc}), or
+output variable (@samp{INSTALL}).
-@item Invalid characters
-Some characters are invalid in @sc{dos} filenames, and should therefore
-be avoided. In a @sc{lfn} environment, these are @samp{/}, @samp{\},
-@samp{?}, @samp{*}, @samp{:}, @samp{<}, @samp{>}, @samp{|} and @samp{"}.
-In a @sc{sfn} environment, other characters are also invalid. These
-include @samp{+}, @samp{,}, @samp{[} and @samp{]}.
+@item @var{additional-options}
+Any particular behavior of the specific member that this test applies to.
+For example, @samp{broken} or @samp{set}. This part of the name may
+be omitted if it does not apply.
@end table
-@node Shell Substitutions, Assignments, File System Conventions, Portable Shell
-@section Shell Substitutions
+The values assigned to cache variables may not contain newlines.
+Usually, their values will be boolean (@samp{yes} or @samp{no}) or the
+names of files or functions; so this is not an important restriction.
+
+@node Cache Files, Cache Checkpointing, Cache Variable Names, Caching Results
+@subsection Cache Files
-Contrary to a persistent urban legend, the Bourne shell does not
-systematically split variables and backquoted expressions, in particular
-on the right-hand side of assignments and in the argument of @code{case}.
-For instance, the following code:
+A cache file is a shell script that caches the results of configure
+tests run on one system so they can be shared between configure scripts
+and configure runs. It is not useful on other systems. If its contents
+are invalid for some reason, the user may delete or edit it.
-@example
-case "$given_srcdir" in
-.) top_srcdir="`echo "$dots" | sed 's,/$,,'`"
-*) top_srcdir="$dots$given_srcdir" ;;
-esac
-@end example
+By default, @code{configure} uses no cache file (technically, it uses
+@option{--cache-file=/dev/null}), to avoid problems caused by accidental
+use of stale cache files.
-@noindent
-is more readable when written as:
+To enable caching, @code{configure} accepts @option{--config-cache} (or
+@option{-C}) to cache results in the file @file{config.cache}.
+Alternatively, @option{--cache-file=@var{file}} specifies that
+@var{file} be the cache file. The cache file is created if it does not
+exist already. When @code{configure} calls @code{configure} scripts in
+subdirectories, it uses the @option{--cache-file} argument so that they
+share the same cache. @xref{Subdirectories}, for information on
+configuring subdirectories with the @code{AC_CONFIG_SUBDIRS} macro.
-@example
-case $given_srcdir in
-.) top_srcdir=`echo "$dots" | sed 's,/$,,'`
-*) top_srcdir=$dots$given_srcdir ;;
-esac
-@end example
+@file{config.status} only pays attention to the cache file if it is
+given the @option{--recheck} option, which makes it rerun
+@code{configure}.
-@noindent
-and in fact it is even @emph{more} portable: in the first case of the
-first attempt, the computation of @code{top_srcdir} is not portable,
-since not all shells properly understand @code{"`@dots{}"@dots{}"@dots{}`"}.
-Worse yet, not all shells understand @code{"`@dots{}\"@dots{}\"@dots{}`"}
-the same way. There is just no portable way to use double-quoted
-strings inside double-quoted backquoted expressions (pfew!).
+It is wrong to try to distribute cache files for particular system types.
+There is too much room for error in doing that, and too much
+administrative overhead in maintaining them. For any features that
+can't be guessed automatically, use the standard method of the canonical
+system type and linking files (@pxref{Manual Configuration}).
-@table @code
-@item $@@
-@cindex @samp{"$@@"}
-One of the most famous shell-portability issues is related to
-@samp{"$@@"}: when there are no positional arguments, it is supposed to
-be equivalent to nothing. But some shells, for instance under Digital
-Unix 4.0 and 5.0, will then replace it with an empty argument. To be
-portable, use @samp{$@{1+"$@@"@}}.
+The site initialization script can specify a site-wide cache file to
+use, instead of the usual per-program cache. In this case, the cache
+file will gradually accumulate information whenever someone runs a new
+@code{configure} script. (Running @code{configure} merges the new cache
+results with the existing cache file.) This may cause problems,
+however, if the system configuration (e.g. the installed libraries or
+compilers) changes and the stale cache file is not deleted.
-@item $@{@var{var}:-@var{value}@}
-@cindex $@{@var{var}:-@var{value}@}
-Old @sc{bsd} shells, including the Ultrix @code{sh}, don't accept the
-colon for any shell substitution, and complain and die.
+@node Cache Checkpointing, , Cache Files, Caching Results
+@subsection Cache Checkpointing
-@item $@{@var{var}=@var{literal}@}
-@cindex $@{@var{var}=@var{literal}@}
-Be sure to quote:
+If your configure script, or a macro called from configure.ac, happens
+to abort the configure process, it may be useful to checkpoint the cache
+a few times at key points using @code{AC_CACHE_SAVE}. Doing so will
+reduce the amount of time it takes to re-run the configure script with
+(hopefully) the error that caused the previous abort corrected.
-@example
-: $@{var='Some words'@}
-@end example
+@c FIXME: Do we really want to document this guy?
+@defmac AC_CACHE_LOAD
+@maindex CACHE_LOAD
+Loads values from existing cache file, or creates a new cache file if a
+cache file is not found. Called automatically from @code{AC_INIT}.
+@end defmac
-@noindent
-otherwise some shells, such as on Digital Unix V 5.0, will die because
-of a ``bad substitution''.
+@defmac AC_CACHE_SAVE
+@maindex CACHE_SAVE
+Flushes all cached values to the cache file. Called automatically from
+@code{AC_OUTPUT}, but it can be quite useful to call
+@code{AC_CACHE_SAVE} at key points in configure.ac.
+@end defmac
-Solaris' @command{/bin/sh} has a frightening bug in its interpretation
-of this. Imagine you need set a variable to a string containing
-@samp{@}}. This @samp{@}} character confuses Solaris' @command{/bin/sh}
-when the affected variable was already set. This bug can be exercised
-by running:
+For instance:
@example
-$ unset foo
-$ foo=$@{foo='@}'@}
-$ echo $foo
-@}
-$ foo=$@{foo='@}' # no error; this hints to what the bug is
-$ echo $foo
-@}
-$ foo=$@{foo='@}'@}
-$ echo $foo
-@}@}
- ^ ugh!
-@end example
-
-It seems that @samp{@}} is interpreted as matching @samp{$@{}, even
-though it is enclosed in single quotes. The problem doesn't happen
-using double quotes.
+@r{ @dots{} AC_INIT, etc. @dots{}}
+@group
+# Checks for programs.
+AC_PROG_CC
+AC_PROG_GCC_TRADITIONAL
+@r{ @dots{} more program checks @dots{}}
+AC_CACHE_SAVE
+@end group
-@item $@{@var{var}=@var{expanded-value}@}
-@cindex $@{@var{var}=@var{expanded-value}@}
-On Ultrix,
-running
+@group
+# Checks for libraries.
+AC_CHECK_LIB(nsl, gethostbyname)
+AC_CHECK_LIB(socket, connect)
+@r{ @dots{} more lib checks @dots{}}
+AC_CACHE_SAVE
+@end group
-@example
-default="yu,yaa"
-: $@{var="$default"@}
+@group
+# Might abort...
+AM_PATH_GTK(1.0.2,, (exit 1); exit)
+AM_PATH_GTKMM(0.9.5,, (exit 1); exit)
+@end group
+@r{ @dots{} AC_OUTPUT, etc. @dots{}}
@end example
-@noindent
-will set @var{var} to @samp{M-yM-uM-,M-yM-aM-a}, i.e., the 8th bit of
-each char will be set. You won't observe the phenomenon using a simple
-@samp{echo $var} since apparently the shell resets the 8th bit when it
-expands $var. Here are two means to make this shell confess its sins:
+@node Printing Messages, , Caching Results, Results
+@section Printing Messages
+@cindex Messages, from @code{configure}
-@example
-$ cat -v <<EOF
-$var
-EOF
-@end example
+@code{configure} scripts need to give users running them several kinds
+of information. The following macros print messages in ways appropriate
+for each kind. The arguments to all of them get enclosed in shell
+double quotes, so the shell performs variable and back-quote
+substitution on them.
-@noindent
-and
+These macros are all wrappers around the @code{echo} shell command.
+@code{configure} scripts should rarely need to run @code{echo} directly
+to print messages for the user. Using these macros makes it easy to
+change how and when each kind of message is printed; such changes need
+only be made to the macro definitions and all of the callers will change
+automatically.
-@example
-$ set | grep '^var=' | cat -v
-@end example
+To diagnose static issues, i.e., when @code{autoconf} is run, see
+@ref{Reporting Messages}.
-One classic incarnation of this bug is:
+@defmac AC_MSG_CHECKING (@var{feature-description})
+@maindex MSG_CHECKING
+Notify the user that @code{configure} is checking for a particular
+feature. This macro prints a message that starts with @samp{checking }
+and ends with @samp{...} and no newline. It must be followed by a call
+to @code{AC_MSG_RESULT} to print the result of the check and the
+newline. The @var{feature-description} should be something like
+@samp{whether the Fortran compiler accepts C++ comments} or @samp{for
+c89}.
-@example
-default="a b c"
-: $@{list="$default"@}
-for c in $list; do
- echo $c
-done
-@end example
+This macro prints nothing if @code{configure} is run with the
+@option{--quiet} or @option{--silent} option.
+@end defmac
-@noindent
-You'll get @samp{a b c} on a single line. Why? Because there are no
-spaces in @samp{$list}: there are @samp{M- }, i.e., spaces with the 8th
-bit set, hence no IFS splitting is performed!!!
+@defmac AC_MSG_RESULT (@var{result-description})
+@maindex MSG_RESULT
+Notify the user of the results of a check. @var{result-description} is
+almost always the value of the cache variable for the check, typically
+@samp{yes}, @samp{no}, or a file name. This macro should follow a call
+to @code{AC_MSG_CHECKING}, and the @var{result-description} should be
+the completion of the message printed by the call to
+@code{AC_MSG_CHECKING}.
-One piece of good news is that Ultrix works fine with @samp{:
-$@{list=$default@}}; i.e., if you @emph{don't} quote. The bad news is
-then that @sc{qnx} 4.25 then sets @var{list} to the @emph{last} item of
-@var{default}!
+This macro prints nothing if @code{configure} is run with the
+@option{--quiet} or @option{--silent} option.
+@end defmac
-The portable way out consists in using a double assignment, to switch
-the 8th bit twice on Ultrix:
+@defmac AC_MSG_NOTICE (@var{message})
+@maindex MSG_NOTICE
+Deliver the @var{message} to the user. It is useful mainly to print a
+general description of the overall purpose of a group of feature checks,
+e.g.,
@example
-list=$@{list="$default"@}
+AC_MSG_NOTICE([checking if stack overflow is detectable])
@end example
-@noindent
-@dots{}but beware of the @samp{@}} bug from Solaris (see above). For safety,
-use:
+This macro prints nothing if @code{configure} is run with the
+@option{--quiet} or @option{--silent} option.
+@end defmac
-@example
-test "$@{var+set@}" = set || var=@var{@{value@}}
-@end example
+@defmac AC_MSG_ERROR (@var{error-description}, @ovar{exit-status})
+@maindex MSG_ERROR
+Notify the user of an error that prevents @code{configure} from
+completing. This macro prints an error message to the standard error
+output and exits @code{configure} with @var{exit-status} (1 by default).
+@var{error-description} should be something like @samp{invalid value
+$HOME for \$HOME}.
+The @var{error-description} should start with a lower-case letter, and
+``cannot'' is preferred to ``can't''.
+@end defmac
-@item `@var{commands}`
-@cindex `@var{commands}`
-@cindex Command Substitution
-While in general it makes no sense, do not substitute a single builtin
-with side effects as Ash 0.2, trying to optimize, does not fork a
-sub-shell to perform the command.
+@defmac AC_MSG_WARN (@var{problem-description})
+@maindex MSG_WARN
+Notify the @code{configure} user of a possible problem. This macro
+prints the message to the standard error output; @code{configure}
+continues running afterward, so macros that call @code{AC_MSG_WARN} should
+provide a default (back-up) behavior for the situations they warn about.
+@var{problem-description} should be something like @samp{ln -s seems to
+make hard links}.
+@end defmac
-For instance, if you wanted to check that @command{cd} is silent, do not
-use @samp{test -z "`cd /`"} because the following can happen:
-@example
-$ pwd
-/tmp
-$ test -n "`cd /`" && pwd
-/
-@end example
-@noindent
-The result of @samp{foo=`exit 1`} is left as an exercise to the reader.
+@c ========================================================== Writing Macros.
+@node Writing Macros, Portable Shell, Results, Top
+@chapter Writing Macros
-@item $(@var{commands})
-@cindex $(@var{commands})
-This construct is meant to replace @samp{`@var{commands}`}; they can be
-nested while this is impossible to do portably with back quotes.
-Unfortunately it is not yet widely supported. Most notably, even recent
-releases of Solaris don't support it:
+When you write a feature test that could be applicable to more than one
+software package, the best thing to do is encapsulate it in a new macro.
+Here are some instructions and guidelines for writing Autoconf macros.
-@example
-$ showrev -c /bin/sh | grep version
-Command version: SunOS 5.8 Generic 109324-02 February 2001
-$ echo $(echo blah)
-syntax error: `(' unexpected
-@end example
+@menu
+* Macro Definitions:: Basic format of an Autoconf macro
+* Macro Names:: What to call your new macros
+* Quoting:: Protecting macros from unwanted expansion
+* Reporting Messages:: Notifying @code{autoconf} users
+* Dependencies Between Macros:: What to do when macros depend on other macros
+* Obsoleting Macros:: Warning about old ways of doing things
+* Coding Style:: Writing Autoconf macros @`a la Autoconf
+@end menu
+
+@node Macro Definitions, Macro Names, Writing Macros, Writing Macros
+@section Macro Definitions
+
+@maindex DEFUN
+Autoconf macros are defined using the @code{AC_DEFUN} macro, which is
+similar to the M4 builtin @code{define} macro. 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}).
+
+An Autoconf macro definition looks like this:
-@noindent
-nor does @sc{irix} 6.5's Bourne shell:
@example
-$ uname -a
-IRIX firebird-image 6.5 07151432 IP22
-$ echo $(echo blah)
-$(echo blah)
+AC_DEFUN(@var{macro-name}, @var{macro-body})
@end example
-@end table
-
-@node Assignments, Special Shell Variables, Shell Substitutions, Portable Shell
-@section Assignments
+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,
+GNU m4}, for more complete information on writing M4 macros.
-When setting several variables in a row, be aware that the order of the
-evaluation is undefined. For instance @samp{foo=1 foo=2; echo $foo}
-gives @samp{1} with sh on Solaris, but @samp{2} with Bash. You must use
-@samp{;} to enforce the order: @samp{foo=1; foo=2; echo $foo}.
+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.
-Don't rely on the exit status of an assignment: Ash 0.2 does not change
-the status and propagates that of the last statement:
+Each macro should have a header comment that gives its prototype, and a
+brief description. When arguments have default values, display them in
+the prototype. For example:
@example
-$ false || foo=bar; echo $?
-1
-$ false || foo=`:`; echo $?
-0
+# AC_MSG_ERROR(ERROR, [EXIT-STATUS = 1])
+# --------------------------------------
+define([AC_MSG_ERROR],
+[@{ _AC_ECHO([configure: error: $1], 2); exit m4_default([$2], 1); @}])
@end example
-@noindent
-and to make things even worse, @sc{qnx 4.25} just sets the exit status
-to 0 in any case:
+Comments about the macro should be left in the header comment. Most
+other comments will make their way into @file{configure}, so just keep
+using @samp{#} to introduce comments.
-@example
-$ foo=`exit 1`; echo $?
-0
-@end example
+@cindex @code{dnl}
+If you have some very special comments about pure M4 code, comments
+that make no sense in @file{configure} and in the header comment, then
+use the builtin @code{dnl}: it causes @code{m4} to discard the text
+through the next newline.
-To assign default values, follow this algorithm:
+Keep in mind that @code{dnl} is rarely needed to introduce comments;
+@code{dnl} is more useful to get rid of the newlines following macros
+that produce no output, such as @code{AC_REQUIRE}.
-@enumerate
-@item
-If the default value is a literal and does not contain any closing
-brace, use:
-@example
-: $@{var='my literal'@}
-@end example
+@node Macro Names, Quoting, Macro Definitions, Writing Macros
+@section Macro Names
-@item
-If the default value contains no closing brace, has to be expanded, and
-the variable being initialized will never be IFS-split (i.e., it's not a
-list), then use:
+All of the Autoconf macros have all-uppercase names starting with
+@samp{AC_} to prevent them from accidentally conflicting with other
+text. All shell variables that they use for internal purposes have
+mostly-lowercase names starting with @samp{ac_}. To ensure that your
+macros don't conflict with present or future Autoconf macros, you should
+prefix your own macro names and any shell variables they use with some
+other sequence. Possibilities include your initials, or an abbreviation
+for the name of your organization or software package.
-@example
-: $@{var="$default"@}
-@end example
+Most of the Autoconf macros' names follow a structured naming convention
+that indicates the kind of feature check by the name. The macro names
+consist of several words, separated by underscores, going from most
+general to most specific. The names of their cache variables use the
+same convention (@pxref{Cache Variable Names}, for more information on
+them).
-@item
-If the default value contains no closing brace, has to be expanded, and
-the variable being initialized will be IFS-split (i.e., it's a list),
-then use:
+The first word of the name after @samp{AC_} usually tells the category
+of feature being tested. Here are the categories used in Autoconf for
+specific test macros, the kind of macro that you are more likely to
+write. They are also used for cache variables, in all-lowercase. Use
+them where applicable; where they're not, invent your own categories.
-@example
-var=$@{var="$default"@}
-@end example
+@table @code
+@item C
+C language builtin features.
+@item DECL
+Declarations of C variables in header files.
+@item FUNC
+Functions in libraries.
+@item GROUP
+@sc{unix} group owners of files.
+@item HEADER
+Header files.
+@item LIB
+C libraries.
+@item PATH
+The full path names to files, including programs.
+@item PROG
+The base names of programs.
+@item MEMBER
+Members of aggregates.
+@item SYS
+Operating system features.
+@item TYPE
+C builtin or declared types.
+@item VAR
+C variables in libraries.
+@end table
-@item
-If the default value contains a closing brace, then use:
+After the category comes the name of the particular feature being
+tested. Any further words in the macro name indicate particular aspects
+of the feature. For example, @code{AC_FUNC_UTIME_NULL} checks the
+behavior of the @code{utime} function when called with a @code{NULL}
+pointer.
-@example
-test "$@{var+set@}" = set || var='$@{indirection@}'
-@end example
-@end enumerate
+An internal macro should have a name that starts with an underscore;
+Autoconf internals should therefore start with @samp{_AC_}.
+Additionally, a macro that is an internal subroutine of another macro
+should have a name that starts with an underscore and the name of that
+other macro, followed by one or more words saying what the internal
+macro does. For example, @code{AC_PATH_X} has internal macros
+@code{_AC_PATH_X_XMKMF} and @code{_AC_PATH_X_DIRECT}.
-In most cases @samp{var=$@{var="$default"@}} is fine, but in case of
-doubt, just use the latter. @xref{Shell Substitutions}, items
-@samp{$@{@var{var}:-@var{value}@}} and @samp{$@{@var{var}=@var{value}@}}
-for the rationale.
+@node Quoting, Reporting Messages, Macro Names, Writing Macros
+@section Quoting
+@cindex quotation
+@c FIXME: Grmph, yet another quoting myth: quotation has *never*
+@c prevented `expansion' of $1. Unless it refers to the expansion
+@c of the value of $1? Anyway, we need a rewrite here@dots{}
-@node Special Shell Variables, Limitations of Builtins, Assignments, Portable Shell
-@section Special Shell Variables
+The most common brokenness of existing macros is an improper quotation.
+This section, which users of Autoconf can skip, but which macro writers
+@emph{must} read, first justifies the quotation scheme that was chosen
+for Autoconf and then ends with a rule of thumb. Understanding the
+former helps one to follow the latter.
-Some shell variables should not be used, since they can have a deep
-influence on the behavior of the shell. In order to recover a sane
-behavior from the shell, some variables should be unset, but
-@command{unset} is not portable (@pxref{Limitations of Builtins}) and a
-fallback value is needed. We list these values below.
+@menu
+* Active Characters:: Characters that change the behavior of m4
+* One Macro Call:: Quotation and one macro call
+* Quotation and Nested Macros:: Macros calling macros
+* Quotation Rule Of Thumb:: One parenthesis, one quote
+@end menu
-@c Alphabetical order, case insensitive, `A' before `a'.
-@table @code
-@item CDPATH
-@evindex CDPATH
-When this variable is set @code{cd} is verbose, so idioms such as
-@samp{abs=`cd $rel && pwd`} break because @code{abs} receives the path
-twice.
+@node Active Characters, One Macro Call, Quoting, Quoting
+@subsection Active Characters
-@c FIXME: Which shells? How do they behave?
-Setting @code{CDPATH} to the empty value is not enough for most shells.
-A simple colon is enough except for @code{zsh}, which prefers a leading
-dot:
+To fully understand where proper quotation is important, you first need
+to know what are the special characters in Autoconf: @samp{#} introduces
+a comment inside which no macro expansion is performed, @samp{,}
+separates arguments, @samp{[} and @samp{]} are the quotes themselves,
+and finally @samp{(} and @samp{)} (which @code{m4} tries to match by
+pairs).
-@example
-zsh-3.1.6 % mkdir foo && (CDPATH=: cd foo)
-/tmp/foo
-zsh-3.1.6 % (CDPATH=:. cd foo)
-/tmp/foo
-zsh-3.1.6 % (CDPATH=.: cd foo)
-zsh-3.1.6 %
-@end example
+In order to understand the delicate case of macro calls, we first have
+to present some obvious failures. Below they are ``obvious-ified'',
+although you find them in real life, they are usually in disguise.
-@noindent
-(of course we could just @code{unset} @code{CDPATH}, since it also
-behaves properly if set to the empty string).
+Comments, introduced by a hash and running up to the newline, are opaque
+tokens to the top level: active characters are turned off, and there is
+no macro expansion:
+
+@example
+# define([def], ine)
+@result{}# define([def], ine)
+@end example
-Life wouldn't be so much fun if @command{bash} and @command{zsh} had the
-same behavior:
+Each time there can be a macro expansion, there is a quotation
+expansion; i.e., one level of quotes is stripped:
@example
-bash-2.02 % (CDPATH=:. cd foo)
-bash-2.02 % (CDPATH=.: cd foo)
-/tmp/foo
+int tab[10];
+@result{}int tab10;
+[int tab[10];]
+@result{}int tab[10];
@end example
-Therefore, a portable solution to neutralize @samp{CDPATH} is
+Without this in mind, the reader will try hopelessly to use her macro
+@code{array}:
@example
-CDPATH=$@{ZSH_VERSION+.@}:
+define([array], [int tab[10];])
+array
+@result{}int tab10;
+[array]
+@result{}array
@end example
@noindent
-Note that since @command{zsh} supports @command{unset}, you may unset
-@samp{CDPATH} using @samp{:} as a fallback, see
-@ref{Limitations of Builtins}.
-
-@item IFS
-@evindex IFS
-Don't set the first character of @code{IFS} to backslash. Indeed,
-Bourne shells use the first character (backslash) when joining the
-components in @samp{"$@@"} and some shells then re-interpret (!) the
-backslash escapes, so you can end up with backspace and other strange
-characters.
-
-@item LANG
-@itemx LC_ALL
-@itemx LC_TIME
-@itemx LC_CTYPE
-@itemx LANGUAGE
-@itemx LC_COLLATE
-@itemx LC_NUMERIC
-@itemx LC_MESSAGES
-@evindex LANG
-@evindex LC_ALL
-@evindex LC_TIME
-@evindex LC_CTYPE
-@evindex LANGUAGE
-@evindex LC_COLLATE
-@evindex LC_NUMERIC
-@evindex LC_MESSAGES
-
-These must not be set unconditionally because not all systems understand
-e.g. @samp{LANG=C} (notably SCO). Fixing @env{LC_MESSAGES} prevents
-Solaris @command{sh} from translating var values in @code{set}! Non-C
-@env{LC_CTYPE} values break the ctype check. Fixing @env{LC_COLLATE}
-makes scripts more portable in some cases. For example, it causes the
-regular expression @samp{[a-z]} to match only lower-case letters on
-@sc{ascii} platforms. However, @samp{[a-z]} does not work in general
-even when @env{LC_COLLATE} is fixed; for example, it does not work for
-@sc{ebcdic} platforms. For maximum portability, you should use regular
-expressions like @samp{[abcdefghijklmnopqrstuvwxyz]} that list
-characters explicitly instead of relying on ranges.
-
-@emph{If} one of these variables is set, you should try to unset it,
-using @samp{C} as a fall back value. see @ref{Limitations of Builtins},
-builtin @command{unset}, for more details.
-
-@item NULLCMD
-@evindex NULLCMD
-When executing the command @samp{>foo}, @command{zsh} executes
-@samp{$NULLCMD >foo}. The Bourne shell considers @code{NULLCMD} is
-@samp{:}, while @command{zsh}, even in Bourne shell compatibility mode,
-sets @code{NULLCMD} to @samp{cat}. If you forgot to set @code{NULLCMD},
-your script might be suspended waiting for data on its standard input.
-
-@item status
-@evindex status
-This variable is an alias to @samp{$?} for @code{zsh} (at least 3.1.6),
-hence read-only. Do not use it.
-
-@item PATH_SEPARATOR
-@evindex PATH_SEPARATOR
-On DJGPP systems, the @code{PATH_SEPARATOR} variable can be set to
-either @samp{:} or @samp{;} to control the path separator @command{bash}
-uses to set up certain environment variables (such as
-@code{PATH}). Since this only works inside bash, you want autoconf to
-detect the regular @sc{dos} path separator @samp{;}, so it can be safely
-substituted in files that may not support @samp{;} as path separator. So
-either unset this variable or set it to @samp{;}.
+How can you correctly output the intended results@footnote{Using
+@code{defn}.}?
-@item RANDOM
-@evindex RANDOM
-Many shells provide @code{RANDOM}, a variable that returns a different
-integer when used. Most of the time, its value does not change when it
-is not used, but on @sc{irix 6.5} the value changes all the time. This
-can be observed by using @command{set}.
-@end table
+@node One Macro Call, Quotation and Nested Macros, Active Characters, Quoting
+@subsection One Macro Call
-@node Limitations of Builtins, Limitations of Usual Tools, Special Shell Variables, Portable Shell
-@section Limitations of Shell Builtins
+Let's proceed on the interaction between active characters and macros
+with this small macro, which just returns its first argument:
-No, no, we are serious: some shells do have limitations! :)
+@example
+define([car], [$1])
+@end example
-You should always keep in mind that any built-in or command may support
-options, and therefore have a very different behavior with arguments
-starting with a dash. For instance, the innocent @samp{echo "$word"}
-can give unexpected results when @code{word} starts with a dash. It is
-often possible to avoid this problem using @samp{echo "x$word"}, taking
-the @samp{x} into account later in the pipe.
+@noindent
+The two pairs of quotes above are not part of the arguments of
+@code{define}; rather, they are understood by the top level when it
+tries to find the arguments of @code{define}. Therefore, it is
+equivalent to write:
-@table @asis
-@item @command{!}
-@cindex @command{!}
-You can't use @command{!}, you'll have to rewrite your code.
+@example
+define(car, $1)
+@end example
+@noindent
+But, while it is acceptable for a @file{configure.ac} to avoid unneeded
+quotes, it is bad practice for Autoconf macros which must both be more
+robust and also advocate perfect style.
-@item @command{break}
-@c ------------------
-@cindex @command{break}
-The use of @samp{break 2}, etcetera, is safe.
+At the top level, there are only two possible quotings: either you
+quote or you don't:
+@example
+car(foo, bar, baz)
+@result{}foo
+[car(foo, bar, baz)]
+@result{}car(foo, bar, baz)
+@end example
-@item @command{case}
-@c -----------------
-@cindex @command{case}
-You don't need to quote the argument; no splitting is performed.
+Let's pay attention to the special characters:
-You don't need the final @samp{;;}, but you should use it.
+@example
+car(#)
+@error{}EOF in argument list
+@end example
-Because of a bug in its @code{fnmatch}, @command{bash} fails to properly
-handle backslashes in character classes:
+The closing parenthesis is hidden in the comment; with a hypothetical
+quoting, the top level understood it this way:
@example
-bash-2.02$ case /tmp in [/\\]*) echo OK;; esac
-bash-2.02$
+car([#)]
@end example
@noindent
-This is extremely unfortunate, since you are likely to use this code to
-handle @sc{unix} or @sc{ms-dos} absolute paths. To work around this
-bug, always put the backslash first:
+Proper quotation, of course, fixes the problem:
@example
-bash-2.02$ case '\TMP' in [\\/]*) echo OK;; esac
-OK
-bash-2.02$ case /tmp in [\\/]*) echo OK;; esac
-OK
+car([#])
+@result{}#
@end example
+The reader will easily understand the following examples:
-@item @command{echo}
-@c -----------------
-@cindex @command{echo}
-The simple @code{echo} is probably the most surprising source of
-portability troubles. It is not possible to use @samp{echo} portably
-unless both options and escape sequences are omitted. New applications
-which are not aiming at portability should use @samp{printf} instead of
-@samp{echo}.
+@example
+car(foo, bar)
+@result{}foo
+car([foo, bar])
+@result{}foo, bar
+car((foo, bar))
+@result{}(foo, bar)
+car([(foo], [bar)])
+@result{}(foo
+car([], [])
+@result{}
+car([[]], [[]])
+@result{}[]
+@end example
-Don't expect any option. @xref{Preset Output Variables}, @code{ECHO_N}
-etc. for a means to simulate @option{-c}.
+With this in mind, we can explore the cases where macros invoke
+macros@dots{}
-Do not use backslashes in the arguments, as there is no consensus on
-their handling. On @samp{echo '\n' | wc -l}, the @command{sh} of
-Digital Unix 4.0, @sc{mips risc/os} 4.52, answer 2, but the Solaris'
-@command{sh}, Bash and Zsh (in @command{sh} emulation mode) report 1.
-Please note that the problem is truly @command{echo}: all the shells
-understand @samp{'\n'} as the string composed of a backslash and an
-@samp{n}.
-Because of these problems, do not pass a string containing arbitrary
-characters to @command{echo}. For example, @samp{echo "$foo"} is safe
-if you know that @var{foo}'s value cannot contain backslashes and cannot
-start with @samp{-}, but otherwise you should use a here-document like
-this:
+@node Quotation and Nested Macros, Quotation Rule Of Thumb, One Macro Call, Quoting
+@subsection Quotation and Nested Macros
+
+The examples below use the following macros:
@example
-cat <<EOF
-$foo
-EOF
+define([car], [$1])
+define([active], [ACT, IVE])
+define([array], [int tab[10]])
@end example
-
-@item @command{exit}
-@c -----------------
-@cindex @command{exit}
-The default value of @command{exit} is supposed to be @code{$?};
-unfortunately, some shells, such as the DJGPP port of Bash 2.04, just
-perform @samp{exit 0}.
+Each additional embedded macro call introduces other possible
+interesting quotations:
@example
-bash-2.04$ foo=`exit 1` || echo fail
-fail
-bash-2.04$ foo=`(exit 1)` || echo fail
-fail
-bash-2.04$ foo=`(exit 1); exit` || echo fail
-bash-2.04$
+car(active)
+@result{}ACT
+car([active])
+@result{}ACT, IVE
+car([[active]])
+@result{}active
@end example
-Using @samp{exit $?} restores the expected behavior.
-
-Some shell scripts, such as those generated by @command{autoconf}, use a
-trap to clean up before exiting. If the last shell command exited with
-nonzero status, the trap also exits with nonzero status so that the
-invoker can tell that an error occurred.
+In the first case, the top level looks for the arguments of @code{car},
+and finds @samp{active}. Because @code{m4} evaluates its arguments
+before applying the macro, @samp{active} is expanded, which results in:
-Unfortunately, in some shells, such as Solaris 8 @command{sh}, an exit
-trap ignores the @code{exit} command's status. In these shells, a trap
-cannot determine whether it was invoked by plain @code{exit} or by
-@code{exit 1}. Instead of calling @code{exit} directly, use the
-@code{AC_MSG_ERROR} macro that has a workaround for this problem.
+@example
+car(ACT, IVE)
+@result{}ACT
+@end example
+@noindent
+In the second case, the top level gives @samp{active} as first and only
+argument of @code{car}, which results in:
-@item @command{export}
-@c -------------------
-@cindex @command{export}
-The builtin @command{export} dubs @dfn{environment variable} a shell
-variable. Each update of exported variables corresponds to an update of
-the environment variables. Conversely, each environment variable
-received by the shell when it is launched should be imported as a shell
-variable marked as exported.
+@example
+active
+@result{}ACT, IVE
+@end example
-Alas, many shells, such as Solaris 2.5, IRIX 6.3, IRIX 5.2, AIX 4.1.5
-and DU 4.0, forget to @command{export} the environment variables they
-receive. As a result, two variables are coexisting: the environment
-variable and the shell variable. The following code demonstrates this
-failure:
+@noindent
+i.e., the argument is evaluated @emph{after} the macro that invokes it.
+In the third case, @code{car} receives @samp{[active]}, which results in:
@example
-#! /bin/sh
-echo $FOO
-FOO=bar
-echo $FOO
-exec /bin/sh $0
+[active]
+@result{}active
@end example
@noindent
-when run with @samp{FOO=foo} in the environment, these shells will print
-alternately @samp{foo} and @samp{bar}, although it should only print
-@samp{foo} and then a sequence of @samp{bar}s.
-
-Therefore you should @command{export} again each environment variable
-that you update.
+exactly as we already saw above.
+The example above, applied to a more realistic example, gives:
-@item @command{false}
-@c ------------------
-@cindex @command{false}
-Don't expect @command{false} to exit with status 1: in the native Bourne
-shell of Solaris 8, it exits with status 255.
+@example
+car(int tab[10];)
+@result{}int tab10;
+car([int tab[10];])
+@result{}int tab10;
+car([[int tab[10];]])
+@result{}int tab[10];
+@end example
+@noindent
+Huh? The first case is easily understood, but why is the second wrong,
+and the third right? To understand that, you must know that after
+@code{m4} expands a macro, the resulting text is immediately subjected
+to macro expansion and quote removal. This means that the quote removal
+occurs twice---first before the argument is passed to the @code{car}
+macro, and second after the @code{car} macro expands to the first
+argument.
-@item @command{for}
-@c ----------------
-@cindex @command{for}
-To loop over positional arguments, use:
+As the author of the Autoconf macro @code{car}, you then consider it to
+be incorrect that your users have to double-quote the arguments of
+@code{car}, so you ``fix'' your macro. Let's call it @code{qar} for
+quoted car:
@example
-for arg
-do
- echo "$arg"
-done
+define([qar], [[$1]])
@end example
@noindent
-You may @emph{not} leave the @code{do} on the same line as @code{for},
-since some shells improperly grok:
+and check that @code{qar} is properly fixed:
@example
-for arg; do
- echo "$arg"
-done
+qar([int tab[10];])
+@result{}int tab[10];
@end example
-If you want to explicitly refer to the positional arguments, given the
-@samp{$@@} bug (@pxref{Shell Substitutions}), use:
+@noindent
+Ahhh! That's much better.
+
+But note what you've done: now that the arguments are literal strings,
+if the user wants to use the results of expansions as arguments, she has
+to use an @emph{unquoted} macro call:
@example
-for arg in $@{1+"$@@"@}; do
- echo "$arg"
-done
+qar(active)
+@result{}ACT
@end example
-@item @command{if}
-@c ---------------
-@cindex @command{if}
-Using @samp{!} is not portable. Instead of:
+@noindent
+where she wanted to reproduce what she used to do with @code{car}:
@example
-if ! cmp -s file file.new; then
- mv file.new file
-fi
+car([active])
+@result{}ACT, IVE
@end example
@noindent
-use:
+Worse yet: she wants to use a macro that produces a set of @code{cpp}
+macros:
@example
-if cmp -s file file.new; then :; else
- mv file.new file
-fi
+define([my_includes], [#include <stdio.h>])
+car([my_includes])
+@result{}#include <stdio.h>
+qar(my_includes)
+@error{}EOF in argument list
@end example
-There are shells that do not reset the exit status from an @command{if}:
+This macro, @code{qar}, because it double quotes its arguments, forces
+its users to leave their macro calls unquoted, which is dangerous.
+Commas and other active symbols are interpreted by @code{m4} before
+they are given to the macro, often not in the way the users expect.
+Also, because @code{qar} behaves differently from the other macros,
+it's an exception that should be avoided in Autoconf.
+
+@node Quotation Rule Of Thumb, , Quotation and Nested Macros, Quoting
+@subsection Quotation Rule Of Thumb
+
+To conclude, the quotation rule of thumb is:
+
+@center @emph{One pair of quotes per pair of parentheses.}
+
+Never over-quote, never under-quote, in particular in the definition of
+macros. In the few places where the macros need to use brackets
+(usually in C program text or regular expressions), properly quote
+@emph{the arguments}!
+
+It is common to read Autoconf programs with snippets like:
@example
-$ if (exit 42); then true; fi; echo $?
-42
+AC_TRY_LINK(
+changequote(<<, >>)dnl
+<<#include <time.h>
+#ifndef tzname /* For SGI. */
+extern char *tzname[]; /* RS6000 and others reject char **tzname. */
+#endif>>,
+changequote([, ])dnl
+[atoi (*tzname);], ac_cv_var_tzname=yes, ac_cv_var_tzname=no)
@end example
@noindent
-whereas a proper shell should have printed @samp{0}. This is especially
-bad in Makefiles since it produces false failures. This is why properly
-written Makefiles, such as Automake's, have such hairy constructs:
+which is incredibly useless since @code{AC_TRY_LINK} is @emph{already}
+double quoting, so you just need:
@example
-if test -f "$file"; then
- install "$file" "$dest"
-else
- :
-fi
+AC_TRY_LINK(
+[#include <time.h>
+#ifndef tzname /* For SGI. */
+extern char *tzname[]; /* RS6000 and others reject char **tzname. */
+#endif],
+ [atoi (*tzname);],
+ [ac_cv_var_tzname=yes],
+ [ac_cv_var_tzname=no])
@end example
+@noindent
+The M4-fluent reader will note that these two examples are rigorously
+equivalent, since @code{m4} swallows both the @samp{changequote(<<, >>)}
+and @samp{<<} @samp{>>} when it @dfn{collects} the arguments: these
+quotes are not part of the arguments!
-@item @command{set}
-@c ----------------
-@cindex @command{set}
-This builtin faces the usual problem with arguments starting with a
-dash. Modern shells such as Bash or Zsh understand @option{--} to specify
-the end of the options (any argument after @option{--} is a parameters,
-even @samp{-x} for instance), but most shells simply stop the option
-processing as soon as a non-option argument is found. Therefore, use
-@samp{dummy} or simply @samp{x} to end the option processing, and use
-@command{shift} to pop it out:
+Simplified, the example above is just doing this:
@example
-set x $my_list; shift
+changequote(<<, >>)dnl
+<<[]>>
+changequote([, ])dnl
@end example
-@item @command{shift}
-@c ------------------
-@cindex @command{shift}
-Not only is @command{shift}ing a bad idea when there is nothing left to
-shift, but in addition it is not portable: the shell of @sc{mips
-risc/os} 4.52 refuses to do it.
+@noindent
+instead of simply:
-@item @command{test}
-@c -----------------
-@cindex @command{test}
-The @code{test} program is the way to perform many file and string
-tests. It is often invoked by the alternate name @samp{[}, but using
-that name in Autoconf code is asking for trouble since it is an M4 quote
-character.
+@example
+[[]]
+@end example
-If you need to make multiple checks using @code{test}, combine them with
-the shell operators @samp{&&} and @samp{||} instead of using the
-@code{test} operators @option{-a} and @option{-o}. On System V, the
-precedence of @option{-a} and @option{-o} is wrong relative to the unary
-operators; consequently, @sc{posix} does not specify them, so using them
-is nonportable. If you combine @samp{&&} and @samp{||} in the same
-statement, keep in mind that they have equal precedence.
-You may use @samp{!} with @command{test}, but not with @command{if}:
-@samp{test ! -r foo || exit 1}.
+With macros that do not double quote their arguments (which is the
+rule), double-quote the (risky) literals:
-@item @command{test} (files)
-@c -------------------------
-To enable @code{configure} scripts to support cross-compilation, they
-shouldn't do anything that tests features of the build system instead of
-the host system. But occasionally you may find it necessary to check
-whether some arbitrary file exists. To do so, use @samp{test -f} or
-@samp{test -r}. Do not use @samp{test -x}, because @sc{4.3bsd} does not
-have it. Do not use @samp{test -e} either, because Solaris 2.5 does not
-have it.
+@example
+AC_LINK_IFELSE([AC_LANG_PROGRAM(
+[[#include <time.h>
+#ifndef tzname /* For SGI. */
+extern char *tzname[]; /* RS6000 and others reject char **tzname. */
+#endif]],
+ [atoi (*tzname);])],
+ [ac_cv_var_tzname=yes],
+ [ac_cv_var_tzname=no])
+@end example
-@item @command{test} (strings)
-@c ---------------------------
-Avoid @samp{test "@var{string}"}, in particular if @var{string} might
-start with a dash, since @code{test} might interpret its argument as an
-option (e.g., @samp{@var{string} = "-n"}).
+@c FIXME: Quadrigraphs and hopeless cases.
-Contrary to a common belief, @samp{test -n @var{string}} and @samp{test
--z @var{string}} @strong{are} portable, nevertheless many shells (such
-as Solaris 2.5, AIX 3.2, UNICOS 10.0.0.6, Digital Unix 4 etc.) have
-bizarre precedence and may be confused if @var{string} looks like an
-operator:
+When you create a @code{configure} script using newly written macros,
+examine it carefully to check whether you need to add more quotes in
+your macros. If one or more words have disappeared in the @code{m4}
+output, you need more quotes. When in doubt, quote.
+
+However, it's also possible to put on too many layers of quotes. If
+this happens, the resulting @code{configure} script will contain
+unexpanded macros. The @code{autoconf} program checks for this problem
+by doing @samp{grep AC_ configure}.
-@example
-$ test -n =
-test: argument expected
-@end example
-If there are risks, use @samp{test "x@var{string}" = x} or @samp{test
-"x@var{string}" != x} instead.
+@node Reporting Messages, Dependencies Between Macros, Quoting, Writing Macros
+@section Reporting Messages
+@cindex Messages, from @code{autoconf}
-It is frequent to find variations of the following idiom:
+When macros statically diagnose abnormal situations, benign or fatal,
+they should report them using these macros. For dynamic issues, i.e.,
+when @code{configure} is run, see @ref{Printing Messages}.
-@example
-test -n "`echo $ac_feature | sed 's/[-a-zA-Z0-9_]//g'`" &&
- @var{action}
-@end example
+@defmac AC_DIAGNOSE (@var{category}, @var{message})
+@maindex DIAGNOSE
+Report @var{message} as a warning (or as an error if requested by the
+user) if it falls into the @var{category}. You are encouraged to use
+standard categories, which currently include:
-@noindent
-to take an action when a token matches a given pattern. Such constructs
-should always be avoided by using:
+@table @samp
+@item all
+messages that don't fall into one of the following category. Use of an
+empty @var{category} is equivalent.
-@example
-echo "$ac_feature" | grep '[^-a-zA-Z0-9_]' >/dev/null 2>&1 &&
- @var{action}
-@end example
+@item cross
+related to cross compilation issues.
-@noindent
-Use @code{case} where possible since it is faster, being a shell builtin:
+@item obsolete
+use of an obsolete construct.
+@item syntax
+dubious syntactic constructs, incorrectly ordered macro calls.
+@end table
+@end defmac
-@example
-case $ac_feature in
- *[!-a-zA-Z0-9_]*) @var{action};;
-esac
-@end example
+@defmac AC_WARNING (@var{message})
+@maindex WARNING
+Equivalent to @samp{AC_DIAGNOSE([syntax], @var{message})}, but you are
+strongly encouraged to use a finer grained category.
+@end defmac
-Alas, negated character classes are probably not portable, although no
-shell is known to not support the @sc{posix.2} syntax @samp{[!@dots{}]}
-(when in interactive mode, @command{zsh} is confused by the
-@samp{[!@dots{}]} syntax and looks for an event in its history because of
-@samp{!}). Many shells do not support the alternative syntax
-@samp{[^@dots{}]} (Solaris, Digital Unix, etc.).
+@defmac AC_FATAL (@var{message})
+@maindex FATAL
+Report a severe error @var{message}, and have @code{autoconf} die.
+@end defmac
-One solution can be:
+When the user runs @samp{autoconf -W error}, warnings from
+@code{AC_DIAGNOSE} and @code{AC_WARNING} are reported as error, see
+@ref{autoconf Invocation}.
-@example
-expr "$ac_feature" : '.*[^-a-zA-Z0-9_]' >/dev/null &&
- @var{action}
-@end example
+@node Dependencies Between Macros, Obsoleting Macros, Reporting Messages, Writing Macros
+@section Dependencies Between Macros
-@noindent
-or better yet
+Some Autoconf macros depend on other macros having been called first in
+order to work correctly. Autoconf provides a way to ensure that certain
+macros are called if needed and a way to warn the user if macros are
+called in an order that might cause incorrect operation.
-@example
-expr "x$ac_feature" : '.*[^-a-zA-Z0-9_]' >/dev/null &&
- @var{action}
-@end example
+@menu
+* Prerequisite Macros:: Ensuring required information
+* Suggested Ordering:: Warning about possible ordering problems
+@end menu
-@samp{expr "X@var{foo}" : "X@var{bar}"} is more robust than @samp{echo
-"X@var{foo}" | grep "^X@var{bar}"}, because it avoids problems when
-@samp{@var{foo}} contains backslashes.
+@node Prerequisite Macros, Suggested Ordering, Dependencies Between Macros, Dependencies Between Macros
+@subsection Prerequisite Macros
+A macro that you write might need to use values that have previously
+been computed by other macros. For example, @code{AC_DECL_YYTEXT}
+examines the output of @code{flex} or @code{lex}, so it depends on
+@code{AC_PROG_LEX} having been called first to set the shell variable
+@code{LEX}.
-@item @command{trap}
-@c -----------------
-@cindex @command{trap}
-It is safe to trap at least the signals 1, 2, 13 and 15. You can also
-trap 0, i.e., have the @command{trap} run when the script ends (either via an
-explicit @command{exit}, or the end of the script).
+Rather than forcing the user of the macros to keep track of the
+dependencies between them, you can use the @code{AC_REQUIRE} macro to do
+it automatically. @code{AC_REQUIRE} can ensure that a macro is only
+called if it is needed, and only called once.
-Although @sc{posix} is not absolutely clear on this point, it is widely
-admitted that when entering the trap @samp{$?} should be set to the exit
-status of the last command run before the trap. The ambiguity can be
-summarized as: ``when the trap is launched by an @command{exit}, what is
-the @emph{last} command run: that before @command{exit}, or
-@command{exit} itself?''
+@defmac AC_REQUIRE (@var{macro-name})
+@maindex REQUIRE
+If the M4 macro @var{macro-name} has not already been called, call it
+(without any arguments). Make sure to quote @var{macro-name} with
+square brackets. @var{macro-name} must have been defined using
+@code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate
+that it has been called.
-Bash considers @command{exit} to be the last command, while Zsh and
-Solaris 8 @command{sh} consider that when the trap is run it is
-@emph{still} in the @command{exit}, hence it is the previous exit status
-that the trap receives:
+@code{AC_REQUIRE} must be used inside an @code{AC_DEFUN}'d macro; it
+must not be called from the top level.
+@end defmac
+
+@code{AC_REQUIRE} is often misunderstood. It really implements
+dependencies between macros in the sense that if one macro depends upon
+another, the latter will be expanded @emph{before} the body of the
+former. In particular, @samp{AC_REQUIRE(FOO)} is not replaced with the
+body of @code{FOO}. For instance, this definition of macros:
@example
-$ cat trap.sh
-trap 'echo $?' 0
-(exit 42); exit 0
-$ zsh trap.sh
-42
-$ bash trap.sh
-0
-@end example
+@group
+AC_DEFUN([TRAVOLTA],
+[test "$body_temparature_in_celsius" -gt "38" &&
+ dance_floor=occupied])
+AC_DEFUN([NEWTON_JOHN],
+[test "$hair_style" = "curly" &&
+ dance_floor=occupied])
+@end group
-The portable solution is then simple: when you want to @samp{exit 42},
-run @samp{(exit 42); exit 42}, the first @command{exit} being used to
-set the exit status to 42 for Zsh, and the second to trigger the trap
-and pass 42 as exit status for Bash.
+@group
+AC_DEFUN([RESERVE_DANCE_FLOOR],
+[if date | grep '^Sat.*pm' >/dev/null 2>&1; then
+ AC_REQUIRE([TRAVOLTA])
+ AC_REQUIRE([NEWTON_JOHN])
+fi])
+@end group
+@end example
-The shell in FreeBSD 4.0 has the following bug: @samp{$?} is reset to 0
-by empty lines if the code is inside @command{trap}.
+@noindent
+with this @file{configure.ac}
@example
-$ trap 'false
-
-echo $?' 0
-$ exit
-0
+AC_INIT
+RESERVE_DANCE_FLOOR
+if test "$dance_floor" = occupied; then
+ AC_MSG_ERROR([cannot pick up here, let's move])
+fi
@end example
@noindent
-Fortunately, this bug only affects @command{trap}.
+will not leave you with a better chance to meet a kindred soul at
+other times than Saturday night since it expands into:
-@item @command{true}
-@c -----------------
-@cindex @command{true}
-@cindex @command{:}
-Don't worry: as far as we know @command{true} is portable.
-Nevertheless, it's not always a builtin (e.g., Bash 1.x), and the
-portable shell community tends to prefer using @command{:}. This has a
-funny side effect: when asked whether @command{false} is more portable
-than @command{true} Alexandre Oliva answered:
+@example
+@group
+test "$body_temperature_in_Celsius" -gt "38" &&
+ dance_floor=occupied
+test "$hair_style" = "curly" &&
+ dance_floor=occupied
+fi
+if date | grep '^Sat.*pm' >/dev/null 2>&1; then
-@quotation
-In a sense, yes, because if it doesn't exist, the shell will produce an
-exit status of failure, which is correct for @command{false}, but not
-for @command{true}.
-@end quotation
+fi
+@end group
+@end example
-@item @command{unset}
-@c ------------------
-@cindex @command{unset}
-You cannot assume the support of @command{unset}, nevertheless, because
-it is extremely useful to disable embarrassing variables such as
-@code{CDPATH} or @code{LANG}, you can test for its existence and use
-it @emph{provided} you give a neutralizing value when @command{unset} is
-not supported:
+This behavior was chosen on purpose: (i) it prevents messages in
+required macros from interrupting the messages in the requiring macros;
+(ii) it avoids bad surprises when shell conditionals are used, as in:
@example
-if (unset FOO) >/dev/null 2>&1; then
- unset=unset
-else
- unset=false
+@group
+if @dots{}; then
+ AC_REQUIRE([SOME_CHECK])
fi
-$unset CDPATH || CDPATH=:
+@dots{}
+SOME_CHECK
+@end group
@end example
-@xref{Special Shell Variables}, for some neutralizing values. Also, see
-@ref{Limitations of Builtins}, documentation of @command{export}, for
-the case of environment variables.
-@end table
-@node Limitations of Usual Tools, Limitations of Make, Limitations of Builtins, Portable Shell
-@section Limitations of Usual Tools
+You are encouraged to put all @code{AC_REQUIRE}s at the beginning of a
+macro. You can use @code{dnl} to avoid the empty lines they leave.
-The small set of tools you can expect to find on any machine can still
-include some limitations you should be aware of.
+@node Suggested Ordering, , Prerequisite Macros, Dependencies Between Macros
+@subsection Suggested Ordering
-@table @asis
-@item @command{awk}
-@c ----------------
-@cindex @command{awk}
-Don't leave white spaces before the parentheses in user functions calls,
-@sc{gnu} awk will reject it:
+Some macros should be run before another macro if both are called, but
+neither @emph{requires} that the other be called. For example, a macro
+that changes the behavior of the C compiler should be called before any
+macros that run the C compiler. Many of these dependencies are noted in
+the documentation.
-@example
-$ gawk 'function die () @{ print "Aaaaarg!" @}
- BEGIN @{ die () @}'
-gawk: cmd. line:2: BEGIN @{ die () @}
-gawk: cmd. line:2: ^ parse error
-$ gawk 'function die () @{ print "Aaaaarg!" @}
- BEGIN @{ die() @}'
-Aaaaarg!
-@end example
+Autoconf provides the @code{AC_BEFORE} macro to warn users when macros
+with this kind of dependency appear out of order in a
+@file{configure.ac} file. The warning occurs when creating
+@code{configure} from @file{configure.ac}, not when running
+@code{configure}.
-If you want your program to be deterministic, don't depend on @code{for}
-on arrays:
+For example, @code{AC_PROG_CPP} checks whether the C compiler
+can run the C preprocessor when given the @option{-E} option. It should
+therefore be called after any macros that change which C compiler is
+being used, such as @code{AC_PROG_CC}. So @code{AC_PROG_CC} contains:
@example
-$ cat for.awk
-END @{
- arr["foo"] = 1
- arr["bar"] = 1
- for (i in arr)
- print i
-@}
-$ gawk -f for.awk </dev/null
-foo
-bar
-$ nawk -f for.awk </dev/null
-bar
-foo
+AC_BEFORE([$0], [AC_PROG_CPP])dnl
@end example
+@noindent
+This warns the user if a call to @code{AC_PROG_CPP} has already occurred
+when @code{AC_PROG_CC} is called.
-@item @command{cat}
-@c ----------------
-@cindex @command{cat}
-Don't rely on any option. The option @option{-v}, which displays
-non-printing characters, @emph{seems} portable, though.
+@defmac AC_BEFORE (@var{this-macro-name}, @var{called-macro-name})
+@maindex BEFORE
+Make @code{m4} print a warning message to the standard error output if
+@var{called-macro-name} has already been called. @var{this-macro-name}
+should be the name of the macro that is calling @code{AC_BEFORE}. The
+macro @var{called-macro-name} must have been defined using
+@code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate
+that it has been called.
+@end defmac
+@node Obsoleting Macros, Coding Style, Dependencies Between Macros, Writing Macros
+@section Obsoleting Macros
-@item @command{cmp}
-@c ----------------
-@cindex @command{cmp}
-@command{cmp} performs a raw data comparison of two files, while
-@command{diff} compares two text files. Therefore, if you might compare
-DOS files, even if only checking whether two files are different, use
-@command{diff} to avoid spurious differences due to differences of
-newline encoding.
+Configuration and portability technology has evolved over the years.
+Often better ways of solving a particular problem are developed, or
+ad-hoc approaches are systematized. This process has occurred in many
+parts of Autoconf. One result is that some of the macros are now
+considered @dfn{obsolete}; they still work, but are no longer considered
+the best thing to do, hence they should be replaced with more modern
+macros. Ideally, @code{autoupdate} should substitute the old macro calls
+with their modern implementation.
+Autoconf provides a simple means to obsolete a macro.
-@item @command{cp}
-@c ---------------
-@cindex @command{cp}
-@c This is thanks to Ian.
-SunOS @command{cp} does not support @option{-f}, although its
-@command{mv} does. It's possible to deduce why @command{mv} and
-@command{cp} are different with respect to @option{-f}. @command{mv}
-prompts by default before overwriting a read-only file. @command{cp}
-does not. Therefore, @command{mv} requires a @option{-f} option, but
-@command{cp} does not. @command{mv} and @command{cp} behave differently
-with respect to read-only files because the simplest form of
-@command{cp} cannot overwrite a read-only file, but the simplest form of
-@command{mv} can. This is because @command{cp} opens the target for
-write access, whereas @command{mv} simply calls @code{link} (or, in
-newer systems, @code{rename}).
-@c Ian said: ``I don't think -p or -r are portable''!!! How can you live
-@c without -r???
+@defmac AU_DEFUN (@var{old-macro}, @var{implementation}, @ovar{message})
+@maindex DEFUN
+@maindex AU_DEFUN
+Define @var{old-macro} as @var{implementation}. The only difference
+with @code{AC_DEFUN} is that the user will be warned that
+@var{old-macro} is now obsolete.
+If she then uses @code{autoupdate}, the call to @var{old-macro} will be
+replaced by the modern @var{implementation}. The additional
+@var{message} is then printed.
+@end defmac
-@item @command{diff}
-@c -----------------
-@cindex @command{diff}
-Option @option{-u} is nonportable.
+@node Coding Style, , Obsoleting Macros, Writing Macros
+@section Coding Style
-Some implementations, such as Tru64's, fail when comparing to
-@file{/dev/null}. Use an empty file instead.
+The Autoconf macros follow a strict coding style. You are encouraged to
+follow this style, especially if you intend to distribute your macro,
+either by contributing it to Autoconf itself, or via other means.
-@item @command{dirname}
-@c --------------------
-@cindex @command{dirname}
-Not all hosts have @command{dirname}, but it is reasonably easy to
-emulate, e.g.:
+The first requirement is to pay great attention to the quotation, for
+more details, see @ref{Autoconf Language}, and @ref{Quoting}.
+
+Do not try to invent new interfaces. It is likely that there is a macro
+in Autoconf that resembles the macro you are defining: try to stick to
+this existing interface (order of arguments, default values, etc.). We
+@emph{are} conscious that some of these interfaces are not perfect;
+nevertheless, when harmless, homogeneity should be preferred over
+creativity.
+
+Be careful about clashes both between M4 symbols and between shell
+variables.
+
+If you stick to the suggested M4 naming scheme (@pxref{Macro Names}),
+you are unlikely to generate conflicts. Nevertheless, when you need to
+set a special value, @emph{avoid using a regular macro name}; rather,
+use an ``impossible'' name. For instance, up to version 2.13, the macro
+@code{AC_SUBST} used to remember what @var{symbol}s were already defined
+by setting @code{AC_SUBST_@var{symbol}}, which is a regular macro name.
+But since there is a macro named @code{AC_SUBST_FILE}, it was just
+impossible to @samp{AC_SUBST(FILE)}! In this case,
+@code{AC_SUBST(@var{symbol})} or @code{_AC_SUBST(@var{symbol})} should
+have been used (yes, with the parentheses)@dots{}or better yet, high-level
+macros such as @code{AC_EXPAND_ONCE}.
+
+No Autoconf macro should ever enter the user-variable name space; i.e.,
+except for the variables that are the actual result of running the
+macro, all shell variables should start with @code{ac_}. In
+addition, small macros or any macro that is likely to be embedded in
+other macros should be careful not to use obvious names.
+
+@cindex @code{dnl}
+Do not use @code{dnl} to introduce comments: most of the comments you
+are likely to write are either header comments which are not output
+anyway, or comments that should make their way into @file{configure}.
+There are exceptional cases where you do want to comment special M4
+constructs, in which case @code{dnl} is right, but keep in mind that it
+is unlikely.
+
+M4 ignores the leading spaces before each argument, use this feature to
+indent in such a way that arguments are (more or less) aligned with the
+opening parenthesis of the macro being called. For instance, instead of
@example
-dir=`expr "x$file" : 'x\(.*\)/[^/]*' \|
- '.' : '.'
+AC_CACHE_CHECK(for EMX OS/2 environment,
+ac_cv_emxos2,
+[AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, [return __EMX__;])],
+[ac_cv_emxos2=yes], [ac_cv_emxos2=no])])
@end example
@noindent
-But there are a few subtilities, e.g., under UN*X, should @samp{//1}
-give @samp{/}? Paul Eggert answers:
+write
-@quotation
-No, under some older flavors of Unix, leading @samp{//} is a special
-path name: it refers to a ``super-root'' and is used to access other
-machines' files. Leading @samp{///}, @samp{////}, etc. are equivalent
-to @samp{/}; but leading @samp{//} is special. I think this tradition
-started with Apollo Domain/OS, an OS that is still in use on some older
-hosts.
+@example
+AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2],
+[AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])],
+ [ac_cv_emxos2=yes],
+ [ac_cv_emxos2=no])])
+@end example
-POSIX.2 allows but does not require the special treatment for @samp{//}.
-It says that the behavior of dirname on path names of the form
-@samp{//([^/]+/*)?} is implementation defined. In these cases, GNU
-@command{dirname} returns @samp{/}, but it's more portable to return
-@samp{//} as this works even on those older flavors of Unix.
+@noindent
+or even
-I have heard rumors that this special treatment of @samp{//} may be
-dropped in future versions of POSIX, but for now it's still the
-standard.
-@end quotation
+@example
+AC_CACHE_CHECK([for EMX OS/2 environment],
+ [ac_cv_emxos2],
+ [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([],
+ [return __EMX__;])],
+ [ac_cv_emxos2=yes],
+ [ac_cv_emxos2=no])])
+@end example
+When using @code{AC_TRY_RUN} or any macro that cannot work when
+cross-compiling, provide a pessimistic value (typically @samp{no}).
-@item @command{egrep}
-@c ------------------
-@cindex @command{egrep}
-The empty alternative is not portable, use @samp{?} instead. For
-instance with Digital Unix v5.0:
+Feel free to use various tricks to prevent auxiliary tools, such as
+syntax-highlighting editors, from behaving improperly. For instance,
+instead of:
@example
-> printf "foo\n|foo\n" | egrep '^(|foo|bar)$'
-|foo
-> printf "bar\nbar|\n" | egrep '^(foo|bar|)$'
-bar|
-> printf "foo\nfoo|\n|bar\nbar\n" | egrep '^(foo||bar)$'
-foo
-|bar
+patsubst([$1], [$"])
@end example
-@command{egrep} also suffers the limitations of @command{grep}.
+@noindent
+use
+@example
+patsubst([$1], [$""])
+@end example
-@item @command{expr}
-@c -----------------
-@cindex @command{expr}
-No @command{expr} keyword starts with @samp{x}, so use @samp{expr
-x"@var{word}" : 'x@var{regex}'} to keep @command{expr} from
-misinterpreting @var{word}.
+@noindent
+so that Emacsen do not open a endless ``string'' at the first quote.
+For the same reasons, avoid:
-Don't use @code{length}, @code{substr}, @code{match} and @code{index}.
+@example
+test $[#] != 0
+@end example
-@item @command{expr} (@samp{|})
-@cindex @command{expr} (@samp{|})
-You can use @samp{|}. Although @sc{posix} does require that @samp{expr
-''} return the empty string, it does not specify the result when you
-@samp{|} together the empty string (or zero) with the empty string. For
-example:
+@noindent
+and use:
@example
-expr '' \| ''
+test $[@@%:@@] != 0
@end example
-@sc{gnu}/Linux and @sc{posix.2-1992} return the empty string for this
-case, but traditional Unix returns @samp{0} (Solaris is one such
-example). In the latest @sc{posix} draft, the specification has been
-changed to match traditional Unix's behavior (which is bizarre, but it's
-too late to fix this). Please note that the same problem does arise
-when the empty string results from a computation, as in:
+@noindent
+Otherwise, the closing bracket would be hidden inside a @samp{#}-comment,
+breaking the bracket-matching highlighting from Emacsen. Note the
+preferred style to escape from M4: @samp{$[1]}, @samp{$[@@]}, etc. Do
+not escape when it is unneeded. Common examples of useless quotation
+are @samp{[$]$1} (write @samp{$$1}), @samp{[$]var} (use @samp{$var}),
+etc. If you add portability issues to the picture, you'll prefer
+@samp{$@{1+"$[@@]"@}} to @samp{"[$]@@"}, and you'll prefer do something
+better than hacking Autoconf @code{:-)}.
+
+When using @command{sed}, don't use @option{-e} except for indenting
+purpose. With the @code{s} command, the preferred separator is @samp{/}
+unless @samp{/} itself is used in the command, in which case you should
+use @samp{,}.
+
+@xref{Macro Definitions}, for details on how to define a macro. If a
+macro doesn't use @code{AC_REQUIRE} and it is expected to never be the
+object of an @code{AC_REQUIRE} directive, then use @code{define}. In
+case of doubt, use @code{AC_DEFUN}. All the @code{AC_REQUIRE}
+statements should be at the beginning of the macro, @code{dnl}'ed.
+
+You should not rely on the number of arguments: instead of checking
+whether an argument is missing, test that it is not empty. It provides
+both a simpler and a more predictable interface to the user, and saves
+room for further arguments.
+
+Unless the macro is short, try to leave the closing @samp{])} at the
+beginning of a line, followed by a comment that repeats the name of the
+macro being defined. This introduces an additional newline in
+@code{configure}; normally, that is not a problem, but if you want to
+remove it you can use @samp{[]dnl} on the last line. You can similarly
+use @samp{[]dnl} after a macro call to remove its newline. @samp{[]dnl}
+is recommended instead of @samp{dnl} to ensure that M4 does not
+interpret the @samp{dnl} as being attached to the preceding text or
+macro output. For example, instead of:
@example
-expr bar : foo \| foo : bar
+AC_DEFUN([AC_PATH_X],
+[AC_MSG_CHECKING([for X])
+AC_REQUIRE_CPP()
+@r{# @dots{}omitted@dots{}}
+ AC_MSG_RESULT([libraries $x_libraries, headers $x_includes])
+fi])
@end example
@noindent
-Avoid this portability problem by avoiding the empty string.
-
+you would write:
-@item @command{expr} (@samp{:})
-@c ----------------------------
-@cindex @command{expr}
-Don't use @samp{\?}, @samp{\+} and @samp{\|} in patterns, they are
-not supported on Solaris.
+@example
+AC_DEFUN([AC_PATH_X],
+[AC_REQUIRE_CPP()[]dnl
+AC_MSG_CHECKING([for X])
+@r{# @dots{}omitted@dots{}}
+ AC_MSG_RESULT([libraries $x_libraries, headers $x_includes])
+fi[]dnl
+])# AC_PATH_X
+@end example
-The @sc{posix.2-1992} standard is ambiguous as to whether @samp{expr a :
-b} (and @samp{expr 'a' : '\(b\)'}) output @samp{0} or the empty string.
-In practice, it outputs the empty string on most platforms, but portable
-scripts should not assume this. For instance, the @sc{qnx} 4.25 native
-@command{expr} returns @samp{0}.
+If the macro is long, try to split it into logical chunks. Typically,
+macros that check for a bug in a function and prepare its
+@code{AC_LIBOBJ} replacement should have an auxiliary macro to perform
+this setup. Do not hesitate to introduce auxiliary macros to factor
+your code.
-You may believe that one means to get a uniform behavior would be to use
-the empty string as a default value:
+In order to highlight the recommended coding style, here is a macro
+written the old way:
@example
-expr a : b \| ''
+dnl Check for EMX on OS/2.
+dnl _AC_EMXOS2
+AC_DEFUN(_AC_EMXOS2,
+[AC_CACHE_CHECK(for EMX OS/2 environment, ac_cv_emxos2,
+[AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, return __EMX__;)],
+ac_cv_emxos2=yes, ac_cv_emxos2=no)])
+test "$ac_cv_emxos2" = yes && EMXOS2=yes])
@end example
@noindent
-unfortunately this behaves exactly as the original expression, see the
-@samp{@command{expr} (@samp{:})} entry for more information.
+and the new way:
-Older @command{expr} implementations (e.g. SunOS 4 @command{expr} and
-Solaris 8 @command{/usr/ucb/expr}) have a silly length limit that causes
-@command{expr} to fail if the matched substring is longer than 120
-bytes. In this case, you might want to fall back on @samp{echo|sed} if
-@command{expr} fails.
+@example
+# _AC_EMXOS2
+# ----------
+# Check for EMX on OS/2.
+define([_AC_EMXOS2],
+[AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2],
+[AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])],
+ [ac_cv_emxos2=yes],
+ [ac_cv_emxos2=no])])
+test "$ac_cv_emxos2" = yes && EMXOS2=yes[]dnl
+])# _AC_EMXOS2
+@end example
-Don't leave, there is some more!
-The @sc{qnx} 4.25 @command{expr}, in addition of preferring @samp{0} to
-the empty string, has a funny behavior in its exit status: it's always 1
-when parentheses are used!
-@example
-$ val=`expr 'a' : 'a'`; echo "$?: $val"
-0: 1
-$ val=`expr 'a' : 'b'`; echo "$?: $val"
-1: 0
-$ val=`expr 'a' : '\(a\)'`; echo "?: $val"
-1: a
-$ val=`expr 'a' : '\(b\)'`; echo "?: $val"
-1: 0
-@end example
+@c ============================================= Portable Shell Programming
-@noindent
-In practice this can be a big problem if you are ready to catch failures
-of @command{expr} programs with some other method (such as using
-@command{sed}), since you may get twice the result. For instance
+@node Portable Shell, Manual Configuration, Writing Macros, Top
+@chapter Portable Shell Programming
+
+When writing your own checks, there are some shell-script programming
+techniques you should avoid in order to make your code portable. The
+Bourne shell and upward-compatible shells like the Korn shell and Bash
+have evolved over the years, but to prevent trouble, do not take
+advantage of features that were added after @sc{unix} version 7, circa
+1977. You should not use shell functions, aliases, negated character
+classes, or other features that are not found in all Bourne-compatible
+shells; restrict yourself to the lowest common denominator. Even
+@code{unset} is not supported by all shells! Also, include a space
+after the exclamation point in interpreter specifications, like this:
@example
-$ expr 'a' : '\(a\)' || echo 'a' | sed 's/^\(a\)$/\1/'
+#! /usr/bin/perl
@end example
@noindent
-will output @samp{a} on most hosts, but @samp{aa} on @sc{qnx} 4.25. A
-simple work around consists in testing @command{expr} and use a variable
-set to @command{expr} or to @command{false} according to the result.
-
-
-@item @command{find}
-@c -----------------
-The option @option{-maxdepth} seems to be GNU specific. Tru64 v5.1,
-NetBSD 1.5 and Solaris 2.5 @command{find} commands do not understand it.
-
+If you omit the space before the path, then 4.2@sc{bsd} based systems
+(such as Sequent DYNIX) will ignore the line, because they interpret
+@samp{#! /} as a 4-byte magic number.
-@item @command{grep}
-@c -----------------
-@cindex @command{grep}
-Don't use @samp{grep -s} to suppress output, because @samp{grep -s} on
-System V does not suppress output, only error messages. Instead,
-redirect the standard output and standard error (in case the file
-doesn't exist) of @code{grep} to @file{/dev/null}. Check the exit
-status of @code{grep} to determine whether it found a match.
+The set of external programs you should run in a @code{configure} script
+is fairly small. @xref{Utilities in Makefiles,, Utilities in
+Makefiles, standards, GNU Coding Standards}, for the list. This
+restriction allows users to start out with a fairly small set of
+programs and build the rest, avoiding too many interdependencies between
+packages.
-Don't use multiple regexps with @option{-e}, as some @code{grep} will only
-honor the last pattern (eg., IRIX 6.5 and Solaris 2.5.1). Anyway,
-Stardent Vistra SVR4 @code{grep} lacks @option{-e}@dots{} Instead, use
-alternation and @code{egrep}.
+Some of these external utilities have a portable subset of features; see
+@ref{Limitations of Usual Tools}.
+@menu
+* Shellology:: A zoology of shells
+* Here-Documents:: Quirks and tricks
+* File Descriptors:: FDs and redirections
+* File System Conventions:: File- and pathnames
+* Shell Substitutions:: Variable and command expansions
+* Assignments:: Varying side effects of assignments
+* Special Shell Variables:: Variables you should not change
+* Limitations of Builtins:: Portable use of not so portable /bin/sh
+* Limitations of Usual Tools:: Portable use of portable tools
+* Limitations of Make:: Portable Makefiles
+@end menu
-@item @command{ln}
-@c ---------------
-@cindex @command{ln}
-@cindex Symbolic links
-Don't rely on @command{ln} having a @option{-f} option. Symbolic links
-are not available on old systems, use @samp{ln} as a fall back.
+@node Shellology, Here-Documents, Portable Shell, Portable Shell
+@section Shellology
-For versions of the DJGPP before 2.04, @command{ln} emulates soft links
-for executables by generating a stub that in turn calls the real
-program. This feature also works with nonexistent files like in the
-Unix spec. So @samp{ln -s file link} will generate @file{link.exe},
-which will attempt to call @file{file.exe} if run. But this feature only
-works for executables, so @samp{cp -p} is used instead for these
-systems. DJGPP versions 2.04 and later have full symlink support.
+There are several families of shells, most prominently the Bourne
+family and the C shell family which are deeply incompatible. If you
+want to write portable shell scripts, avoid members of the C shell
+family.
+Below we describe some of the members of the Bourne shell family.
-@item @command{mv}
-@c ---------------
-@cindex @command{mv}
-The only portable options are @option{-f} and @option{-i}.
+@table @asis
+@item Ash
+@cindex Ash
+@command{ash} is often used on @sc{gnu}/Linux and @sc{bsd} systems as a
+light-weight Bourne-compatible shell. Ash 0.2 has some bugs that are
+fixed in the 0.3.x series, but portable shell scripts should workaround
+them, since version 0.2 is still shipped with many @sc{gnu}/Linux
+distributions.
-Moving individual files between file systems is portable (it was in V6),
-but it is not always atomic: when doing @samp{mv new existing}, there's
-a critical section where neither the old nor the new version of
-@file{existing} actually exists.
+To be compatible with Ash 0.2:
-Moving directories across mount points is not portable, use @command{cp}
-and @command{rm}.
+@itemize @minus
+@item
+don't use @samp{$?} after expanding empty or unset variables:
+@example
+foo=
+false
+$foo
+echo "Don't use it: $?"
+@end example
-@item @command{sed}
-@c ----------------
-@cindex @command{sed}
-Patterns should not include the separator (unless escaped), even as part
-of a character class. In conformance with @sc{posix}, the Cray
-@command{sed} will reject @samp{s/[^/]*$//}: use @samp{s,[^/]*$,,}.
+@item
+don't use command substitution within variable expansion:
-Sed scripts should not use branch labels longer than 8 characters and
-should not contain comments.
+@example
+cat $@{FOO=`bar`@}
+@end example
-Input should have reasonably long lines, since some @command{sed} have
-an input buffer limited to 4000 bytes.
+@item
+beware that single builtin substitutions are not performed by a sub
+shell, hence their effect applies to the current shell! @xref{Shell
+Substitutions}, item ``Command Substitution''.
+@end itemize
-Alternation, @samp{\|}, is common but not portable.
-@c FIXME: I know Solaris is guilty, but I don't remember how.
-Anchors (@samp{^} and @samp{$}) inside groups are not portable.
+@item Bash
+@cindex Bash
+To detect whether you are running @command{bash}, test if
+@code{BASH_VERSION} is set. To disable its extensions and require
+@sc{posix} compatibility, run @samp{set -o posix}. @xref{Bash POSIX
+Mode,, Bash @sc{posix} Mode, bash, The GNU Bash Reference Manual}, for
+details.
-Nested groups are extremely portable, but there is at least one
-@command{sed} (System V/68 Base Operating System R3V7.1) that does not
-support it.
+@item @command{/usr/xpg4/bin/sh} on Solaris
+@cindex @command{/usr/xpg4/bin/sh} on Solaris
+The @sc{posix}-compliant Bourne shell on a Solaris system is
+@command{/usr/xpg4/bin/sh} and is part of an extra optional package.
+There is no extra charge for this package, but it is also not part of a
+minimal OS install and therefore some folks may not have it.
-Of course the option @option{-e} is portable, but it is not needed. No
-valid Sed program can start with a dash, so it does not help
-disambiguating. Its sole usefulness is helping enforcing indenting as
-in:
+@item Zsh
+@cindex Zsh
+To detect whether you are running @command{zsh}, test if
+@code{ZSH_VERSION} is set. By default @command{zsh} is @emph{not}
+compatible with the Bourne shell: you have to run @samp{emulate sh} and
+set @code{NULLCMD} to @samp{:}. @xref{Compatibility,, Compatibility,
+zsh, The Z Shell Manual}, for details.
-@example
-sed -e @var{instruction-1} \
- -e @var{instruction-2}
-@end example
+Zsh 3.0.8 is the native @command{/bin/sh} on Mac OS X 10.0.3.
+@end table
-@noindent
-as opposed to
+The following discussion between Russ Allbery and Robert Lipe is worth
+reading:
-@example
-sed @var{instruction-1};@var{instruction-2}
-@end example
+@noindent
+Russ Allbery:
-Contrary to yet another urban legend, you may portably use @samp{&} in
-the replacement part of the @code{s} command to mean ``what was
-matched''.
+@quotation
+The @sc{gnu} assumption that @command{/bin/sh} is the one and only shell
+leads to a permanent deadlock. Vendors don't want to break user's
+existant shell scripts, and there are some corner cases in the Bourne
+shell that are not completely compatible with a @sc{posix} shell. Thus,
+vendors who have taken this route will @emph{never} (OK@dots{}``never say
+never'') replace the Bourne shell (as @command{/bin/sh}) with a
+@sc{posix} shell.
+@end quotation
+@noindent
+Robert Lipe:
-@item @command{sed} (@samp{t})
-@c ---------------------------
-@cindex @command{sed} (@samp{t})
-Some old systems have @command{sed} that ``forget'' to reset their
-@samp{t} flag when starting a new cycle. For instance on @sc{mips
-risc/os}, and on @sc{irix} 5.3, if you run the following @command{sed}
-script (the line numbers are not actual part of the texts):
+@quotation
+This is exactly the problem. While most (at least most System V's) do
+have a bourne shell that accepts shell functions most vendor
+@command{/bin/sh} programs are not the @sc{posix} shell.
-@example
-s/keep me/kept/g # a
-t end # b
-s/.*/deleted/g # c
-: end # d
-@end example
+So while most modern systems do have a shell _somewhere_ that meets the
+@sc{posix} standard, the challenge is to find it.
+@end quotation
-@noindent
-on
+@node Here-Documents, File Descriptors, Shellology, Portable Shell
+@section Here-Documents
-@example
-delete me # 1
-delete me # 2
-keep me # 3
-delete me # 4
-@end example
+Don't rely on @samp{\} being preserved just because it has no special
+meaning together with the next symbol. in the native @command{/bin/sh}
+on OpenBSD 2.7 @samp{\"} expands to @samp{"} in here-documents with
+unquoted delimiter. As a general rule, if @samp{\\} expands to @samp{\}
+use @samp{\\} to get @samp{\}.
-@noindent
-you get
+With OpenBSD 2.7's @command{/bin/sh}
@example
-deleted
-delete me
-kept
-deleted
+@group
+$ cat <<EOF
+> \" \\
+> EOF
+" \
+@end group
@end example
@noindent
-instead of
+and with Bash:
@example
-deleted
-deleted
-kept
-deleted
+@group
+bash-2.04$ cat <<EOF
+> \" \\
+> EOF
+\" \
+@end group
@end example
-Why? When processing 1, a matches, therefore sets the t flag, b jumps to
-d, and the output is produced. When processing line 2, the t flag is
-still set (this is the bug). Line a fails to match, but @command{sed}
-is not supposed to clear the t flag when a substitution fails. Line b
-sees that the flag is set, therefore it clears it, and jumps to d, hence
-you get @samp{delete me} instead of @samp{deleted}. When processing 3 t
-is clear, a matches, so the flag is set, hence b clears the flags and
-jumps. Finally, since the flag is clear, 4 is processed properly.
-
-There are two things one should remind about @samp{t} in @command{sed}.
-Firstly, always remember that @samp{t} jumps if @emph{some} substitution
-succeeded, not only the immediately preceding substitution, therefore,
-always use a fake @samp{t clear; : clear} to reset the t flag where
-indeed.
-Secondly, you cannot rely on @command{sed} to clear the flag at each new
-cycle.
+Many older shells (including the Bourne shell) implement here-documents
+inefficiently. Users can generally speed things up by using a faster
+shell, e.g., by using the command @samp{bash ./configure} rather than
+plain @samp{./configure}.
-One portable implementation of the script above is:
+Some shells can be extremely inefficient when there are a lot of
+here-documents inside a single statement. For instance if your
+@file{configure.ac} includes something like:
@example
-t clear
-: clear
-s/keep me/kept/g
-t end
-s/.*/deleted/g
-: end
+@group
+if <cross_compiling>; then
+ assume this and that
+else
+ check this
+ check that
+ check something else
+ @dots{}
+ on and on forever
+ @dots{}
+fi
+@end group
@end example
-@item @command{touch}
-@c ------------------
-@cindex @command{touch}
-On some old @sc{bsd} systems, @command{touch} or any command that
-results in an empty file does not update the timestamps, so use a
-command like @code{echo} as a workaround.
-
-GNU @command{touch} 3.16r (and presumably all before that) fails to work
-on SunOS 4.1.3 when the empty file is on an @sc{nfs}-mounted 4.2 volume.
-
-@end table
+A shell parses the whole @code{if}/@code{fi} construct, creating
+temporary files for each here document in it. Some shells create links
+for such here-documents on every @code{fork}, so that the clean-up code
+they had installed correctly removes them. It is creating the links
+that the shell can take forever.
+Moving the tests out of the @code{if}/@code{fi}, or creating multiple
+@code{if}/@code{fi} constructs, would improve the performance
+significantly. Anyway, this kind of construct is not exactly the
+typical use of Autoconf. In fact, it's even not recommended, because M4
+macros can't look into shell conditionals, so we may fail to expand a
+macro when it was expanded before in a conditional path, and the
+condition turned out to be false at run-time, and we end up not
+executing the macro at all.
-@node Limitations of Make, , Limitations of Usual Tools, Portable Shell
-@section Limitations of Make
+@node File Descriptors, File System Conventions, Here-Documents, Portable Shell
+@section File Descriptors
-Make itself suffers a great number of limitations, only a few of which
-being listed here. First of all, remember that since commands are
-executed by the shell, all its weaknesses are inherited@dots{}
+Some file descriptors shall not be used, since some systems, admittedly
+arcane, use them for special purpose:
@table @asis
-@item @code{VPATH}
-@cindex @code{VPATH}
-Don't use it! For instance any assignment to @code{VPATH} causes Sun
-@command{make} to only execute the first set of double-colon rules.
-@end table
-
-
-
-
-@c ====================================================== Results of Tests.
-
-@node Results, Writing Macros, Portable Shell, Top
-@chapter Results of Tests
-
-Once @code{configure} has determined whether a feature exists, what can
-it do to record that information? There are four sorts of things it can
-do: define a C preprocessor symbol, set a variable in the output files,
-save the result in a cache file for future @code{configure} runs, and
-print a message letting the user know the result of the test.
-
-@menu
-* Defining Symbols:: Defining C preprocessor symbols
-* Setting Output Variables:: Replacing variables in output files
-* Caching Results:: Speeding up subsequent @code{configure} runs
-* Printing Messages:: Notifying @code{configure} users
-@end menu
-
-@node Defining Symbols, Setting Output Variables, Results, Results
-@section Defining C Preprocessor Symbols
+@item 3
+some systems may open it to @samp{/dev/tty}.
-A common action to take in response to a feature test is to define a C
-preprocessor symbol indicating the results of the test. That is done by
-calling @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED}.
+@item 4
+used on the Kubota Titan.
+@end table
-By default, @code{AC_OUTPUT} places the symbols defined by these macros
-into the output variable @code{DEFS}, which contains an option
-@option{-D@var{symbol}=@var{value}} for each symbol defined. Unlike in
-Autoconf version 1, there is no variable @code{DEFS} defined while
-@code{configure} is running. To check whether Autoconf macros have
-already defined a certain C preprocessor symbol, test the value of the
-appropriate cache variable, as in this example:
+Don't redirect several times the same file descriptor, as you are doomed
+to failure under Ultrix.
@example
-AC_CHECK_FUNC(vprintf, [AC_DEFINE(HAVE_VPRINTF)])
-if test "$ac_cv_func_vprintf" != yes; then
- AC_CHECK_FUNC(_doprnt, [AC_DEFINE(HAVE_DOPRNT)])
-fi
+ULTRIX V4.4 (Rev. 69) System #31: Thu Aug 10 19:42:23 GMT 1995
+UWS V4.4 (Rev. 11)
+$ eval 'echo matter >fullness' >void
+illegal io
+$ eval '(echo matter >fullness)' >void
+illegal io
+$ (eval '(echo matter >fullness)') >void
+Ambiguous output redirect.
@end example
-If @code{AC_CONFIG_HEADERS} has been called, then instead of creating
-@code{DEFS}, @code{AC_OUTPUT} creates a header file by substituting the
-correct values into @code{#define} statements in a template file.
-@xref{Configuration Headers}, for more information about this kind of
-output.
+@noindent
+In each case the expected result is of course @file{fullness} containing
+@samp{matter} and @file{void} being empty.
-@defmac AC_DEFINE (@var{variable}, @ovar{value}, @ovar{description})
-@maindex DEFINE
-Define C preprocessor variable @var{variable}. If @var{value} is given,
-set @var{variable} to that value (verbatim), otherwise set it to 1.
-@var{value} should not contain literal newlines, and if you are not
-using @code{AC_CONFIG_HEADERS} it should not contain any @samp{#}
-characters, as @code{make} tends to eat them. To use a shell variable
-(which you need to do in order to define a value containing the M4 quote
-characters @samp{[} or @samp{]}), use @code{AC_DEFINE_UNQUOTED} instead.
-@var{description} is only useful if you are using
-@code{AC_CONFIG_HEADERS}. In this case, @var{description} is put into
-the generated @file{config.h.in} as the comment before the macro define.
-The following example defines the C preprocessor variable
-@code{EQUATION} to be the string constant @samp{"$a > $b"}:
+Don't try to redirect the standard error of a command substitution: it
+must be done @emph{inside} the command substitution: when running
+@samp{: `cd /zorglub` 2>/dev/null} expect the error message to
+escape, while @samp{: `cd /zorglub 2>/dev/null`} works properly.
+
+It is worth noting that Zsh (but not Ash nor Bash) makes it possible
+in assignments though: @samp{foo=`cd /zorglub` 2>/dev/null}.
+
+Most shells, if not all (including Bash, Zsh, Ash), output traces on
+stderr, even for sub-shells. This might result in undesired content
+if you meant to capture the standard-error output of the inner command:
@example
-AC_DEFINE(EQUATION, "$a > $b")
+$ ash -x -c '(eval "echo foo >&2") 2>stderr'
+$ cat stderr
++ eval echo foo >&2
++ echo foo
+foo
+$ bash -x -c '(eval "echo foo >&2") 2>stderr'
+$ cat stderr
++ eval 'echo foo >&2'
+++ echo foo
+foo
+$ zsh -x -c '(eval "echo foo >&2") 2>stderr'
+@i{# Traces on startup files deleted here.}
+$ cat stderr
++zsh:1> eval echo foo >&2
++zsh:1> echo foo
+foo
@end example
-@end defmac
-@defmac AC_DEFINE_UNQUOTED (@var{variable}, @ovar{value}, @ovar{description})
-@maindex DEFINE_UNQUOTED
-Like @code{AC_DEFINE}, but three shell expansions are
-performed---once---on @var{variable} and @var{value}: variable expansion
-(@samp{$}), command substitution (@samp{`}), and backslash escaping
-(@samp{\}). Single and double quote characters in the value have no
-special meaning. Use this macro instead of @code{AC_DEFINE} when
-@var{variable} or @var{value} is a shell variable. Examples:
+@noindent
+You'll appreciate the various levels of detail@dots{}
-@example
-AC_DEFINE_UNQUOTED(config_machfile, "$machfile")
-AC_DEFINE_UNQUOTED(GETGROUPS_T, $ac_cv_type_getgroups)
-AC_DEFINE_UNQUOTED($ac_tr_hdr)
-@end example
-@end defmac
+One workaround is to grep out uninteresting lines, hoping not to remove
+good ones@dots{}
-Due to the syntactical bizarreness of the Bourne shell, do not use
-semicolons to separate @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED}
-calls from other macro calls or shell code; that can cause syntax errors
-in the resulting @code{configure} script. Use either spaces or
-newlines. That is, do this:
+@node File System Conventions, Shell Substitutions, File Descriptors, Portable Shell
+@section File System Conventions
-@example
-AC_CHECK_HEADER(elf.h, [AC_DEFINE(SVR4) LIBS="$LIBS -lelf"])
-@end example
+While @command{autoconf} and friends will usually be run on some Unix
+variety, it can and will be used on other systems, most notably @sc{dos}
+variants. This impacts several assumptions regarding file and
+path names.
@noindent
-or this:
+For example, the following code:
@example
-AC_CHECK_HEADER(elf.h,
- [AC_DEFINE(SVR4)
- LIBS="$LIBS -lelf"])
+case $foo_dir in
+ /*) # Absolute
+ ;;
+ *)
+ foo_dir=$dots$foo_dir ;;
+esac
@end example
@noindent
-instead of this:
+will fail to properly detect absolute paths on those systems, because
+they can use a drivespec, and will usually use a backslash as directory
+separator. The canonical way to check for absolute paths is:
@example
-AC_CHECK_HEADER(elf.h, [AC_DEFINE(SVR4); LIBS="$LIBS -lelf"])
+case $foo_dir in
+ [\\/]* | ?:[\\/]* ) # Absolute
+ ;;
+ *)
+ foo_dir=$dots$foo_dir ;;
+esac
@end example
-@node Setting Output Variables, Caching Results, Defining Symbols, Results
-@section Setting Output Variables
+@noindent
+Make sure you quote the brackets if appropriate and keep the backslash as
+first character (@pxref{Limitations of Builtins}).
-Another way to record the results of tests is to set @dfn{output
-variables}, which are shell variables whose values are substituted into
-files that @code{configure} outputs. The two macros below create new
-output variables. @xref{Preset Output Variables}, for a list of output
-variables that are always available.
+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, use
+@code{$ac_path_separator} instead (or the @code{PATH_SEPARATOR} output
+variable). @command{autoconf} sets this to the appropriate value (@samp{:}
+or @samp{;}) when it starts up.
-@defmac AC_SUBST (@var{variable}, @ovar{value})
-@maindex SUBST
-Create an output variable from a shell variable. Make @code{AC_OUTPUT}
-substitute the variable @var{variable} into output files (typically one
-or more @file{Makefile}s). This means that @code{AC_OUTPUT} will
-replace instances of @samp{@@@var{variable}@@} in input files with the
-value that the shell variable @var{variable} has when @code{AC_OUTPUT}
-is called. This value of @var{variable} should not contain literal
-newlines.
+File names need extra care as well. While @sc{dos}-based environments
+that are Unixy enough to run @command{autoconf} (such as DJGPP) will
+usually be able to handle long file names properly, there are still
+limitations that can seriously break packages. Several of these issues
+can be easily detected by the
+@href{ftp://ftp.gnu.org/gnu/non-gnu/doschk/doschk-1.1.tar.gz, doschk}
+package.
-If @var{value} is given, in addition assign it to @samp{variable}.
-@end defmac
+A short overview follows; problems are marked with @sc{sfn}/@sc{lfn} to
+indicate where they apply: @sc{sfn} means the issues are only relevant to
+plain @sc{dos}, not to @sc{dos} boxes under Windows, while @sc{lfn}
+identifies problems that exist even under Windows.
-@defmac AC_SUBST_FILE (@var{variable})
-@maindex SUBST_FILE
-Another way to create an output variable from a shell variable. Make
-@code{AC_OUTPUT} insert (without substitutions) the contents of the file
-named by shell variable @var{variable} into output files. This means
-that @code{AC_OUTPUT} will replace instances of
-@samp{@@@var{variable}@@} in output files (such as @file{Makefile.in})
-with the contents of the file that the shell variable @var{variable}
-names when @code{AC_OUTPUT} is called. Set the variable to
-@file{/dev/null} for cases that do not have a file to insert.
+@table @asis
+@item No multiple dots (@sc{sfn})
+@sc{dos} cannot handle multiple dots in filenames. This is an especially
+important thing to remember when building a portable configure script,
+as @command{autoconf} uses a .in suffix for template files.
-This macro is useful for inserting @file{Makefile} fragments containing
-special dependencies or other @code{make} directives for particular host
-or target types into @file{Makefile}s. For example, @file{configure.ac}
-could contain:
+This is perfectly OK on Unices:
@example
-AC_SUBST_FILE(host_frag)
-host_frag=$srcdir/conf/sun4.mh
+AC_CONFIG_HEADER(config.h)
+AC_CONFIG_FILES([source.c foo.bar])
+AC_OUTPUT
@end example
@noindent
-and then a @file{Makefile.in} could contain:
+but it causes problems on @sc{dos}, as it requires @samp{config.h.in},
+@samp{source.c.in} and @samp{foo.bar.in}. To make your package more portable
+to @sc{dos}-based environments, you should use this instead:
@example
-@@host_frag@@
+AC_CONFIG_HEADER(config.h:config.hin)
+AC_CONFIG_FILES([source.c:source.cin foo.bar:foobar.in])
+AC_OUTPUT
@end example
-@end defmac
-@node Caching Results, Printing Messages, Setting Output Variables, Results
-@section Caching Results
-@cindex Cache
+@item No leading dot (@sc{sfn})
+@sc{dos} cannot handle filenames that start with a dot. This is usually
+not a very important issue for @command{autoconf}.
-To avoid checking for the same features repeatedly in various
-@code{configure} scripts (or in repeated runs of one script),
-@code{configure} can optionally save the results of many checks in a
-@dfn{cache file} (@pxref{Cache Files}). If a @code{configure} script
-runs with caching enabled and finds a cache file, it reads the results
-of previous runs from the cache and avoids rerunning those checks. As a
-result, @code{configure} can then run much faster than if it had to
-perform all of the checks every time.
+@item Case insensitivity (@sc{lfn})
+@sc{dos} is case insensitive, so you cannot, for example, have both a
+file called @samp{INSTALL} and a directory called @samp{install}. This
+also affects @command{make}; if there's a file called @samp{INSTALL} in
+the directory, @command{make install} will do nothing (unless the
+@samp{install} target is marked as PHONY).
-@defmac AC_CACHE_VAL (@var{cache-id}, @var{commands-to-set-it})
-@maindex CACHE_VAL
-Ensure that the results of the check identified by @var{cache-id} are
-available. If the results of the check were in the cache file that was
-read, and @code{configure} was not given the @option{--quiet} or
-@option{--silent} option, print a message saying that the result was
-cached; otherwise, run the shell commands @var{commands-to-set-it}. If
-the shell commands are run to determine the value, the value will be
-saved in the cache file just before @code{configure} creates its output
-files. @xref{Cache Variable Names}, for how to choose the name of the
-@var{cache-id} variable.
+@item The 8+3 limit (@sc{sfn})
+Because the @sc{dos} file system only stores the first 8 characters of
+the filename and the first 3 of the extension, those must be unique.
+That means that @file{foobar-part1.c}, @file{foobar-part2.c} and
+@file{foobar-prettybird.c} all resolve to the same filename
+(@file{FOOBAR-P.C}). The same goes for @file{foo.bar} and
+@file{foo.bartender}.
-The @var{commands-to-set-it} @emph{must have no side effects} except for
-setting the variable @var{cache-id}, see below.
-@end defmac
+Note: This is not usually a problem under Windows, as it uses numeric
+tails in the short version of filenames to make them unique. However, a
+registry setting can turn this behaviour off. While this makes it
+possible to share file trees containing long file names between @sc{sfn}
+and @sc{lfn} environments, it also means the above problem applies there
+as well.
-@defmac AC_CACHE_CHECK (@var{message}, @var{cache-id}, @var{commands-to-set-it})
-@maindex CACHE_CHECK
-A wrapper for @code{AC_CACHE_VAL} that takes care of printing the
-messages. This macro provides a convenient shorthand for the most
-common way to use these macros. It calls @code{AC_MSG_CHECKING} for
-@var{message}, then @code{AC_CACHE_VAL} with the @var{cache-id} and
-@var{commands} arguments, and @code{AC_MSG_RESULT} with @var{cache-id}.
+@item Invalid characters
+Some characters are invalid in @sc{dos} filenames, and should therefore
+be avoided. In a @sc{lfn} environment, these are @samp{/}, @samp{\},
+@samp{?}, @samp{*}, @samp{:}, @samp{<}, @samp{>}, @samp{|} and @samp{"}.
+In a @sc{sfn} environment, other characters are also invalid. These
+include @samp{+}, @samp{,}, @samp{[} and @samp{]}.
+@end table
-The @var{commands-to-set-it} @emph{must have no side effects} except for
-setting the variable @var{cache-id}, see below.
-@end defmac
+@node Shell Substitutions, Assignments, File System Conventions, Portable Shell
+@section Shell Substitutions
-It is very common to find buggy macros using @code{AC_CACHE_VAL} or
-@code{AC_CACHE_CHECK}, because people are tempted to call
-@code{AC_DEFINE} in the @var{commands-to-set-it}. Instead, the code that
-@emph{follows} the call to @code{AC_CACHE_VAL} should call
-@code{AC_DEFINE}, by examining the value of the cache variable. For
-instance, the following macro is broken:
+Contrary to a persistent urban legend, the Bourne shell does not
+systematically split variables and backquoted expressions, in particular
+on the right-hand side of assignments and in the argument of @code{case}.
+For instance, the following code:
+
+@example
+case "$given_srcdir" in
+.) top_srcdir="`echo "$dots" | sed 's,/$,,'`"
+*) top_srcdir="$dots$given_srcdir" ;;
+esac
+@end example
+
+@noindent
+is more readable when written as:
+
+@example
+case $given_srcdir in
+.) top_srcdir=`echo "$dots" | sed 's,/$,,'`
+*) top_srcdir=$dots$given_srcdir ;;
+esac
+@end example
+
+@noindent
+and in fact it is even @emph{more} portable: in the first case of the
+first attempt, the computation of @code{top_srcdir} is not portable,
+since not all shells properly understand @code{"`@dots{}"@dots{}"@dots{}`"}.
+Worse yet, not all shells understand @code{"`@dots{}\"@dots{}\"@dots{}`"}
+the same way. There is just no portable way to use double-quoted
+strings inside double-quoted backquoted expressions (pfew!).
+
+@table @code
+@item $@@
+@cindex @samp{"$@@"}
+One of the most famous shell-portability issues is related to
+@samp{"$@@"}: when there are no positional arguments, it is supposed to
+be equivalent to nothing. But some shells, for instance under Digital
+Unix 4.0 and 5.0, will then replace it with an empty argument. To be
+portable, use @samp{$@{1+"$@@"@}}.
+
+@item $@{@var{var}:-@var{value}@}
+@cindex $@{@var{var}:-@var{value}@}
+Old @sc{bsd} shells, including the Ultrix @code{sh}, don't accept the
+colon for any shell substitution, and complain and die.
+
+@item $@{@var{var}=@var{literal}@}
+@cindex $@{@var{var}=@var{literal}@}
+Be sure to quote:
@example
-@group
-AC_DEFUN([AC_SHELL_TRUE],
-[AC_CACHE_CHECK([whether true(1) works], [ac_cv_shell_true_works],
- [ac_cv_shell_true_works=no
- true && ac_cv_shell_true_works=yes
- if test $ac_cv_shell_true_works = yes; then
- AC_DEFINE([TRUE_WORKS], 1
- [Define if `true(1)' works properly.])
- fi])
-])
-@end group
+: $@{var='Some words'@}
@end example
@noindent
-This fails if the cache is enabled: the second time this macro is run,
-@code{TRUE_WORKS} @emph{will not be defined}. The proper implementation
-is:
+otherwise some shells, such as on Digital Unix V 5.0, will die because
+of a ``bad substitution''.
+
+Solaris' @command{/bin/sh} has a frightening bug in its interpretation
+of this. Imagine you need set a variable to a string containing
+@samp{@}}. This @samp{@}} character confuses Solaris' @command{/bin/sh}
+when the affected variable was already set. This bug can be exercised
+by running:
@example
-@group
-AC_DEFUN([AC_SHELL_TRUE],
-[AC_CACHE_CHECK([whether true(1) works], [ac_cv_shell_true_works],
- [ac_cv_shell_true_works=no
- true && ac_cv_shell_true_works=yes])
- if test $ac_cv_shell_true_works = yes; then
- AC_DEFINE([TRUE_WORKS], 1
- [Define if `true(1)' works properly.])
- fi
-])
-@end group
+$ unset foo
+$ foo=$@{foo='@}'@}
+$ echo $foo
+@}
+$ foo=$@{foo='@}' # no error; this hints to what the bug is
+$ echo $foo
+@}
+$ foo=$@{foo='@}'@}
+$ echo $foo
+@}@}
+ ^ ugh!
@end example
-Also, @var{commands-to-set-it} should not print any messages, for
-example with @code{AC_MSG_CHECKING}; do that before calling
-@code{AC_CACHE_VAL}, so the messages are printed regardless of whether
-the results of the check are retrieved from the cache or determined by
-running the shell commands.
+It seems that @samp{@}} is interpreted as matching @samp{$@{}, even
+though it is enclosed in single quotes. The problem doesn't happen
+using double quotes.
-@menu
-* Cache Variable Names:: Shell variables used in caches
-* Cache Files:: Files @code{configure} uses for caching
-* Cache Checkpointing:: Loading and saving the cache file
-@end menu
+@item $@{@var{var}=@var{expanded-value}@}
+@cindex $@{@var{var}=@var{expanded-value}@}
+On Ultrix,
+running
-@node Cache Variable Names, Cache Files, Caching Results, Caching Results
-@subsection Cache Variable Names
-@cindex Cache variable
+@example
+default="yu,yaa"
+: $@{var="$default"@}
+@end example
-The names of cache variables should have the following format:
+@noindent
+will set @var{var} to @samp{M-yM-uM-,M-yM-aM-a}, i.e., the 8th bit of
+each char will be set. You won't observe the phenomenon using a simple
+@samp{echo $var} since apparently the shell resets the 8th bit when it
+expands $var. Here are two means to make this shell confess its sins:
@example
-@var{package-prefix}_cv_@var{value-type}_@var{specific-value}_@ovar{additional-options}
+$ cat -v <<EOF
+$var
+EOF
@end example
@noindent
-for example, @samp{ac_cv_header_stat_broken} or
-@samp{ac_cv_prog_gcc_traditional}. The parts of the variable name are:
-
-@table @asis
-@item @var{package-prefix}
-An abbreviation for your package or organization; the same prefix you
-begin local Autoconf macros with, except lowercase by convention.
-For cache values used by the distributed Autoconf macros, this value is
-@samp{ac}.
+and
-@item @code{_cv_}
-Indicates that this shell variable is a cache value. This string
-@emph{must} be present in the variable name, including the leading
-underscore.
+@example
+$ set | grep '^var=' | cat -v
+@end example
-@item @var{value-type}
-A convention for classifying cache values, to produce a rational naming
-system. The values used in Autoconf are listed in @ref{Macro Names}.
+One classic incarnation of this bug is:
-@item @var{specific-value}
-Which member of the class of cache values this test applies to.
-For example, which function (@samp{alloca}), program (@samp{gcc}), or
-output variable (@samp{INSTALL}).
+@example
+default="a b c"
+: $@{list="$default"@}
+for c in $list; do
+ echo $c
+done
+@end example
-@item @var{additional-options}
-Any particular behavior of the specific member that this test applies to.
-For example, @samp{broken} or @samp{set}. This part of the name may
-be omitted if it does not apply.
-@end table
+@noindent
+You'll get @samp{a b c} on a single line. Why? Because there are no
+spaces in @samp{$list}: there are @samp{M- }, i.e., spaces with the 8th
+bit set, hence no IFS splitting is performed!!!
-The values assigned to cache variables may not contain newlines.
-Usually, their values will be boolean (@samp{yes} or @samp{no}) or the
-names of files or functions; so this is not an important restriction.
+One piece of good news is that Ultrix works fine with @samp{:
+$@{list=$default@}}; i.e., if you @emph{don't} quote. The bad news is
+then that @sc{qnx} 4.25 then sets @var{list} to the @emph{last} item of
+@var{default}!
-@node Cache Files, Cache Checkpointing, Cache Variable Names, Caching Results
-@subsection Cache Files
+The portable way out consists in using a double assignment, to switch
+the 8th bit twice on Ultrix:
-A cache file is a shell script that caches the results of configure
-tests run on one system so they can be shared between configure scripts
-and configure runs. It is not useful on other systems. If its contents
-are invalid for some reason, the user may delete or edit it.
+@example
+list=$@{list="$default"@}
+@end example
-By default, @code{configure} uses no cache file (technically, it uses
-@option{--cache-file=/dev/null}), to avoid problems caused by accidental
-use of stale cache files.
+@noindent
+@dots{}but beware of the @samp{@}} bug from Solaris (see above). For safety,
+use:
-To enable caching, @code{configure} accepts @option{--config-cache} (or
-@option{-C}) to cache results in the file @file{config.cache}.
-Alternatively, @option{--cache-file=@var{file}} specifies that
-@var{file} be the cache file. The cache file is created if it does not
-exist already. When @code{configure} calls @code{configure} scripts in
-subdirectories, it uses the @option{--cache-file} argument so that they
-share the same cache. @xref{Subdirectories}, for information on
-configuring subdirectories with the @code{AC_CONFIG_SUBDIRS} macro.
+@example
+test "$@{var+set@}" = set || var=@var{@{value@}}
+@end example
-@file{config.status} only pays attention to the cache file if it is
-given the @option{--recheck} option, which makes it rerun
-@code{configure}.
-It is wrong to try to distribute cache files for particular system types.
-There is too much room for error in doing that, and too much
-administrative overhead in maintaining them. For any features that
-can't be guessed automatically, use the standard method of the canonical
-system type and linking files (@pxref{Manual Configuration}).
+@item `@var{commands}`
+@cindex `@var{commands}`
+@cindex Command Substitution
+While in general it makes no sense, do not substitute a single builtin
+with side effects as Ash 0.2, trying to optimize, does not fork a
+sub-shell to perform the command.
-The site initialization script can specify a site-wide cache file to
-use, instead of the usual per-program cache. In this case, the cache
-file will gradually accumulate information whenever someone runs a new
-@code{configure} script. (Running @code{configure} merges the new cache
-results with the existing cache file.) This may cause problems,
-however, if the system configuration (e.g. the installed libraries or
-compilers) changes and the stale cache file is not deleted.
+For instance, if you wanted to check that @command{cd} is silent, do not
+use @samp{test -z "`cd /`"} because the following can happen:
-@node Cache Checkpointing, , Cache Files, Caching Results
-@subsection Cache Checkpointing
+@example
+$ pwd
+/tmp
+$ test -n "`cd /`" && pwd
+/
+@end example
-If your configure script, or a macro called from configure.ac, happens
-to abort the configure process, it may be useful to checkpoint the cache
-a few times at key points using @code{AC_CACHE_SAVE}. Doing so will
-reduce the amount of time it takes to re-run the configure script with
-(hopefully) the error that caused the previous abort corrected.
+@noindent
+The result of @samp{foo=`exit 1`} is left as an exercise to the reader.
-@c FIXME: Do we really want to document this guy?
-@defmac AC_CACHE_LOAD
-@maindex CACHE_LOAD
-Loads values from existing cache file, or creates a new cache file if a
-cache file is not found. Called automatically from @code{AC_INIT}.
-@end defmac
-@defmac AC_CACHE_SAVE
-@maindex CACHE_SAVE
-Flushes all cached values to the cache file. Called automatically from
-@code{AC_OUTPUT}, but it can be quite useful to call
-@code{AC_CACHE_SAVE} at key points in configure.ac.
-@end defmac
+@item $(@var{commands})
+@cindex $(@var{commands})
+This construct is meant to replace @samp{`@var{commands}`}; they can be
+nested while this is impossible to do portably with back quotes.
+Unfortunately it is not yet widely supported. Most notably, even recent
+releases of Solaris don't support it:
-For instance:
+@example
+$ showrev -c /bin/sh | grep version
+Command version: SunOS 5.8 Generic 109324-02 February 2001
+$ echo $(echo blah)
+syntax error: `(' unexpected
+@end example
+@noindent
+nor does @sc{irix} 6.5's Bourne shell:
@example
-@r{ @dots{} AC_INIT, etc. @dots{}}
-@group
-# Checks for programs.
-AC_PROG_CC
-AC_PROG_GCC_TRADITIONAL
-@r{ @dots{} more program checks @dots{}}
-AC_CACHE_SAVE
-@end group
+$ uname -a
+IRIX firebird-image 6.5 07151432 IP22
+$ echo $(echo blah)
+$(echo blah)
+@end example
+@end table
-@group
-# Checks for libraries.
-AC_CHECK_LIB(nsl, gethostbyname)
-AC_CHECK_LIB(socket, connect)
-@r{ @dots{} more lib checks @dots{}}
-AC_CACHE_SAVE
-@end group
-@group
-# Might abort...
-AM_PATH_GTK(1.0.2,, (exit 1); exit)
-AM_PATH_GTKMM(0.9.5,, (exit 1); exit)
-@end group
-@r{ @dots{} AC_OUTPUT, etc. @dots{}}
+@node Assignments, Special Shell Variables, Shell Substitutions, Portable Shell
+@section Assignments
+
+When setting several variables in a row, be aware that the order of the
+evaluation is undefined. For instance @samp{foo=1 foo=2; echo $foo}
+gives @samp{1} with sh on Solaris, but @samp{2} with Bash. You must use
+@samp{;} to enforce the order: @samp{foo=1; foo=2; echo $foo}.
+
+Don't rely on the exit status of an assignment: Ash 0.2 does not change
+the status and propagates that of the last statement:
+
+@example
+$ false || foo=bar; echo $?
+1
+$ false || foo=`:`; echo $?
+0
@end example
-@node Printing Messages, , Caching Results, Results
-@section Printing Messages
-@cindex Messages, from @code{configure}
-
-@code{configure} scripts need to give users running them several kinds
-of information. The following macros print messages in ways appropriate
-for each kind. The arguments to all of them get enclosed in shell
-double quotes, so the shell performs variable and back-quote
-substitution on them.
+@noindent
+and to make things even worse, @sc{qnx 4.25} just sets the exit status
+to 0 in any case:
-These macros are all wrappers around the @code{echo} shell command.
-@code{configure} scripts should rarely need to run @code{echo} directly
-to print messages for the user. Using these macros makes it easy to
-change how and when each kind of message is printed; such changes need
-only be made to the macro definitions and all of the callers will change
-automatically.
+@example
+$ foo=`exit 1`; echo $?
+0
+@end example
-To diagnose static issues, i.e., when @code{autoconf} is run, see
-@ref{Reporting Messages}.
+To assign default values, follow this algorithm:
-@defmac AC_MSG_CHECKING (@var{feature-description})
-@maindex MSG_CHECKING
-Notify the user that @code{configure} is checking for a particular
-feature. This macro prints a message that starts with @samp{checking }
-and ends with @samp{...} and no newline. It must be followed by a call
-to @code{AC_MSG_RESULT} to print the result of the check and the
-newline. The @var{feature-description} should be something like
-@samp{whether the Fortran compiler accepts C++ comments} or @samp{for
-c89}.
+@enumerate
+@item
+If the default value is a literal and does not contain any closing
+brace, use:
-This macro prints nothing if @code{configure} is run with the
-@option{--quiet} or @option{--silent} option.
-@end defmac
+@example
+: $@{var='my literal'@}
+@end example
-@defmac AC_MSG_RESULT (@var{result-description})
-@maindex MSG_RESULT
-Notify the user of the results of a check. @var{result-description} is
-almost always the value of the cache variable for the check, typically
-@samp{yes}, @samp{no}, or a file name. This macro should follow a call
-to @code{AC_MSG_CHECKING}, and the @var{result-description} should be
-the completion of the message printed by the call to
-@code{AC_MSG_CHECKING}.
+@item
+If the default value contains no closing brace, has to be expanded, and
+the variable being initialized will never be IFS-split (i.e., it's not a
+list), then use:
-This macro prints nothing if @code{configure} is run with the
-@option{--quiet} or @option{--silent} option.
-@end defmac
+@example
+: $@{var="$default"@}
+@end example
-@defmac AC_MSG_NOTICE (@var{message})
-@maindex MSG_NOTICE
-Deliver the @var{message} to the user. It is useful mainly to print a
-general description of the overall purpose of a group of feature checks,
-e.g.,
+@item
+If the default value contains no closing brace, has to be expanded, and
+the variable being initialized will be IFS-split (i.e., it's a list),
+then use:
@example
-AC_MSG_NOTICE([checking if stack overflow is detectable])
+var=$@{var="$default"@}
@end example
-This macro prints nothing if @code{configure} is run with the
-@option{--quiet} or @option{--silent} option.
-@end defmac
+@item
+If the default value contains a closing brace, then use:
-@defmac AC_MSG_ERROR (@var{error-description}, @ovar{exit-status})
-@maindex MSG_ERROR
-Notify the user of an error that prevents @code{configure} from
-completing. This macro prints an error message to the standard error
-output and exits @code{configure} with @var{exit-status} (1 by default).
-@var{error-description} should be something like @samp{invalid value
-$HOME for \$HOME}.
+@example
+test "$@{var+set@}" = set || var='$@{indirection@}'
+@end example
+@end enumerate
-The @var{error-description} should start with a lower-case letter, and
-``cannot'' is preferred to ``can't''.
-@end defmac
+In most cases @samp{var=$@{var="$default"@}} is fine, but in case of
+doubt, just use the latter. @xref{Shell Substitutions}, items
+@samp{$@{@var{var}:-@var{value}@}} and @samp{$@{@var{var}=@var{value}@}}
+for the rationale.
-@defmac AC_MSG_WARN (@var{problem-description})
-@maindex MSG_WARN
-Notify the @code{configure} user of a possible problem. This macro
-prints the message to the standard error output; @code{configure}
-continues running afterward, so macros that call @code{AC_MSG_WARN} should
-provide a default (back-up) behavior for the situations they warn about.
-@var{problem-description} should be something like @samp{ln -s seems to
-make hard links}.
-@end defmac
+@node Special Shell Variables, Limitations of Builtins, Assignments, Portable Shell
+@section Special Shell Variables
+Some shell variables should not be used, since they can have a deep
+influence on the behavior of the shell. In order to recover a sane
+behavior from the shell, some variables should be unset, but
+@command{unset} is not portable (@pxref{Limitations of Builtins}) and a
+fallback value is needed. We list these values below.
-@c ========================================================== Writing Macros.
+@c Alphabetical order, case insensitive, `A' before `a'.
+@table @code
+@item CDPATH
+@evindex CDPATH
+When this variable is set @code{cd} is verbose, so idioms such as
+@samp{abs=`cd $rel && pwd`} break because @code{abs} receives the path
+twice.
-@node Writing Macros, Manual Configuration, Results, Top
-@chapter Writing Macros
+@c FIXME: Which shells? How do they behave?
+Setting @code{CDPATH} to the empty value is not enough for most shells.
+A simple colon is enough except for @code{zsh}, which prefers a leading
+dot:
-When you write a feature test that could be applicable to more than one
-software package, the best thing to do is encapsulate it in a new macro.
-Here are some instructions and guidelines for writing Autoconf macros.
+@example
+zsh-3.1.6 % mkdir foo && (CDPATH=: cd foo)
+/tmp/foo
+zsh-3.1.6 % (CDPATH=:. cd foo)
+/tmp/foo
+zsh-3.1.6 % (CDPATH=.: cd foo)
+zsh-3.1.6 %
+@end example
-@menu
-* Macro Definitions:: Basic format of an Autoconf macro
-* Macro Names:: What to call your new macros
-* Quoting:: Protecting macros from unwanted expansion
-* Reporting Messages:: Notifying @code{autoconf} users
-* Dependencies Between Macros:: What to do when macros depend on other macros
-* Obsoleting Macros:: Warning about old ways of doing things
-* Coding Style:: Writing Autoconf macros @`a la Autoconf
-@end menu
+@noindent
+(of course we could just @code{unset} @code{CDPATH}, since it also
+behaves properly if set to the empty string).
-@node Macro Definitions, Macro Names, Writing Macros, Writing Macros
-@section Macro Definitions
+Life wouldn't be so much fun if @command{bash} and @command{zsh} had the
+same behavior:
-@maindex DEFUN
-Autoconf macros are defined using the @code{AC_DEFUN} macro, which is
-similar to the M4 builtin @code{define} macro. 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}).
+@example
+bash-2.02 % (CDPATH=:. cd foo)
+bash-2.02 % (CDPATH=.: cd foo)
+/tmp/foo
+@end example
-An Autoconf macro definition looks like this:
+Therefore, a portable solution to neutralize @samp{CDPATH} is
@example
-AC_DEFUN(@var{macro-name}, @var{macro-body})
+CDPATH=$@{ZSH_VERSION+.@}:
@end example
-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,
-GNU m4}, for more complete information on writing M4 macros.
+@noindent
+Note that since @command{zsh} supports @command{unset}, you may unset
+@samp{CDPATH} using @samp{:} as a fallback, see
+@ref{Limitations of Builtins}.
-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.
+@item IFS
+@evindex IFS
+Don't set the first character of @code{IFS} to backslash. Indeed,
+Bourne shells use the first character (backslash) when joining the
+components in @samp{"$@@"} and some shells then re-interpret (!) the
+backslash escapes, so you can end up with backspace and other strange
+characters.
-Each macro should have a header comment that gives its prototype, and a
-brief description. When arguments have default values, display them in
-the prototype. For example:
+@item LANG
+@itemx LC_ALL
+@itemx LC_TIME
+@itemx LC_CTYPE
+@itemx LANGUAGE
+@itemx LC_COLLATE
+@itemx LC_NUMERIC
+@itemx LC_MESSAGES
+@evindex LANG
+@evindex LC_ALL
+@evindex LC_TIME
+@evindex LC_CTYPE
+@evindex LANGUAGE
+@evindex LC_COLLATE
+@evindex LC_NUMERIC
+@evindex LC_MESSAGES
-@example
-# AC_MSG_ERROR(ERROR, [EXIT-STATUS = 1])
-# --------------------------------------
-define([AC_MSG_ERROR],
-[@{ _AC_ECHO([configure: error: $1], 2); exit m4_default([$2], 1); @}])
-@end example
+These must not be set unconditionally because not all systems understand
+e.g. @samp{LANG=C} (notably SCO). Fixing @env{LC_MESSAGES} prevents
+Solaris @command{sh} from translating var values in @code{set}! Non-C
+@env{LC_CTYPE} values break the ctype check. Fixing @env{LC_COLLATE}
+makes scripts more portable in some cases. For example, it causes the
+regular expression @samp{[a-z]} to match only lower-case letters on
+@sc{ascii} platforms. However, @samp{[a-z]} does not work in general
+even when @env{LC_COLLATE} is fixed; for example, it does not work for
+@sc{ebcdic} platforms. For maximum portability, you should use regular
+expressions like @samp{[abcdefghijklmnopqrstuvwxyz]} that list
+characters explicitly instead of relying on ranges.
+
+@emph{If} one of these variables is set, you should try to unset it,
+using @samp{C} as a fall back value. see @ref{Limitations of Builtins},
+builtin @command{unset}, for more details.
+
+@item NULLCMD
+@evindex NULLCMD
+When executing the command @samp{>foo}, @command{zsh} executes
+@samp{$NULLCMD >foo}. The Bourne shell considers @code{NULLCMD} is
+@samp{:}, while @command{zsh}, even in Bourne shell compatibility mode,
+sets @code{NULLCMD} to @samp{cat}. If you forgot to set @code{NULLCMD},
+your script might be suspended waiting for data on its standard input.
+
+@item status
+@evindex status
+This variable is an alias to @samp{$?} for @code{zsh} (at least 3.1.6),
+hence read-only. Do not use it.
+
+@item PATH_SEPARATOR
+@evindex PATH_SEPARATOR
+On DJGPP systems, the @code{PATH_SEPARATOR} variable can be set to
+either @samp{:} or @samp{;} to control the path separator @command{bash}
+uses to set up certain environment variables (such as
+@code{PATH}). Since this only works inside bash, you want autoconf to
+detect the regular @sc{dos} path separator @samp{;}, so it can be safely
+substituted in files that may not support @samp{;} as path separator. So
+either unset this variable or set it to @samp{;}.
-Comments about the macro should be left in the header comment. Most
-other comments will make their way into @file{configure}, so just keep
-using @samp{#} to introduce comments.
+@item RANDOM
+@evindex RANDOM
+Many shells provide @code{RANDOM}, a variable that returns a different
+integer when used. Most of the time, its value does not change when it
+is not used, but on @sc{irix 6.5} the value changes all the time. This
+can be observed by using @command{set}.
+@end table
-@cindex @code{dnl}
-If you have some very special comments about pure M4 code, comments
-that make no sense in @file{configure} and in the header comment, then
-use the builtin @code{dnl}: it causes @code{m4} to discard the text
-through the next newline.
-Keep in mind that @code{dnl} is rarely needed to introduce comments;
-@code{dnl} is more useful to get rid of the newlines following macros
-that produce no output, such as @code{AC_REQUIRE}.
+@node Limitations of Builtins, Limitations of Usual Tools, Special Shell Variables, Portable Shell
+@section Limitations of Shell Builtins
+No, no, we are serious: some shells do have limitations! :)
-@node Macro Names, Quoting, Macro Definitions, Writing Macros
-@section Macro Names
+You should always keep in mind that any built-in or command may support
+options, and therefore have a very different behavior with arguments
+starting with a dash. For instance, the innocent @samp{echo "$word"}
+can give unexpected results when @code{word} starts with a dash. It is
+often possible to avoid this problem using @samp{echo "x$word"}, taking
+the @samp{x} into account later in the pipe.
-All of the Autoconf macros have all-uppercase names starting with
-@samp{AC_} to prevent them from accidentally conflicting with other
-text. All shell variables that they use for internal purposes have
-mostly-lowercase names starting with @samp{ac_}. To ensure that your
-macros don't conflict with present or future Autoconf macros, you should
-prefix your own macro names and any shell variables they use with some
-other sequence. Possibilities include your initials, or an abbreviation
-for the name of your organization or software package.
+@table @asis
+@item @command{!}
+@cindex @command{!}
+You can't use @command{!}, you'll have to rewrite your code.
-Most of the Autoconf macros' names follow a structured naming convention
-that indicates the kind of feature check by the name. The macro names
-consist of several words, separated by underscores, going from most
-general to most specific. The names of their cache variables use the
-same convention (@pxref{Cache Variable Names}, for more information on
-them).
-The first word of the name after @samp{AC_} usually tells the category
-of feature being tested. Here are the categories used in Autoconf for
-specific test macros, the kind of macro that you are more likely to
-write. They are also used for cache variables, in all-lowercase. Use
-them where applicable; where they're not, invent your own categories.
+@item @command{break}
+@c ------------------
+@cindex @command{break}
+The use of @samp{break 2}, etcetera, is safe.
-@table @code
-@item C
-C language builtin features.
-@item DECL
-Declarations of C variables in header files.
-@item FUNC
-Functions in libraries.
-@item GROUP
-@sc{unix} group owners of files.
-@item HEADER
-Header files.
-@item LIB
-C libraries.
-@item PATH
-The full path names to files, including programs.
-@item PROG
-The base names of programs.
-@item MEMBER
-Members of aggregates.
-@item SYS
-Operating system features.
-@item TYPE
-C builtin or declared types.
-@item VAR
-C variables in libraries.
-@end table
-After the category comes the name of the particular feature being
-tested. Any further words in the macro name indicate particular aspects
-of the feature. For example, @code{AC_FUNC_UTIME_NULL} checks the
-behavior of the @code{utime} function when called with a @code{NULL}
-pointer.
+@item @command{case}
+@c -----------------
+@cindex @command{case}
+You don't need to quote the argument; no splitting is performed.
-An internal macro should have a name that starts with an underscore;
-Autoconf internals should therefore start with @samp{_AC_}.
-Additionally, a macro that is an internal subroutine of another macro
-should have a name that starts with an underscore and the name of that
-other macro, followed by one or more words saying what the internal
-macro does. For example, @code{AC_PATH_X} has internal macros
-@code{_AC_PATH_X_XMKMF} and @code{_AC_PATH_X_DIRECT}.
+You don't need the final @samp{;;}, but you should use it.
-@node Quoting, Reporting Messages, Macro Names, Writing Macros
-@section Quoting
-@cindex quotation
+Because of a bug in its @code{fnmatch}, @command{bash} fails to properly
+handle backslashes in character classes:
-@c FIXME: Grmph, yet another quoting myth: quotation has *never*
-@c prevented `expansion' of $1. Unless it refers to the expansion
-@c of the value of $1? Anyway, we need a rewrite here@dots{}
+@example
+bash-2.02$ case /tmp in [/\\]*) echo OK;; esac
+bash-2.02$
+@end example
-The most common brokenness of existing macros is an improper quotation.
-This section, which users of Autoconf can skip, but which macro writers
-@emph{must} read, first justifies the quotation scheme that was chosen
-for Autoconf and then ends with a rule of thumb. Understanding the
-former helps one to follow the latter.
+@noindent
+This is extremely unfortunate, since you are likely to use this code to
+handle @sc{unix} or @sc{ms-dos} absolute paths. To work around this
+bug, always put the backslash first:
-@menu
-* Active Characters:: Characters that change the behavior of m4
-* One Macro Call:: Quotation and one macro call
-* Quotation and Nested Macros:: Macros calling macros
-* Quotation Rule Of Thumb:: One parenthesis, one quote
-@end menu
+@example
+bash-2.02$ case '\TMP' in [\\/]*) echo OK;; esac
+OK
+bash-2.02$ case /tmp in [\\/]*) echo OK;; esac
+OK
+@end example
-@node Active Characters, One Macro Call, Quoting, Quoting
-@subsection Active Characters
-To fully understand where proper quotation is important, you first need
-to know what are the special characters in Autoconf: @samp{#} introduces
-a comment inside which no macro expansion is performed, @samp{,}
-separates arguments, @samp{[} and @samp{]} are the quotes themselves,
-and finally @samp{(} and @samp{)} (which @code{m4} tries to match by
-pairs).
+@item @command{echo}
+@c -----------------
+@cindex @command{echo}
+The simple @code{echo} is probably the most surprising source of
+portability troubles. It is not possible to use @samp{echo} portably
+unless both options and escape sequences are omitted. New applications
+which are not aiming at portability should use @samp{printf} instead of
+@samp{echo}.
-In order to understand the delicate case of macro calls, we first have
-to present some obvious failures. Below they are ``obvious-ified'',
-although you find them in real life, they are usually in disguise.
+Don't expect any option. @xref{Preset Output Variables}, @code{ECHO_N}
+etc. for a means to simulate @option{-c}.
-Comments, introduced by a hash and running up to the newline, are opaque
-tokens to the top level: active characters are turned off, and there is
-no macro expansion:
+Do not use backslashes in the arguments, as there is no consensus on
+their handling. On @samp{echo '\n' | wc -l}, the @command{sh} of
+Digital Unix 4.0, @sc{mips risc/os} 4.52, answer 2, but the Solaris'
+@command{sh}, Bash and Zsh (in @command{sh} emulation mode) report 1.
+Please note that the problem is truly @command{echo}: all the shells
+understand @samp{'\n'} as the string composed of a backslash and an
+@samp{n}.
+
+Because of these problems, do not pass a string containing arbitrary
+characters to @command{echo}. For example, @samp{echo "$foo"} is safe
+if you know that @var{foo}'s value cannot contain backslashes and cannot
+start with @samp{-}, but otherwise you should use a here-document like
+this:
@example
-# define([def], ine)
-@result{}# define([def], ine)
+cat <<EOF
+$foo
+EOF
@end example
-Each time there can be a macro expansion, there is a quotation
-expansion; i.e., one level of quotes is stripped:
+
+@item @command{exit}
+@c -----------------
+@cindex @command{exit}
+The default value of @command{exit} is supposed to be @code{$?};
+unfortunately, some shells, such as the DJGPP port of Bash 2.04, just
+perform @samp{exit 0}.
@example
-int tab[10];
-@result{}int tab10;
-[int tab[10];]
-@result{}int tab[10];
+bash-2.04$ foo=`exit 1` || echo fail
+fail
+bash-2.04$ foo=`(exit 1)` || echo fail
+fail
+bash-2.04$ foo=`(exit 1); exit` || echo fail
+bash-2.04$
@end example
-Without this in mind, the reader will try hopelessly to use her macro
-@code{array}:
+Using @samp{exit $?} restores the expected behavior.
-@example
-define([array], [int tab[10];])
-array
-@result{}int tab10;
-[array]
-@result{}array
-@end example
+Some shell scripts, such as those generated by @command{autoconf}, use a
+trap to clean up before exiting. If the last shell command exited with
+nonzero status, the trap also exits with nonzero status so that the
+invoker can tell that an error occurred.
-@noindent
-How can you correctly output the intended results@footnote{Using
-@code{defn}.}?
+Unfortunately, in some shells, such as Solaris 8 @command{sh}, an exit
+trap ignores the @code{exit} command's status. In these shells, a trap
+cannot determine whether it was invoked by plain @code{exit} or by
+@code{exit 1}. Instead of calling @code{exit} directly, use the
+@code{AC_MSG_ERROR} macro that has a workaround for this problem.
-@node One Macro Call, Quotation and Nested Macros, Active Characters, Quoting
-@subsection One Macro Call
+@item @command{export}
+@c -------------------
+@cindex @command{export}
+The builtin @command{export} dubs @dfn{environment variable} a shell
+variable. Each update of exported variables corresponds to an update of
+the environment variables. Conversely, each environment variable
+received by the shell when it is launched should be imported as a shell
+variable marked as exported.
-Let's proceed on the interaction between active characters and macros
-with this small macro, which just returns its first argument:
+Alas, many shells, such as Solaris 2.5, IRIX 6.3, IRIX 5.2, AIX 4.1.5
+and DU 4.0, forget to @command{export} the environment variables they
+receive. As a result, two variables are coexisting: the environment
+variable and the shell variable. The following code demonstrates this
+failure:
@example
-define([car], [$1])
+#! /bin/sh
+echo $FOO
+FOO=bar
+echo $FOO
+exec /bin/sh $0
@end example
-@noindent
-The two pairs of quotes above are not part of the arguments of
-@code{define}; rather, they are understood by the top level when it
-tries to find the arguments of @code{define}. Therefore, it is
-equivalent to write:
+@noindent
+when run with @samp{FOO=foo} in the environment, these shells will print
+alternately @samp{foo} and @samp{bar}, although it should only print
+@samp{foo} and then a sequence of @samp{bar}s.
+
+Therefore you should @command{export} again each environment variable
+that you update.
+
+
+@item @command{false}
+@c ------------------
+@cindex @command{false}
+Don't expect @command{false} to exit with status 1: in the native Bourne
+shell of Solaris 8, it exits with status 255.
+
+
+@item @command{for}
+@c ----------------
+@cindex @command{for}
+To loop over positional arguments, use:
@example
-define(car, $1)
+for arg
+do
+ echo "$arg"
+done
@end example
@noindent
-But, while it is acceptable for a @file{configure.ac} to avoid unneeded
-quotes, it is bad practice for Autoconf macros which must both be more
-robust and also advocate perfect style.
-
-At the top level, there are only two possible quotings: either you
-quote or you don't:
+You may @emph{not} leave the @code{do} on the same line as @code{for},
+since some shells improperly grok:
@example
-car(foo, bar, baz)
-@result{}foo
-[car(foo, bar, baz)]
-@result{}car(foo, bar, baz)
+for arg; do
+ echo "$arg"
+done
@end example
-Let's pay attention to the special characters:
+If you want to explicitly refer to the positional arguments, given the
+@samp{$@@} bug (@pxref{Shell Substitutions}), use:
@example
-car(#)
-@error{}EOF in argument list
+for arg in $@{1+"$@@"@}; do
+ echo "$arg"
+done
@end example
-The closing parenthesis is hidden in the comment; with a hypothetical
-quoting, the top level understood it this way:
+@item @command{if}
+@c ---------------
+@cindex @command{if}
+Using @samp{!} is not portable. Instead of:
@example
-car([#)]
+if ! cmp -s file file.new; then
+ mv file.new file
+fi
@end example
@noindent
-Proper quotation, of course, fixes the problem:
+use:
@example
-car([#])
-@result{}#
+if cmp -s file file.new; then :; else
+ mv file.new file
+fi
@end example
-The reader will easily understand the following examples:
+There are shells that do not reset the exit status from an @command{if}:
@example
-car(foo, bar)
-@result{}foo
-car([foo, bar])
-@result{}foo, bar
-car((foo, bar))
-@result{}(foo, bar)
-car([(foo], [bar)])
-@result{}(foo
-car([], [])
-@result{}
-car([[]], [[]])
-@result{}[]
+$ if (exit 42); then true; fi; echo $?
+42
@end example
-With this in mind, we can explore the cases where macros invoke
-macros@dots{}
-
-
-@node Quotation and Nested Macros, Quotation Rule Of Thumb, One Macro Call, Quoting
-@subsection Quotation and Nested Macros
-
-The examples below use the following macros:
+@noindent
+whereas a proper shell should have printed @samp{0}. This is especially
+bad in Makefiles since it produces false failures. This is why properly
+written Makefiles, such as Automake's, have such hairy constructs:
@example
-define([car], [$1])
-define([active], [ACT, IVE])
-define([array], [int tab[10]])
+if test -f "$file"; then
+ install "$file" "$dest"
+else
+ :
+fi
@end example
-Each additional embedded macro call introduces other possible
-interesting quotations:
-
-@example
-car(active)
-@result{}ACT
-car([active])
-@result{}ACT, IVE
-car([[active]])
-@result{}active
-@end example
-In the first case, the top level looks for the arguments of @code{car},
-and finds @samp{active}. Because @code{m4} evaluates its arguments
-before applying the macro, @samp{active} is expanded, which results in:
+@item @command{set}
+@c ----------------
+@cindex @command{set}
+This builtin faces the usual problem with arguments starting with a
+dash. Modern shells such as Bash or Zsh understand @option{--} to specify
+the end of the options (any argument after @option{--} is a parameters,
+even @samp{-x} for instance), but most shells simply stop the option
+processing as soon as a non-option argument is found. Therefore, use
+@samp{dummy} or simply @samp{x} to end the option processing, and use
+@command{shift} to pop it out:
@example
-car(ACT, IVE)
-@result{}ACT
+set x $my_list; shift
@end example
-@noindent
-In the second case, the top level gives @samp{active} as first and only
-argument of @code{car}, which results in:
+@item @command{shift}
+@c ------------------
+@cindex @command{shift}
+Not only is @command{shift}ing a bad idea when there is nothing left to
+shift, but in addition it is not portable: the shell of @sc{mips
+risc/os} 4.52 refuses to do it.
-@example
-active
-@result{}ACT, IVE
-@end example
+@item @command{test}
+@c -----------------
+@cindex @command{test}
+The @code{test} program is the way to perform many file and string
+tests. It is often invoked by the alternate name @samp{[}, but using
+that name in Autoconf code is asking for trouble since it is an M4 quote
+character.
-@noindent
-i.e., the argument is evaluated @emph{after} the macro that invokes it.
-In the third case, @code{car} receives @samp{[active]}, which results in:
+If you need to make multiple checks using @code{test}, combine them with
+the shell operators @samp{&&} and @samp{||} instead of using the
+@code{test} operators @option{-a} and @option{-o}. On System V, the
+precedence of @option{-a} and @option{-o} is wrong relative to the unary
+operators; consequently, @sc{posix} does not specify them, so using them
+is nonportable. If you combine @samp{&&} and @samp{||} in the same
+statement, keep in mind that they have equal precedence.
-@example
-[active]
-@result{}active
-@end example
+You may use @samp{!} with @command{test}, but not with @command{if}:
+@samp{test ! -r foo || exit 1}.
-@noindent
-exactly as we already saw above.
+@item @command{test} (files)
+@c -------------------------
+To enable @code{configure} scripts to support cross-compilation, they
+shouldn't do anything that tests features of the build system instead of
+the host system. But occasionally you may find it necessary to check
+whether some arbitrary file exists. To do so, use @samp{test -f} or
+@samp{test -r}. Do not use @samp{test -x}, because @sc{4.3bsd} does not
+have it. Do not use @samp{test -e} either, because Solaris 2.5 does not
+have it.
-The example above, applied to a more realistic example, gives:
+@item @command{test} (strings)
+@c ---------------------------
+Avoid @samp{test "@var{string}"}, in particular if @var{string} might
+start with a dash, since @code{test} might interpret its argument as an
+option (e.g., @samp{@var{string} = "-n"}).
+
+Contrary to a common belief, @samp{test -n @var{string}} and @samp{test
+-z @var{string}} @strong{are} portable, nevertheless many shells (such
+as Solaris 2.5, AIX 3.2, UNICOS 10.0.0.6, Digital Unix 4 etc.) have
+bizarre precedence and may be confused if @var{string} looks like an
+operator:
@example
-car(int tab[10];)
-@result{}int tab10;
-car([int tab[10];])
-@result{}int tab10;
-car([[int tab[10];]])
-@result{}int tab[10];
+$ test -n =
+test: argument expected
@end example
-@noindent
-Huh? The first case is easily understood, but why is the second wrong,
-and the third right? To understand that, you must know that after
-@code{m4} expands a macro, the resulting text is immediately subjected
-to macro expansion and quote removal. This means that the quote removal
-occurs twice---first before the argument is passed to the @code{car}
-macro, and second after the @code{car} macro expands to the first
-argument.
+If there are risks, use @samp{test "x@var{string}" = x} or @samp{test
+"x@var{string}" != x} instead.
-As the author of the Autoconf macro @code{car}, you then consider it to
-be incorrect that your users have to double-quote the arguments of
-@code{car}, so you ``fix'' your macro. Let's call it @code{qar} for
-quoted car:
+It is frequent to find variations of the following idiom:
@example
-define([qar], [[$1]])
+test -n "`echo $ac_feature | sed 's/[-a-zA-Z0-9_]//g'`" &&
+ @var{action}
@end example
@noindent
-and check that @code{qar} is properly fixed:
+to take an action when a token matches a given pattern. Such constructs
+should always be avoided by using:
@example
-qar([int tab[10];])
-@result{}int tab[10];
+echo "$ac_feature" | grep '[^-a-zA-Z0-9_]' >/dev/null 2>&1 &&
+ @var{action}
@end example
@noindent
-Ahhh! That's much better.
+Use @code{case} where possible since it is faster, being a shell builtin:
-But note what you've done: now that the arguments are literal strings,
-if the user wants to use the results of expansions as arguments, she has
-to use an @emph{unquoted} macro call:
@example
-qar(active)
-@result{}ACT
+case $ac_feature in
+ *[!-a-zA-Z0-9_]*) @var{action};;
+esac
@end example
-@noindent
-where she wanted to reproduce what she used to do with @code{car}:
+Alas, negated character classes are probably not portable, although no
+shell is known to not support the @sc{posix.2} syntax @samp{[!@dots{}]}
+(when in interactive mode, @command{zsh} is confused by the
+@samp{[!@dots{}]} syntax and looks for an event in its history because of
+@samp{!}). Many shells do not support the alternative syntax
+@samp{[^@dots{}]} (Solaris, Digital Unix, etc.).
+
+One solution can be:
@example
-car([active])
-@result{}ACT, IVE
+expr "$ac_feature" : '.*[^-a-zA-Z0-9_]' >/dev/null &&
+ @var{action}
@end example
@noindent
-Worse yet: she wants to use a macro that produces a set of @code{cpp}
-macros:
+or better yet
@example
-define([my_includes], [#include <stdio.h>])
-car([my_includes])
-@result{}#include <stdio.h>
-qar(my_includes)
-@error{}EOF in argument list
+expr "x$ac_feature" : '.*[^-a-zA-Z0-9_]' >/dev/null &&
+ @var{action}
@end example
-This macro, @code{qar}, because it double quotes its arguments, forces
-its users to leave their macro calls unquoted, which is dangerous.
-Commas and other active symbols are interpreted by @code{m4} before
-they are given to the macro, often not in the way the users expect.
-Also, because @code{qar} behaves differently from the other macros,
-it's an exception that should be avoided in Autoconf.
-
-@node Quotation Rule Of Thumb, , Quotation and Nested Macros, Quoting
-@subsection Quotation Rule Of Thumb
+@samp{expr "X@var{foo}" : "X@var{bar}"} is more robust than @samp{echo
+"X@var{foo}" | grep "^X@var{bar}"}, because it avoids problems when
+@samp{@var{foo}} contains backslashes.
-To conclude, the quotation rule of thumb is:
-@center @emph{One pair of quotes per pair of parentheses.}
+@item @command{trap}
+@c -----------------
+@cindex @command{trap}
+It is safe to trap at least the signals 1, 2, 13 and 15. You can also
+trap 0, i.e., have the @command{trap} run when the script ends (either via an
+explicit @command{exit}, or the end of the script).
-Never over-quote, never under-quote, in particular in the definition of
-macros. In the few places where the macros need to use brackets
-(usually in C program text or regular expressions), properly quote
-@emph{the arguments}!
+Although @sc{posix} is not absolutely clear on this point, it is widely
+admitted that when entering the trap @samp{$?} should be set to the exit
+status of the last command run before the trap. The ambiguity can be
+summarized as: ``when the trap is launched by an @command{exit}, what is
+the @emph{last} command run: that before @command{exit}, or
+@command{exit} itself?''
-It is common to read Autoconf programs with snippets like:
+Bash considers @command{exit} to be the last command, while Zsh and
+Solaris 8 @command{sh} consider that when the trap is run it is
+@emph{still} in the @command{exit}, hence it is the previous exit status
+that the trap receives:
@example
-AC_TRY_LINK(
-changequote(<<, >>)dnl
-<<#include <time.h>
-#ifndef tzname /* For SGI. */
-extern char *tzname[]; /* RS6000 and others reject char **tzname. */
-#endif>>,
-changequote([, ])dnl
-[atoi (*tzname);], ac_cv_var_tzname=yes, ac_cv_var_tzname=no)
+$ cat trap.sh
+trap 'echo $?' 0
+(exit 42); exit 0
+$ zsh trap.sh
+42
+$ bash trap.sh
+0
@end example
-@noindent
-which is incredibly useless since @code{AC_TRY_LINK} is @emph{already}
-double quoting, so you just need:
+The portable solution is then simple: when you want to @samp{exit 42},
+run @samp{(exit 42); exit 42}, the first @command{exit} being used to
+set the exit status to 42 for Zsh, and the second to trigger the trap
+and pass 42 as exit status for Bash.
+
+The shell in FreeBSD 4.0 has the following bug: @samp{$?} is reset to 0
+by empty lines if the code is inside @command{trap}.
@example
-AC_TRY_LINK(
-[#include <time.h>
-#ifndef tzname /* For SGI. */
-extern char *tzname[]; /* RS6000 and others reject char **tzname. */
-#endif],
- [atoi (*tzname);],
- [ac_cv_var_tzname=yes],
- [ac_cv_var_tzname=no])
+$ trap 'false
+
+echo $?' 0
+$ exit
+0
@end example
@noindent
-The M4-fluent reader will note that these two examples are rigorously
-equivalent, since @code{m4} swallows both the @samp{changequote(<<, >>)}
-and @samp{<<} @samp{>>} when it @dfn{collects} the arguments: these
-quotes are not part of the arguments!
+Fortunately, this bug only affects @command{trap}.
-Simplified, the example above is just doing this:
+@item @command{true}
+@c -----------------
+@cindex @command{true}
+@cindex @command{:}
+Don't worry: as far as we know @command{true} is portable.
+Nevertheless, it's not always a builtin (e.g., Bash 1.x), and the
+portable shell community tends to prefer using @command{:}. This has a
+funny side effect: when asked whether @command{false} is more portable
+than @command{true} Alexandre Oliva answered:
+
+@quotation
+In a sense, yes, because if it doesn't exist, the shell will produce an
+exit status of failure, which is correct for @command{false}, but not
+for @command{true}.
+@end quotation
+
+
+@item @command{unset}
+@c ------------------
+@cindex @command{unset}
+You cannot assume the support of @command{unset}, nevertheless, because
+it is extremely useful to disable embarrassing variables such as
+@code{CDPATH} or @code{LANG}, you can test for its existence and use
+it @emph{provided} you give a neutralizing value when @command{unset} is
+not supported:
@example
-changequote(<<, >>)dnl
-<<[]>>
-changequote([, ])dnl
+if (unset FOO) >/dev/null 2>&1; then
+ unset=unset
+else
+ unset=false
+fi
+$unset CDPATH || CDPATH=:
@end example
-@noindent
-instead of simply:
+@xref{Special Shell Variables}, for some neutralizing values. Also, see
+@ref{Limitations of Builtins}, documentation of @command{export}, for
+the case of environment variables.
+@end table
+
+@node Limitations of Usual Tools, Limitations of Make, Limitations of Builtins, Portable Shell
+@section Limitations of Usual Tools
+
+The small set of tools you can expect to find on any machine can still
+include some limitations you should be aware of.
+
+@table @asis
+@item @command{awk}
+@c ----------------
+@cindex @command{awk}
+Don't leave white spaces before the parentheses in user functions calls,
+@sc{gnu} awk will reject it:
@example
-[[]]
+$ gawk 'function die () @{ print "Aaaaarg!" @}
+ BEGIN @{ die () @}'
+gawk: cmd. line:2: BEGIN @{ die () @}
+gawk: cmd. line:2: ^ parse error
+$ gawk 'function die () @{ print "Aaaaarg!" @}
+ BEGIN @{ die() @}'
+Aaaaarg!
@end example
-
-With macros that do not double quote their arguments (which is the
-rule), double-quote the (risky) literals:
+If you want your program to be deterministic, don't depend on @code{for}
+on arrays:
@example
-AC_LINK_IFELSE([AC_LANG_PROGRAM(
-[[#include <time.h>
-#ifndef tzname /* For SGI. */
-extern char *tzname[]; /* RS6000 and others reject char **tzname. */
-#endif]],
- [atoi (*tzname);])],
- [ac_cv_var_tzname=yes],
- [ac_cv_var_tzname=no])
+$ cat for.awk
+END @{
+ arr["foo"] = 1
+ arr["bar"] = 1
+ for (i in arr)
+ print i
+@}
+$ gawk -f for.awk </dev/null
+foo
+bar
+$ nawk -f for.awk </dev/null
+bar
+foo
@end example
-@c FIXME: Quadrigraphs and hopeless cases.
-When you create a @code{configure} script using newly written macros,
-examine it carefully to check whether you need to add more quotes in
-your macros. If one or more words have disappeared in the @code{m4}
-output, you need more quotes. When in doubt, quote.
+@item @command{cat}
+@c ----------------
+@cindex @command{cat}
+Don't rely on any option. The option @option{-v}, which displays
+non-printing characters, @emph{seems} portable, though.
-However, it's also possible to put on too many layers of quotes. If
-this happens, the resulting @code{configure} script will contain
-unexpanded macros. The @code{autoconf} program checks for this problem
-by doing @samp{grep AC_ configure}.
+@item @command{cmp}
+@c ----------------
+@cindex @command{cmp}
+@command{cmp} performs a raw data comparison of two files, while
+@command{diff} compares two text files. Therefore, if you might compare
+DOS files, even if only checking whether two files are different, use
+@command{diff} to avoid spurious differences due to differences of
+newline encoding.
-@node Reporting Messages, Dependencies Between Macros, Quoting, Writing Macros
-@section Reporting Messages
-@cindex Messages, from @code{autoconf}
-When macros statically diagnose abnormal situations, benign or fatal,
-they should report them using these macros. For dynamic issues, i.e.,
-when @code{configure} is run, see @ref{Printing Messages}.
+@item @command{cp}
+@c ---------------
+@cindex @command{cp}
+@c This is thanks to Ian.
+SunOS @command{cp} does not support @option{-f}, although its
+@command{mv} does. It's possible to deduce why @command{mv} and
+@command{cp} are different with respect to @option{-f}. @command{mv}
+prompts by default before overwriting a read-only file. @command{cp}
+does not. Therefore, @command{mv} requires a @option{-f} option, but
+@command{cp} does not. @command{mv} and @command{cp} behave differently
+with respect to read-only files because the simplest form of
+@command{cp} cannot overwrite a read-only file, but the simplest form of
+@command{mv} can. This is because @command{cp} opens the target for
+write access, whereas @command{mv} simply calls @code{link} (or, in
+newer systems, @code{rename}).
+@c Ian said: ``I don't think -p or -r are portable''!!! How can you live
+@c without -r???
-@defmac AC_DIAGNOSE (@var{category}, @var{message})
-@maindex DIAGNOSE
-Report @var{message} as a warning (or as an error if requested by the
-user) if it falls into the @var{category}. You are encouraged to use
-standard categories, which currently include:
-@table @samp
-@item all
-messages that don't fall into one of the following category. Use of an
-empty @var{category} is equivalent.
+@item @command{diff}
+@c -----------------
+@cindex @command{diff}
+Option @option{-u} is nonportable.
-@item cross
-related to cross compilation issues.
+Some implementations, such as Tru64's, fail when comparing to
+@file{/dev/null}. Use an empty file instead.
-@item obsolete
-use of an obsolete construct.
+@item @command{dirname}
+@c --------------------
+@cindex @command{dirname}
+Not all hosts have @command{dirname}, but it is reasonably easy to
+emulate, e.g.:
-@item syntax
-dubious syntactic constructs, incorrectly ordered macro calls.
-@end table
-@end defmac
+@example
+dir=`expr "x$file" : 'x\(.*\)/[^/]*' \|
+ '.' : '.'
+@end example
-@defmac AC_WARNING (@var{message})
-@maindex WARNING
-Equivalent to @samp{AC_DIAGNOSE([syntax], @var{message})}, but you are
-strongly encouraged to use a finer grained category.
-@end defmac
+@noindent
+But there are a few subtilities, e.g., under UN*X, should @samp{//1}
+give @samp{/}? Paul Eggert answers:
-@defmac AC_FATAL (@var{message})
-@maindex FATAL
-Report a severe error @var{message}, and have @code{autoconf} die.
-@end defmac
+@quotation
+No, under some older flavors of Unix, leading @samp{//} is a special
+path name: it refers to a ``super-root'' and is used to access other
+machines' files. Leading @samp{///}, @samp{////}, etc. are equivalent
+to @samp{/}; but leading @samp{//} is special. I think this tradition
+started with Apollo Domain/OS, an OS that is still in use on some older
+hosts.
-When the user runs @samp{autoconf -W error}, warnings from
-@code{AC_DIAGNOSE} and @code{AC_WARNING} are reported as error, see
-@ref{autoconf Invocation}.
+POSIX.2 allows but does not require the special treatment for @samp{//}.
+It says that the behavior of dirname on path names of the form
+@samp{//([^/]+/*)?} is implementation defined. In these cases, GNU
+@command{dirname} returns @samp{/}, but it's more portable to return
+@samp{//} as this works even on those older flavors of Unix.
-@node Dependencies Between Macros, Obsoleting Macros, Reporting Messages, Writing Macros
-@section Dependencies Between Macros
+I have heard rumors that this special treatment of @samp{//} may be
+dropped in future versions of POSIX, but for now it's still the
+standard.
+@end quotation
-Some Autoconf macros depend on other macros having been called first in
-order to work correctly. Autoconf provides a way to ensure that certain
-macros are called if needed and a way to warn the user if macros are
-called in an order that might cause incorrect operation.
-@menu
-* Prerequisite Macros:: Ensuring required information
-* Suggested Ordering:: Warning about possible ordering problems
-@end menu
+@item @command{egrep}
+@c ------------------
+@cindex @command{egrep}
+The empty alternative is not portable, use @samp{?} instead. For
+instance with Digital Unix v5.0:
-@node Prerequisite Macros, Suggested Ordering, Dependencies Between Macros, Dependencies Between Macros
-@subsection Prerequisite Macros
+@example
+> printf "foo\n|foo\n" | egrep '^(|foo|bar)$'
+|foo
+> printf "bar\nbar|\n" | egrep '^(foo|bar|)$'
+bar|
+> printf "foo\nfoo|\n|bar\nbar\n" | egrep '^(foo||bar)$'
+foo
+|bar
+@end example
-A macro that you write might need to use values that have previously
-been computed by other macros. For example, @code{AC_DECL_YYTEXT}
-examines the output of @code{flex} or @code{lex}, so it depends on
-@code{AC_PROG_LEX} having been called first to set the shell variable
-@code{LEX}.
+@command{egrep} also suffers the limitations of @command{grep}.
-Rather than forcing the user of the macros to keep track of the
-dependencies between them, you can use the @code{AC_REQUIRE} macro to do
-it automatically. @code{AC_REQUIRE} can ensure that a macro is only
-called if it is needed, and only called once.
-@defmac AC_REQUIRE (@var{macro-name})
-@maindex REQUIRE
-If the M4 macro @var{macro-name} has not already been called, call it
-(without any arguments). Make sure to quote @var{macro-name} with
-square brackets. @var{macro-name} must have been defined using
-@code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate
-that it has been called.
+@item @command{expr}
+@c -----------------
+@cindex @command{expr}
+No @command{expr} keyword starts with @samp{x}, so use @samp{expr
+x"@var{word}" : 'x@var{regex}'} to keep @command{expr} from
+misinterpreting @var{word}.
-@code{AC_REQUIRE} must be used inside an @code{AC_DEFUN}'d macro; it
-must not be called from the top level.
-@end defmac
+Don't use @code{length}, @code{substr}, @code{match} and @code{index}.
-@code{AC_REQUIRE} is often misunderstood. It really implements
-dependencies between macros in the sense that if one macro depends upon
-another, the latter will be expanded @emph{before} the body of the
-former. In particular, @samp{AC_REQUIRE(FOO)} is not replaced with the
-body of @code{FOO}. For instance, this definition of macros:
+@item @command{expr} (@samp{|})
+@cindex @command{expr} (@samp{|})
+You can use @samp{|}. Although @sc{posix} does require that @samp{expr
+''} return the empty string, it does not specify the result when you
+@samp{|} together the empty string (or zero) with the empty string. For
+example:
@example
-@group
-AC_DEFUN([TRAVOLTA],
-[test "$body_temparature_in_celsius" -gt "38" &&
- dance_floor=occupied])
-AC_DEFUN([NEWTON_JOHN],
-[test "$hair_style" = "curly" &&
- dance_floor=occupied])
-@end group
-
-@group
-AC_DEFUN([RESERVE_DANCE_FLOOR],
-[if date | grep '^Sat.*pm' >/dev/null 2>&1; then
- AC_REQUIRE([TRAVOLTA])
- AC_REQUIRE([NEWTON_JOHN])
-fi])
-@end group
+expr '' \| ''
@end example
-@noindent
-with this @file{configure.ac}
+@sc{gnu}/Linux and @sc{posix.2-1992} return the empty string for this
+case, but traditional Unix returns @samp{0} (Solaris is one such
+example). In the latest @sc{posix} draft, the specification has been
+changed to match traditional Unix's behavior (which is bizarre, but it's
+too late to fix this). Please note that the same problem does arise
+when the empty string results from a computation, as in:
@example
-AC_INIT
-RESERVE_DANCE_FLOOR
-if test "$dance_floor" = occupied; then
- AC_MSG_ERROR([cannot pick up here, let's move])
-fi
+expr bar : foo \| foo : bar
@end example
@noindent
-will not leave you with a better chance to meet a kindred soul at
-other times than Saturday night since it expands into:
+Avoid this portability problem by avoiding the empty string.
-@example
-@group
-test "$body_temperature_in_Celsius" -gt "38" &&
- dance_floor=occupied
-test "$hair_style" = "curly" &&
- dance_floor=occupied
-fi
-if date | grep '^Sat.*pm' >/dev/null 2>&1; then
+@item @command{expr} (@samp{:})
+@c ----------------------------
+@cindex @command{expr}
+Don't use @samp{\?}, @samp{\+} and @samp{\|} in patterns, they are
+not supported on Solaris.
-fi
-@end group
-@end example
+The @sc{posix.2-1992} standard is ambiguous as to whether @samp{expr a :
+b} (and @samp{expr 'a' : '\(b\)'}) output @samp{0} or the empty string.
+In practice, it outputs the empty string on most platforms, but portable
+scripts should not assume this. For instance, the @sc{qnx} 4.25 native
+@command{expr} returns @samp{0}.
-This behavior was chosen on purpose: (i) it prevents messages in
-required macros from interrupting the messages in the requiring macros;
-(ii) it avoids bad surprises when shell conditionals are used, as in:
+You may believe that one means to get a uniform behavior would be to use
+the empty string as a default value:
@example
-@group
-if @dots{}; then
- AC_REQUIRE([SOME_CHECK])
-fi
-@dots{}
-SOME_CHECK
-@end group
+expr a : b \| ''
@end example
+@noindent
+unfortunately this behaves exactly as the original expression, see the
+@samp{@command{expr} (@samp{:})} entry for more information.
-You are encouraged to put all @code{AC_REQUIRE}s at the beginning of a
-macro. You can use @code{dnl} to avoid the empty lines they leave.
+Older @command{expr} implementations (e.g. SunOS 4 @command{expr} and
+Solaris 8 @command{/usr/ucb/expr}) have a silly length limit that causes
+@command{expr} to fail if the matched substring is longer than 120
+bytes. In this case, you might want to fall back on @samp{echo|sed} if
+@command{expr} fails.
-@node Suggested Ordering, , Prerequisite Macros, Dependencies Between Macros
-@subsection Suggested Ordering
+Don't leave, there is some more!
-Some macros should be run before another macro if both are called, but
-neither @emph{requires} that the other be called. For example, a macro
-that changes the behavior of the C compiler should be called before any
-macros that run the C compiler. Many of these dependencies are noted in
-the documentation.
+The @sc{qnx} 4.25 @command{expr}, in addition of preferring @samp{0} to
+the empty string, has a funny behavior in its exit status: it's always 1
+when parentheses are used!
-Autoconf provides the @code{AC_BEFORE} macro to warn users when macros
-with this kind of dependency appear out of order in a
-@file{configure.ac} file. The warning occurs when creating
-@code{configure} from @file{configure.ac}, not when running
-@code{configure}.
+@example
+$ val=`expr 'a' : 'a'`; echo "$?: $val"
+0: 1
+$ val=`expr 'a' : 'b'`; echo "$?: $val"
+1: 0
-For example, @code{AC_PROG_CPP} checks whether the C compiler
-can run the C preprocessor when given the @option{-E} option. It should
-therefore be called after any macros that change which C compiler is
-being used, such as @code{AC_PROG_CC}. So @code{AC_PROG_CC} contains:
+$ val=`expr 'a' : '\(a\)'`; echo "?: $val"
+1: a
+$ val=`expr 'a' : '\(b\)'`; echo "?: $val"
+1: 0
+@end example
+
+@noindent
+In practice this can be a big problem if you are ready to catch failures
+of @command{expr} programs with some other method (such as using
+@command{sed}), since you may get twice the result. For instance
@example
-AC_BEFORE([$0], [AC_PROG_CPP])dnl
+$ expr 'a' : '\(a\)' || echo 'a' | sed 's/^\(a\)$/\1/'
@end example
@noindent
-This warns the user if a call to @code{AC_PROG_CPP} has already occurred
-when @code{AC_PROG_CC} is called.
+will output @samp{a} on most hosts, but @samp{aa} on @sc{qnx} 4.25. A
+simple work around consists in testing @command{expr} and use a variable
+set to @command{expr} or to @command{false} according to the result.
-@defmac AC_BEFORE (@var{this-macro-name}, @var{called-macro-name})
-@maindex BEFORE
-Make @code{m4} print a warning message to the standard error output if
-@var{called-macro-name} has already been called. @var{this-macro-name}
-should be the name of the macro that is calling @code{AC_BEFORE}. The
-macro @var{called-macro-name} must have been defined using
-@code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate
-that it has been called.
-@end defmac
-@node Obsoleting Macros, Coding Style, Dependencies Between Macros, Writing Macros
-@section Obsoleting Macros
+@item @command{find}
+@c -----------------
+The option @option{-maxdepth} seems to be GNU specific. Tru64 v5.1,
+NetBSD 1.5 and Solaris 2.5 @command{find} commands do not understand it.
-Configuration and portability technology has evolved over the years.
-Often better ways of solving a particular problem are developed, or
-ad-hoc approaches are systematized. This process has occurred in many
-parts of Autoconf. One result is that some of the macros are now
-considered @dfn{obsolete}; they still work, but are no longer considered
-the best thing to do, hence they should be replaced with more modern
-macros. Ideally, @code{autoupdate} should substitute the old macro calls
-with their modern implementation.
-Autoconf provides a simple means to obsolete a macro.
+@item @command{grep}
+@c -----------------
+@cindex @command{grep}
+Don't use @samp{grep -s} to suppress output, because @samp{grep -s} on
+System V does not suppress output, only error messages. Instead,
+redirect the standard output and standard error (in case the file
+doesn't exist) of @code{grep} to @file{/dev/null}. Check the exit
+status of @code{grep} to determine whether it found a match.
-@defmac AU_DEFUN (@var{old-macro}, @var{implementation}, @ovar{message})
-@maindex DEFUN
-@maindex AU_DEFUN
-Define @var{old-macro} as @var{implementation}. The only difference
-with @code{AC_DEFUN} is that the user will be warned that
-@var{old-macro} is now obsolete.
+Don't use multiple regexps with @option{-e}, as some @code{grep} will only
+honor the last pattern (eg., IRIX 6.5 and Solaris 2.5.1). Anyway,
+Stardent Vistra SVR4 @code{grep} lacks @option{-e}@dots{} Instead, use
+alternation and @code{egrep}.
-If she then uses @code{autoupdate}, the call to @var{old-macro} will be
-replaced by the modern @var{implementation}. The additional
-@var{message} is then printed.
-@end defmac
-@node Coding Style, , Obsoleting Macros, Writing Macros
-@section Coding Style
+@item @command{ln}
+@c ---------------
+@cindex @command{ln}
+@cindex Symbolic links
+Don't rely on @command{ln} having a @option{-f} option. Symbolic links
+are not available on old systems, use @samp{ln} as a fall back.
-The Autoconf macros follow a strict coding style. You are encouraged to
-follow this style, especially if you intend to distribute your macro,
-either by contributing it to Autoconf itself, or via other means.
+For versions of the DJGPP before 2.04, @command{ln} emulates soft links
+for executables by generating a stub that in turn calls the real
+program. This feature also works with nonexistent files like in the
+Unix spec. So @samp{ln -s file link} will generate @file{link.exe},
+which will attempt to call @file{file.exe} if run. But this feature only
+works for executables, so @samp{cp -p} is used instead for these
+systems. DJGPP versions 2.04 and later have full symlink support.
+
+
+@item @command{mv}
+@c ---------------
+@cindex @command{mv}
+The only portable options are @option{-f} and @option{-i}.
-The first requirement is to pay great attention to the quotation, for
-more details, see @ref{Autoconf Language}, and @ref{Quoting}.
+Moving individual files between file systems is portable (it was in V6),
+but it is not always atomic: when doing @samp{mv new existing}, there's
+a critical section where neither the old nor the new version of
+@file{existing} actually exists.
-Do not try to invent new interfaces. It is likely that there is a macro
-in Autoconf that resembles the macro you are defining: try to stick to
-this existing interface (order of arguments, default values, etc.). We
-@emph{are} conscious that some of these interfaces are not perfect;
-nevertheless, when harmless, homogeneity should be preferred over
-creativity.
+Moving directories across mount points is not portable, use @command{cp}
+and @command{rm}.
-Be careful about clashes both between M4 symbols and between shell
-variables.
-If you stick to the suggested M4 naming scheme (@pxref{Macro Names}),
-you are unlikely to generate conflicts. Nevertheless, when you need to
-set a special value, @emph{avoid using a regular macro name}; rather,
-use an ``impossible'' name. For instance, up to version 2.13, the macro
-@code{AC_SUBST} used to remember what @var{symbol}s were already defined
-by setting @code{AC_SUBST_@var{symbol}}, which is a regular macro name.
-But since there is a macro named @code{AC_SUBST_FILE}, it was just
-impossible to @samp{AC_SUBST(FILE)}! In this case,
-@code{AC_SUBST(@var{symbol})} or @code{_AC_SUBST(@var{symbol})} should
-have been used (yes, with the parentheses)@dots{}or better yet, high-level
-macros such as @code{AC_EXPAND_ONCE}.
+@item @command{sed}
+@c ----------------
+@cindex @command{sed}
+Patterns should not include the separator (unless escaped), even as part
+of a character class. In conformance with @sc{posix}, the Cray
+@command{sed} will reject @samp{s/[^/]*$//}: use @samp{s,[^/]*$,,}.
-No Autoconf macro should ever enter the user-variable name space; i.e.,
-except for the variables that are the actual result of running the
-macro, all shell variables should start with @code{ac_}. In
-addition, small macros or any macro that is likely to be embedded in
-other macros should be careful not to use obvious names.
+Sed scripts should not use branch labels longer than 8 characters and
+should not contain comments.
-@cindex @code{dnl}
-Do not use @code{dnl} to introduce comments: most of the comments you
-are likely to write are either header comments which are not output
-anyway, or comments that should make their way into @file{configure}.
-There are exceptional cases where you do want to comment special M4
-constructs, in which case @code{dnl} is right, but keep in mind that it
-is unlikely.
+Input should have reasonably long lines, since some @command{sed} have
+an input buffer limited to 4000 bytes.
-M4 ignores the leading spaces before each argument, use this feature to
-indent in such a way that arguments are (more or less) aligned with the
-opening parenthesis of the macro being called. For instance, instead of
+Alternation, @samp{\|}, is common but not portable.
+@c FIXME: I know Solaris is guilty, but I don't remember how.
+Anchors (@samp{^} and @samp{$}) inside groups are not portable.
-@example
-AC_CACHE_CHECK(for EMX OS/2 environment,
-ac_cv_emxos2,
-[AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, [return __EMX__;])],
-[ac_cv_emxos2=yes], [ac_cv_emxos2=no])])
-@end example
+Nested groups are extremely portable, but there is at least one
+@command{sed} (System V/68 Base Operating System R3V7.1) that does not
+support it.
-@noindent
-write
+Of course the option @option{-e} is portable, but it is not needed. No
+valid Sed program can start with a dash, so it does not help
+disambiguating. Its sole usefulness is helping enforcing indenting as
+in:
@example
-AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2],
-[AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])],
- [ac_cv_emxos2=yes],
- [ac_cv_emxos2=no])])
+sed -e @var{instruction-1} \
+ -e @var{instruction-2}
@end example
@noindent
-or even
+as opposed to
@example
-AC_CACHE_CHECK([for EMX OS/2 environment],
- [ac_cv_emxos2],
- [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([],
- [return __EMX__;])],
- [ac_cv_emxos2=yes],
- [ac_cv_emxos2=no])])
+sed @var{instruction-1};@var{instruction-2}
@end example
-When using @code{AC_TRY_RUN} or any macro that cannot work when
-cross-compiling, provide a pessimistic value (typically @samp{no}).
+Contrary to yet another urban legend, you may portably use @samp{&} in
+the replacement part of the @code{s} command to mean ``what was
+matched''.
-Feel free to use various tricks to prevent auxiliary tools, such as
-syntax-highlighting editors, from behaving improperly. For instance,
-instead of:
+
+@item @command{sed} (@samp{t})
+@c ---------------------------
+@cindex @command{sed} (@samp{t})
+Some old systems have @command{sed} that ``forget'' to reset their
+@samp{t} flag when starting a new cycle. For instance on @sc{mips
+risc/os}, and on @sc{irix} 5.3, if you run the following @command{sed}
+script (the line numbers are not actual part of the texts):
@example
-patsubst([$1], [$"])
+s/keep me/kept/g # a
+t end # b
+s/.*/deleted/g # c
+: end # d
@end example
@noindent
-use
+on
@example
-patsubst([$1], [$""])
+delete me # 1
+delete me # 2
+keep me # 3
+delete me # 4
@end example
@noindent
-so that Emacsen do not open a endless ``string'' at the first quote.
-For the same reasons, avoid:
+you get
@example
-test $[#] != 0
+deleted
+delete me
+kept
+deleted
@end example
@noindent
-and use:
+instead of
@example
-test $[@@%:@@] != 0
+deleted
+deleted
+kept
+deleted
@end example
-@noindent
-Otherwise, the closing bracket would be hidden inside a @samp{#}-comment,
-breaking the bracket-matching highlighting from Emacsen. Note the
-preferred style to escape from M4: @samp{$[1]}, @samp{$[@@]}, etc. Do
-not escape when it is unneeded. Common examples of useless quotation
-are @samp{[$]$1} (write @samp{$$1}), @samp{[$]var} (use @samp{$var}),
-etc. If you add portability issues to the picture, you'll prefer
-@samp{$@{1+"$[@@]"@}} to @samp{"[$]@@"}, and you'll prefer do something
-better than hacking Autoconf @code{:-)}.
-
-When using @command{sed}, don't use @option{-e} except for indenting
-purpose. With the @code{s} command, the preferred separator is @samp{/}
-unless @samp{/} itself is used in the command, in which case you should
-use @samp{,}.
+Why? When processing 1, a matches, therefore sets the t flag, b jumps to
+d, and the output is produced. When processing line 2, the t flag is
+still set (this is the bug). Line a fails to match, but @command{sed}
+is not supposed to clear the t flag when a substitution fails. Line b
+sees that the flag is set, therefore it clears it, and jumps to d, hence
+you get @samp{delete me} instead of @samp{deleted}. When processing 3 t
+is clear, a matches, so the flag is set, hence b clears the flags and
+jumps. Finally, since the flag is clear, 4 is processed properly.
-@xref{Macro Definitions}, for details on how to define a macro. If a
-macro doesn't use @code{AC_REQUIRE} and it is expected to never be the
-object of an @code{AC_REQUIRE} directive, then use @code{define}. In
-case of doubt, use @code{AC_DEFUN}. All the @code{AC_REQUIRE}
-statements should be at the beginning of the macro, @code{dnl}'ed.
+There are two things one should remind about @samp{t} in @command{sed}.
+Firstly, always remember that @samp{t} jumps if @emph{some} substitution
+succeeded, not only the immediately preceding substitution, therefore,
+always use a fake @samp{t clear; : clear} to reset the t flag where
+indeed.
-You should not rely on the number of arguments: instead of checking
-whether an argument is missing, test that it is not empty. It provides
-both a simpler and a more predictable interface to the user, and saves
-room for further arguments.
+Secondly, you cannot rely on @command{sed} to clear the flag at each new
+cycle.
-Unless the macro is short, try to leave the closing @samp{])} at the
-beginning of a line, followed by a comment that repeats the name of the
-macro being defined. This introduces an additional newline in
-@code{configure}; normally, that is not a problem, but if you want to
-remove it you can use @samp{[]dnl} on the last line. You can similarly
-use @samp{[]dnl} after a macro call to remove its newline. @samp{[]dnl}
-is recommended instead of @samp{dnl} to ensure that M4 does not
-interpret the @samp{dnl} as being attached to the preceding text or
-macro output. For example, instead of:
+One portable implementation of the script above is:
@example
-AC_DEFUN([AC_PATH_X],
-[AC_MSG_CHECKING([for X])
-AC_REQUIRE_CPP()
-@r{# @dots{}omitted@dots{}}
- AC_MSG_RESULT([libraries $x_libraries, headers $x_includes])
-fi])
+t clear
+: clear
+s/keep me/kept/g
+t end
+s/.*/deleted/g
+: end
@end example
-@noindent
-you would write:
+@item @command{touch}
+@c ------------------
+@cindex @command{touch}
+On some old @sc{bsd} systems, @command{touch} or any command that
+results in an empty file does not update the timestamps, so use a
+command like @code{echo} as a workaround.
-@example
-AC_DEFUN([AC_PATH_X],
-[AC_REQUIRE_CPP()[]dnl
-AC_MSG_CHECKING([for X])
-@r{# @dots{}omitted@dots{}}
- AC_MSG_RESULT([libraries $x_libraries, headers $x_includes])
-fi[]dnl
-])# AC_PATH_X
-@end example
+GNU @command{touch} 3.16r (and presumably all before that) fails to work
+on SunOS 4.1.3 when the empty file is on an @sc{nfs}-mounted 4.2 volume.
-If the macro is long, try to split it into logical chunks. Typically,
-macros that check for a bug in a function and prepare its
-@code{AC_LIBOBJ} replacement should have an auxiliary macro to perform
-this setup. Do not hesitate to introduce auxiliary macros to factor
-your code.
+@end table
-In order to highlight the recommended coding style, here is a macro
-written the old way:
-@example
-dnl Check for EMX on OS/2.
-dnl _AC_EMXOS2
-AC_DEFUN(_AC_EMXOS2,
-[AC_CACHE_CHECK(for EMX OS/2 environment, ac_cv_emxos2,
-[AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, return __EMX__;)],
-ac_cv_emxos2=yes, ac_cv_emxos2=no)])
-test "$ac_cv_emxos2" = yes && EMXOS2=yes])
-@end example
+@node Limitations of Make, , Limitations of Usual Tools, Portable Shell
+@section Limitations of Make
+
+Make itself suffers a great number of limitations, only a few of which
+being listed here. First of all, remember that since commands are
+executed by the shell, all its weaknesses are inherited@dots{}
+
+@table @asis
+@item @code{VPATH}
+@cindex @code{VPATH}
+Don't use it! For instance any assignment to @code{VPATH} causes Sun
+@command{make} to only execute the first set of double-colon rules.
+@end table
+
-@noindent
-and the new way:
-@example
-# _AC_EMXOS2
-# ----------
-# Check for EMX on OS/2.
-define([_AC_EMXOS2],
-[AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2],
-[AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])],
- [ac_cv_emxos2=yes],
- [ac_cv_emxos2=no])])
-test "$ac_cv_emxos2" = yes && EMXOS2=yes[]dnl
-])# _AC_EMXOS2
-@end example
@c ================================================== Manual Configuration
-@node Manual Configuration, Site Configuration, Writing Macros, Top
+@node Manual Configuration, Site Configuration, Portable Shell, Top
@chapter Manual Configuration
A few kinds of features can't be guessed automatically by running test
projects / thirdparty / autoconf.git / commitdiff
