Adding upstream version 2.52+20231210.upstream/2.52+20231210

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 11346 insertions, 0 deletions

diff --git a/doc/autoconf.texi b/doc/autoconf.texi
new file mode 100644
index 0000000..2728b2f
--- /dev/null
+++ b/doc/autoconf.texi
@@ -0,0 +1,11346 @@
+\input texinfo @c -*-texinfo-*-
+@c %**start of header
+@setfilename autoconf.info
+@settitle Autoconf
+
+@finalout
+@setchapternewpage odd
+@setcontentsaftertitlepage
+
+@include version.texi
+
+@c A simple macro for optional variables.
+@macro ovar{varname}
+@r{[}@var{\varname\}@r{]}
+@end macro
+
+@c I don't like the way URL are displayed in TeX with @uref.
+@ifhtml
+@macro href{url, title}
+@uref{\url\, \title\}
+@end macro
+@end ifhtml
+@ifnothtml
+@macro href{url, title}
+\title\@footnote{\title\, @url{\url\}.}
+@end macro
+@end ifnothtml
+
+
+@dircategory GNU admin
+@direntry
+* Autoconf: (autoconf).         Create source code configuration scripts
+@end direntry
+
+@dircategory Individual utilities
+@direntry
+* autoscan: (autoconf)autoscan Invocation.
+                                Semi-automatic @file{configure.ac} writing
+* ifnames: (autoconf)ifnames Invocation.
+                                Listing the conditionals in source code
+* autoconf: (autoconf)autoconf Invocation.
+                                How to create configuration scripts
+* autoreconf: (autoconf)autoreconf Invocation.
+                                Remaking multiple @code{configure} scripts
+* configure: (autoconf)configure Invocation.
+                                Configuring a package
+* config.status: (autoconf)config.status Invocation.
+                                Recreating a configuration
+@end direntry
+
+@ifinfo
+Autoconf: Creating Automatic Configuration Scripts, by David MacKenzie.
+
+This file documents the GNU Autoconf package for creating scripts to
+configure source code packages using templates and an @code{m4} macro
+package.
+ 
+Copyright 2003-2022,2023	Thomas E. Dickey@*
+Copyright 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, 2001 Free
+Software Foundation, Inc.
+
+Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+@ignore
+Permission is granted to process this file through TeX and print the
+results, provided the printed document carries copying permission notice
+identical to this one except for the removal of this paragraph (this
+paragraph not being relevant to the printed manual).
+
+@end ignore
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that this permission notice may be stated in a translation
+approved by the Foundation.
+@end ifinfo
+
+@titlepage
+@title Autoconf
+@subtitle Creating Automatic Configuration Scripts
+@subtitle Edition @value{EDITION}, for Autoconf version @value{VERSION}
+@subtitle @value{UPDATED}
+@author David MacKenzie and Ben Elliston
+@c I think I've rewritten all of Noah and Roland's contributions by now.
+
+@page
+@vskip 0pt plus 1filll
+Copyright @copyright{} 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000,
+2001 Free Software Foundation, Inc.
+
+Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that this permission notice may be stated in a translation
+approved by the Foundation.
+@end titlepage
+
+@c Define an environment variable index.
+@defcodeindex ev
+@c Define an output variable index.
+@defcodeindex ov
+@c Define a CPP variable index.
+@defcodeindex cv
+@c Define an Autoconf macro index that @defmac doesn't write to.
+@defcodeindex ma
+@c Define an M4sugar macro index that @defmac doesn't write to.
+@defcodeindex ms
+
+@node Top, Introduction, (dir), (dir)
+@comment  node-name,  next,  previous,  up
+
+@ifinfo
+This file documents the GNU Autoconf package for creating scripts to
+configure source code packages using templates and the GNU M4 macro
+package.  This is edition @value{EDITION}, for Autoconf version
+@value{VERSION}.
+
+@end ifinfo
+
+@c The master menu, created with texinfo-master-menu, goes here.
+
+@menu
+* Introduction::                Autoconf's purpose, strengths, and weaknesses
+* The GNU build system::        A set of tools for portable software packages
+* Making configure Scripts::    How to organize and produce Autoconf scripts
+* Setup::                       Initialization and output
+* Existing Tests::              Macros that check for particular features
+* Writing Tests::               How to write new feature checks
+* Results::                     What to do with results from feature checks
+* Programming in M4::           Layers on top of which Autoconf is written
+* Writing Autoconf 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
+* config.status Invocation::    Recreating a configuration
+* Obsolete Constructs::         Kept for backward compatibility
+* Questions::                   Questions about Autoconf, with answers
+* History::                     History of Autoconf
+* Environment Variable Index::  Index of environment variables used
+* Output Variable Index::       Index of variables set in output files
+* Preprocessor Symbol Index::   Index of C preprocessor symbols defined
+* Autoconf Macro Index::        Index of Autoconf macros
+* M4 Macro Index::              Index of M4, M4sugar, and M4sh macros
+* Concept Index::               General index
+
+@detailmenu --- The Detailed Node Listing ---
+
+The GNU build system
+
+* Automake::                    Escaping Makefile hell
+* Libtool::                     Building libraries portably
+* Pointers::                    More info on the GNU build system
+
+Making @code{configure} Scripts
+
+* Writing configure.ac::        What to put in an Autoconf input file
+* autoscan Invocation::         Semi-automatic @file{configure.ac} writing
+* ifnames Invocation::          Listing the conditionals in source code
+* autoconf Invocation::         How to create configuration scripts
+* autoreconf Invocation::       Remaking multiple @code{configure} scripts
+
+Writing @file{configure.ac}
+
+* Shell Script Compiler::       Autoconf as solution of a problem
+* Autoconf Language::           Programming in Autoconf
+* configure.ac Layout::         Standard organization of configure.ac
+
+Initialization and Output Files
+
+* Notices::                     Copyright, version numbers in @code{configure}
+* Input::                       Where Autoconf should find files
+* Output::                      Outputting results from the configuration
+* Configuration Actions::       Preparing the output based on results
+* Configuration Files::         Creating output files
+* Makefile Substitutions::      Using output variables in @file{Makefile}s
+* Configuration Headers::       Creating a configuration header file
+* Configuration Commands::      Running arbitrary instantiation commands
+* Configuration Links::         Links depending from the configuration
+* Subdirectories::              Configuring independent packages together
+* Default Prefix::              Changing the default installation prefix
+
+Substitutions in Makefiles
+
+* Preset Output Variables::     Output variables that are always set
+* Installation Directory Variables::  Other preset output variables
+* Build Directories::           Supporting multiple concurrent compiles
+* Automatic Remaking::          Makefile rules for configuring
+
+Configuration Header Files
+
+* Header Templates::            Input for the configuration headers
+* autoheader Invocation::       How to create configuration templates
+* Autoheader Macros::           How to specify CPP templates
+
+Existing Tests
+
+* Common Behavior::             Macros' standard schemes
+* Alternative Programs::        Selecting between alternative programs
+* Files::                       Checking for the existence of files
+* Libraries::                   Library archives that might be missing
+* Library Functions::           C library functions that might be missing
+* Header Files::                Header files that might be missing
+* Declarations::                Declarations that may be missing
+* Structures::                  Structures or members that might be missing
+* Types::                       Types that might be missing
+* Compilers and Preprocessors::  Checking for compiling programs
+* System Services::             Operating system services
+* UNIX Variants::               Special kludges for specific UNIX variants
+
+Common Behavior
+
+* Standard Symbols::            Symbols defined by the macros
+* Default Includes::            Includes used by the generic macros
+
+Alternative Programs
+
+* Particular Programs::         Special handling to find certain programs
+* Generic Programs::            How to find other programs
+
+Library Functions
+
+* Function Portability::        Pitfalls with usual functions
+* Particular Functions::        Special handling to find certain functions
+* Generic Functions::           How to find other functions
+
+Header Files
+
+* Particular Headers::          Special handling to find certain headers
+* Generic Headers::             How to find other headers
+
+Declarations
+
+* Particular Declarations::     Macros to check for certain declarations
+* Generic Declarations::        How to find other declarations
+
+Structures
+
+* Particular Structures::       Macros to check for certain structure members
+* Generic Structures::          How to find other structure members
+
+Types
+
+* Particular Types::            Special handling to find certain types
+* Generic Types::               How to find other types
+
+Compilers and Preprocessors
+
+* Generic Compiler Characteristics::  Language independent tests
+* C Compiler::                  Checking its characteristics
+* C++ Compiler::                Likewise
+* Fortran 77 Compiler::         Likewise
+
+Writing Tests
+
+* Examining Declarations::      Detecting header files and declarations
+* Examining Syntax::            Detecting language syntax features
+* Examining Libraries::         Detecting functions and global variables
+* Run Time::                    Testing for run-time features
+* Systemology::                 A zoology of operating systems
+* Multiple Cases::              Tests for several possible values
+* Language Choice::             Selecting which language to use for testing
+
+Checking Run Time Behavior
+
+* Test Programs::               Running test programs
+* Guidelines::                  General rules for writing test programs
+* Test Functions::              Avoiding pitfalls in test programs
+
+Results of Tests
+
+* 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
+
+Caching Results
+
+* Cache Variable Names::        Shell variables used in caches
+* Cache Files::                 Files @code{configure} uses for caching
+* Cache Checkpointing::         Loading and saving the cache file
+
+Programming in M4
+
+* M4 Quotation::                Protecting macros from unwanted expansion
+* Programming in M4sugar::      Convenient pure M4 macros
+
+M4 Quotation
+
+* Active Characters::           Characters that change the behavior of m4
+* One Macro Call::              Quotation and one macro call
+* Quotation and Nested Macros::  Macros calling macros
+* Quadrigraphs::                Another way to escape special characters
+* Quotation Rule Of Thumb::     One parenthesis, one quote
+
+Programming in M4sugar
+
+* Redefined M4 Macros::         M4 builtins changed in M4sugar
+* Forbidden Patterns::          Catching unexpanded macros
+
+Writing Autoconf Macros
+
+* Macro Definitions::           Basic format of an Autoconf macro
+* Macro Names::                 What to call your new macros
+* 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
+
+Dependencies Between Macros
+
+* 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
+* Canonicalizing::              Getting the canonical system type
+* Using System Type::           What to do with the system type
+
+Site Configuration
+
+* External Software::           Working with other optional software
+* Package Options::             Selecting optional features
+* Pretty Help Strings::         Formatting help string
+* Site Details::                Configuring site details
+* Transforming Names::          Changing program names when installing
+* Site Defaults::               Giving @code{configure} local defaults
+
+Transforming Program Names When Installing
+
+* Transformation Options::      @code{configure} options to transform names
+* Transformation Examples::     Sample uses of transforming names
+* Transformation Rules::        @file{Makefile} uses of transforming names
+
+Running @code{configure} Scripts
+
+* Basic Installation::          Instructions for typical cases
+* Compilers and Options::       Selecting compilers and optimization
+* Multiple Architectures::      Compiling for multiple architectures at once
+* Installation Names::          Installing in different directories
+* Optional Features::           Selecting optional features
+* System Type::                 Specifying the system type
+* Sharing Defaults::            Setting site-wide defaults for @code{configure}
+* Environment Variables::       Defining environment variables.
+* configure Invocation::        Changing how @code{configure} runs
+
+Obsolete Constructs
+
+* Obsolete config.status Use::  Different calling convention
+* acconfig.h::                  Additional entries in @file{config.h.in}
+* autoupdate Invocation::       Automatic update of @file{configure.ac}
+* Obsolete Macros::             Backward compatibility macros
+* Autoconf 1::                  Tips for upgrading your files
+* Autoconf 2.13::               Some fresher tips
+
+Upgrading From Version 1
+
+* Changed File Names::          Files you might rename
+* Changed Makefiles::           New things to put in @file{Makefile.in}
+* Changed Macros::              Macro calls you might replace
+* Changed Results::             Changes in how to check test results
+* Changed Macro Writing::       Better ways to write your own macros
+
+Upgrading From Version 2.13
+
+* Changed Quotation::           Broken code which used to work
+* New Macros::                  Interaction with foreign macros
+
+Questions About Autoconf
+
+* Distributing::                Distributing @code{configure} scripts
+* Why GNU m4::                  Why not use the standard M4?
+* Bootstrapping::               Autoconf and GNU M4 require each other?
+* Why Not Imake::               Why GNU uses @code{configure} instead of Imake
+
+History of Autoconf
+
+* Genesis::                     Prehistory and naming of @code{configure}
+* Exodus::                      The plagues of M4 and Perl
+* Leviticus::                   The priestly code of portability arrives
+* Numbers::                     Growth and contributors
+* Deuteronomy::                 Approaching the promises of easy configuration
+
+@end detailmenu
+@end menu
+
+@c ============================================================= Introduction.
+
+@node Introduction, The GNU build system, Top, Top
+@chapter Introduction
+
+@flushright
+A physicist, an engineer, and a computer scientist were discussing the
+nature of God.  ``Surely a Physicist,'' said the physicist, ``because
+early in the Creation, God made Light; and you know, Maxwell's
+equations, the dual nature of electromagnetic waves, the relativistic
+consequences@dots{}'' ``An Engineer!,'' said the engineer, ``because
+before making Light, God split the Chaos into Land and Water; it takes a
+hell of an engineer to handle that big amount of mud, and orderly
+separation of solids from liquids@dots{}'' The computer scientist
+shouted: ``And the Chaos, where do you think it was coming from, hmm?''
+
+---Anonymous
+@end flushright
+@c (via Franc,ois Pinard)
+
+Autoconf is a tool for producing shell scripts that automatically
+configure software source code packages to adapt to many kinds of
+@sc{unix}-like systems.  The configuration scripts produced by Autoconf
+are independent of Autoconf when they are run, so their users do not
+need to have Autoconf.
+
+The configuration scripts produced by Autoconf require no manual user
+intervention when run; they do not normally even need an argument
+specifying the system type.  Instead, they individually test for the
+presence of each feature that the software package they are for might need.
+(Before each check, they print a one-line message stating what they are
+checking for, so the user doesn't get too bored while waiting for the
+script to finish.)  As a result, they deal well with systems that are
+hybrids or customized from the more common @sc{unix} variants.  There is
+no need to maintain files that list the features supported by each
+release of each variant of @sc{unix}.
+
+For each software package that Autoconf is used with, it creates a
+configuration script from a template file that lists the system features
+that the package needs or can use.  After the shell code to recognize
+and respond to a system feature has been written, Autoconf allows it to
+be shared by many software packages that can use (or need) that feature.
+If it later turns out that the shell code needs adjustment for some
+reason, it needs to be changed in only one place; all of the
+configuration scripts can be regenerated automatically to take advantage
+of the updated code.
+
+The Metaconfig package is similar in purpose to Autoconf, but the
+scripts it produces require manual user intervention, which is quite
+inconvenient when configuring large source trees.  Unlike Metaconfig
+scripts, Autoconf scripts can support cross-compiling, if some care is
+taken in writing them.
+
+Autoconf does not solve all problems related to making portable software
+packages---for a more complete solution, it should be used in concert
+with other GNU build tools like Automake and Libtool.  These other tools
+take on jobs like the creation of a portable, recursive @file{Makefile}
+with all of the standard targets, linking of shared libraries, and so
+on.  @xref{The GNU build system}, for more information.
+
+Autoconf imposes some restrictions on the names of macros used with
+@code{#if} in C programs (@pxref{Preprocessor Symbol Index}).
+
+Autoconf requires @sc{gnu} M4 in order to generate the scripts.  It uses
+features that some @sc{unix} versions of M4, including @sc{gnu} M4 1.3,
+do not have.  You must use version 1.4 or later of @sc{gnu} M4.
+
+@xref{Autoconf 1}, for information about upgrading from version 1.
+@xref{History}, for the story of Autoconf's development.
+@xref{Questions}, for answers to some common questions about Autoconf.
+
+
+See the @href{http://www.gnu.org/software/autoconf/autoconf.html,
+Autoconf web page} for up-to-date information, details on the mailing
+lists, pointers to a list of known bugs, etc.
+
+Mail suggestions to @email{autoconf@@gnu.org, the Autoconf mailing
+list}.
+
+Bug reports should be preferably submitted to the
+@href{http://sources.redhat.com/cgi-bin/gnatsweb.pl?database=autoconf,
+Autoconf Gnats database}, or sent to @email{bug-autoconf@@gnu.org, the
+Autoconf Bugs mailing list}.  If possible, first check that your bug is
+not already solved in current development versions, and that it has not
+been reported yet.  Be sure to include all the needed information and a
+short @file{configure.ac} that demonstrates the problem.
+
+Autoconf's development tree is accessible via @sc{cvs}; see the Autoconf
+web page for details.  There is also a
+@href{http://subversions.gnu.org/cgi-bin/cvsweb/autoconf/, @sc{cvs}web
+interface to the Autoconf development tree}.  Patches relative to the
+current @sc{cvs} version can be sent for review to the
+@email{autoconf-patches@@gnu.org, Autoconf Patches mailing list}.
+
+Because of its mission, Autoconf includes only a set of often-used
+macros that have already demonstrated their usefulness.  Nevertheless,
+if you wish to share your macros, or find existing ones, see the
+@href{http://www.gnu.org/software/ac-archive/, Autoconf Macro
+Archive}, which is kindly run by @email{simons@@computer.org,
+Peter Simons}.
+
+
+@c ================================================= The GNU build system
+
+@node The GNU build system, Making configure Scripts, Introduction, Top
+@chapter The GNU build system
+
+Autoconf solves an important problem---reliable discovery of
+system-specific build and runtime information---but this is only one
+piece of the puzzle for the development of portable software.  To this
+end, the GNU project has developed a suite of integrated utilities to
+finish the job Autoconf started: the GNU build system, whose most
+important components are Autoconf, Automake, and Libtool.  In this
+chapter, we introduce you to those tools, point you to sources of more
+information, and try to convince you to use the entire GNU build system
+for your software.
+
+@menu
+* Automake::                    Escaping Makefile hell
+* Libtool::                     Building libraries portably
+* Pointers::                    More info on the GNU build system
+@end menu
+
+@node Automake, Libtool, The GNU build system, The GNU build system
+@section Automake
+
+The ubiquity of @code{make} means that a @code{Makefile} is almost the
+only viable way to distribute automatic build rules for software, but
+one quickly runs into @code{make}'s numerous limitations.  Its lack of
+support for automatic dependency tracking, recursive builds in
+subdirectories, reliable timestamps (e.g. for network filesystems), and
+so on, mean that developers must painfully (and often incorrectly)
+reinvent the wheel for each project.  Portability is non-trivial, thanks
+to the quirks of @code{make} on many systems.  On top of all this is the
+manual labor required to implement the many standard targets that users
+have come to expect (@code{make install}, @code{make distclean},
+@code{make uninstall}, etc.).  Since you are, of course, using Autoconf,
+you also have to insert repetitive code in your @code{Makefile.in} to
+recognize @code{@@CC@@}, @code{@@CFLAGS@@}, and other substitutions
+provided by @code{configure}.  Into this mess steps @dfn{Automake}.
+@cindex Automake
+
+Automake allows you to specify your build needs in a @code{Makefile.am}
+file with a vastly simpler and more powerful syntax than that of a plain
+@code{Makefile}, and then generates a portable @code{Makefile.in} for
+use with Autoconf.  For example, the @code{Makefile.am} to build and
+install a simple ``Hello world'' program might look like:
+
+@example
+bin_PROGRAMS = hello
+hello_SOURCES = hello.c
+@end example
+
+@noindent
+The resulting @code{Makefile.in} (~400 lines) automatically supports all
+the standard targets, the substitutions provided by Autoconf, automatic
+dependency tracking, @code{VPATH} building, and so on.  @code{make} will
+build the @code{hello} program, and @code{make install} will install it
+in @file{/usr/local/bin} (or whatever prefix was given to
+@code{configure}, if not @file{/usr/local}).
+
+Automake may require that additional tools be present on the
+@emph{developer's} machine.  For example, the @code{Makefile.in} that
+the developer works with may not be portable (e.g. it might use special
+features of your compiler to automatically generate dependency
+information).  Running @code{make dist}, however, produces a
+@file{hello-1.0.tar.gz} package (or whatever the program/version is)
+with a @code{Makefile.in} that will work on any system.
+
+The benefits of Automake increase for larger packages (especially ones
+with subdirectories), but even for small programs the added convenience
+and portability can be substantial.  And that's not all@dots{}
+
+@node Libtool, Pointers, Automake, The GNU build system
+@section Libtool
+
+Very often, one wants to build not only programs, but libraries, so that
+other programs can benefit from the fruits of your labor.  Ideally, one
+would like to produce @emph{shared} (dynamically-linked) libraries,
+which can be used by multiple programs without duplication on disk or in
+memory and can be updated independently of the linked programs.
+Producing shared libraries portably, however, is the stuff of
+nightmares---each system has its own incompatible tools, compiler flags,
+and magic incantations.  Fortunately, GNU provides a solution:
+@dfn{Libtool}.
+@cindex Libtool
+
+Libtool handles all the requirements of building shared libraries for
+you, and at this time seems to be the @emph{only} way to do so with any
+portability.  It also handles many other headaches, such as: the
+interaction of @code{Makefile} rules with the variable suffixes of
+shared libraries, linking reliably to shared libraries before they are
+installed by the superuser, and supplying a consistent versioning system
+(so that different versions of a library can be installed or upgraded
+without breaking binary compatibility).  Although Libtool, like
+Autoconf, can be used on its own, it is most simply utilized in
+conjunction with Automake---there, Libtool is used automatically
+whenever shared libraries are needed, and you need not know its syntax.
+
+@node Pointers,  , Libtool, The GNU build system
+@section Pointers
+
+Developers who are used to the simplicity of @code{make} for small
+projects on a single system might be daunted at the prospect of learning
+to use Automake and Autoconf.  As your software is distributed to more
+and more users, however, you will otherwise quickly find yourself
+putting lots of effort into reinventing the services that the GNU build
+tools provide, and making the same mistakes that they once made and
+overcame.  (Besides, since you're already learning Autoconf, Automake
+will be a piece of cake.)
+
+There are a number of places that you can go to for more information on
+the GNU build tools.
+
+@itemize @minus
+
+@item Web
+
+The home pages for
+@href{http://www.gnu.org/software/autoconf/,Autoconf}, and
+@href{http://www.gnu.org/software/libtool/,Libtool}.
+
+@item Books
+
+The book @cite{GNU Autoconf, Automake and Libtool}@footnote{@cite{GNU
+Autoconf, Automake and Libtool}, by G. V. Vaughan, B. Elliston,
+T. Tromey, and I. L. Taylor. New Riders, 2000, ISBN 1578701902.}
+describes the complete GNU build environment.  You can also find the
+entire book on-line at @href{http://sources.redhat.com/autobook/,``The
+Goat Book'' home page}.
+
+@item Tutorials and Examples
+
+The @href{http://sources.redhat.com/autoconf/,Autoconf Developer Page}
+maintains links to a number of Autoconf/Automake tutorials online, and
+also links to the @href{http://www.gnu.org/software/ac-archive/,
+Autoconf Macro Archive}.
+
+@end itemize
+
+@c ================================================= Making configure Scripts.
+
+@node Making configure Scripts, Setup, The GNU build system, Top
+@chapter Making @code{configure} Scripts
+@cindex @file{aclocal.m4}
+@cindex @code{configure}
+
+The configuration scripts that Autoconf produces are by convention
+called @code{configure}.  When run, @code{configure} creates several
+files, replacing configuration parameters in them with appropriate
+values.  The files that @code{configure} creates are:
+
+@itemize @minus
+@item
+one or more @file{Makefile} files, one in each subdirectory of the
+package (@pxref{Makefile Substitutions});
+
+@item
+optionally, a C header file, the name of which is configurable,
+containing @code{#define} directives (@pxref{Configuration Headers});
+
+@item
+a shell script called @file{config.status} that, when run, will recreate
+the files listed above (@pxref{config.status Invocation});
+
+@item
+an optional shell script normally called @file{config.cache}
+(created when using @samp{configure --config-cache}) that
+saves the results of running many of the tests (@pxref{Cache Files});
+
+@item
+a file called @file{config.log} containing any messages produced by
+compilers, to help debugging if @code{configure} makes a mistake.
+@end itemize
+
+@cindex @file{configure.in}
+@cindex @file{configure.ac}
+To create a @code{configure} script with Autoconf, you need to write an
+Autoconf input file @file{configure.ac} (or @file{configure.in}) and run
+@code{autoconf} on it.  If you write your own feature tests to
+supplement those that come with Autoconf, you might also write files
+called @file{aclocal.m4} and @file{acsite.m4}.  If you use a C header
+file to contain @code{#define} directives, you might also run
+@code{autoheader}, and you will distribute the generated file
+@file{config.h.in} with the package.
+
+Here is a diagram showing how the files that can be used in
+configuration are produced.  Programs that are executed are suffixed by
+@samp{*}.  Optional files are enclosed in square brackets (@samp{[]}).
+@code{autoconf} and @code{autoheader} also read the installed Autoconf
+macro files (by reading @file{autoconf.m4}).
+
+@noindent
+Files used in preparing a software package for distribution:
+@example
+your source files --> [autoscan*] --> [configure.scan] --> configure.ac
+
+@group
+configure.ac --.
+               |   .------> autoconf* -----> configure
+[aclocal.m4] --+---+
+               |   `-----> [autoheader*] --> [config.h.in]
+[acsite.m4] ---'
+@end group
+
+Makefile.in -------------------------------> Makefile.in
+@end example
+
+@noindent
+Files used in configuring a software package:
+@example
+@group
+                       .-------------> [config.cache]
+configure* ------------+-------------> config.log
+                       |
+[config.h.in] -.       v            .-> [config.h] -.
+               +--> config.status* -+               +--> make*
+Makefile.in ---'                    `-> Makefile ---'
+@end group
+@end example
+
+@menu
+* Writing configure.ac::        What to put in an Autoconf input file
+* autoscan Invocation::         Semi-automatic @file{configure.ac} writing
+* ifnames Invocation::          Listing the conditionals in source code
+* autoconf Invocation::         How to create configuration scripts
+* autoreconf Invocation::       Remaking multiple @code{configure} scripts
+@end menu
+
+@node Writing configure.ac, autoscan Invocation, Making configure Scripts, Making configure Scripts
+@section Writing @file{configure.ac}
+
+To produce a @code{configure} script for a software package, create a
+file called @file{configure.ac} that contains invocations of the
+Autoconf macros that test the system features your package needs or can
+use.  Autoconf macros already exist to check for many features; see
+@ref{Existing Tests}, for their descriptions.  For most other features,
+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; 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
+described by its extension), and introduces a slight confusion with
+@file{config.h.in} and so on (for which @samp{.in} means ``to be
+processed by @code{configure}'').  Using @file{configure.ac} is now
+preferred.
+
+@menu
+* Shell Script Compiler::       Autoconf as solution of a problem
+* Autoconf Language::           Programming in Autoconf
+* configure.ac Layout::         Standard organization of configure.ac
+@end menu
+
+@node Shell Script Compiler, Autoconf Language, Writing configure.ac, Writing configure.ac
+@subsection A Shell Script Compiler
+
+Just as for any other computer language, in order to properly program
+@file{configure.ac} in Autoconf you must understand @emph{what} problem
+the language tries to address and @emph{how} it does so.
+
+The problem Autoconf addresses is that the world is a mess.  After all,
+you are using Autoconf in order to have your package compile easily on
+all sorts of different systems, some of them being extremely hostile.
+Autoconf itself bears the price for these differences: @code{configure}
+must run on all those systems, and thus @code{configure} must limit itself
+to their lowest common denominator of features.
+
+Naturally, you might then think of shell scripts; who needs
+@code{autoconf}?  A set of properly written shell functions is enough to
+make it easy to write @code{configure} scripts by hand.  Sigh!
+Unfortunately, shell functions do not belong to the least common
+denominator; therefore, where you would like to define a function and
+use it ten times, you would instead need to copy its body ten times.
+
+So, what is really needed is some kind of compiler, @code{autoconf},
+that takes an Autoconf program, @file{configure.ac}, and transforms it
+into a portable shell script, @code{configure}.
+
+How does @code{autoconf} perform this task?
+
+There are two obvious possibilities: creating a brand new language or
+extending an existing one.  The former option is very attractive: all
+sorts of optimizations could easily be implemented in the compiler and
+many rigorous checks could be performed on the Autoconf program
+(e.g. rejecting any non-portable construct).  Alternatively, you can
+extend an existing language, such as the @code{sh} (Bourne shell)
+language.
+
+Autoconf does the latter: it is a layer on top of @code{sh}.  It was
+therefore most convenient to implement @code{autoconf} as a macro
+expander: a program that repeatedly performs @dfn{macro expansions} on
+text input, replacing macro calls with macro bodies and producing a pure
+@code{sh} script in the end.  Instead of implementing a dedicated
+Autoconf macro expander, it is natural to use an existing
+general-purpose macro language, such as M4, and implement the extensions
+as a set of M4 macros.
+
+
+@node Autoconf Language, configure.ac Layout, Shell Script Compiler, Writing configure.ac
+@subsection The Autoconf Language
+@cindex quotation
+
+The Autoconf language is very different from many other computer
+languages because it treats actual code the same as plain text.  Whereas
+in C, for instance, data and instructions have very different syntactic
+status, in Autoconf their status is rigorously the same.  Therefore, we
+need a means to distinguish literal strings from text to be expanded:
+quotation.
+
+When calling macros that take arguments, there must not be any blank
+space between the macro name and the open parenthesis.  Arguments should
+be enclosed within the M4 quote characters @samp{[} and @samp{]}, and be
+separated by commas.  Any leading spaces in arguments are ignored,
+unless they are quoted.  You may safely leave out the quotes when the
+argument is simple text, but @emph{always} quote complex arguments such
+as other macro calls.  This rule applies recursively for every macro
+call, including macros called from other macros.
+
+For instance:
+
+@example
+AC_CHECK_HEADER([stdio.h],
+                [AC_DEFINE([HAVE_STDIO_H])],
+                [AC_MSG_ERROR([Sorry, can't do anything for you])])
+@end example
+
+@noindent
+is quoted properly.  You may safely simplify its quotation to:
+
+@example
+AC_CHECK_HEADER(stdio.h,
+                [AC_DEFINE(HAVE_STDIO_H)],
+                [AC_MSG_ERROR([Sorry, can't do anything for you])])
+@end example
+
+@noindent
+Notice that the argument of @code{AC_MSG_ERROR} is still quoted;
+otherwise, its comma would have been interpreted as an argument separator.
+
+The following example is wrong and dangerous, as it is underquoted:
+
+@example
+AC_CHECK_HEADER(stdio.h,
+                AC_DEFINE(HAVE_STDIO_H),
+                AC_MSG_ERROR([Sorry, can't do anything for you]))
+@end example
+
+In other cases, you may have to use text that also resembles a macro
+call.  You must quote that text even when it is not passed as a macro
+argument:
+
+@example
+echo "Hard rock was here!  --[AC_DC]"
+@end example
+
+@noindent
+which will result in
+
+@example
+echo "Hard rock was here!  --AC_DC"
+@end example
+
+@noindent
+When you use the same text in a macro argument, you must therefore have
+an extra quotation level (since one is stripped away by the macro
+substitution).  In general, then, it is a good idea to @emph{use double
+quoting for all literal string arguments}:
+
+@example
+AC_MSG_WARN([[AC_DC stinks  --Iron Maiden]])
+@end example
+
+You are now able to understand one of the constructs of Autoconf that
+has been continually misunderstood@dots{}  The rule of thumb is that
+@emph{whenever you expect macro expansion, expect quote expansion};
+i.e., expect one level of quotes to be lost.  For instance:
+
+@example
+AC_COMPILE_IFELSE([char b[10];],, [AC_MSG_ERROR([you lose])])
+@end example
+
+@noindent
+is incorrect: here, the first argument of @code{AC_COMPILE_IFELSE} is
+@samp{char b[10];} and will be expanded once, which results in
+@samp{char b10;}.  (There was an idiom common in Autoconf's past to
+address this issue via the M4 @code{changequote} primitive, but do not
+use it!)  Let's take a closer look: the author meant the first argument
+to be understood as a literal, and therefore it must be quoted twice:
+
+@example
+AC_COMPILE_IFELSE([[char b[10];]],, [AC_MSG_ERROR([you lose])])
+@end example
+
+@noindent
+Voil@`a, you actually produce @samp{char b[10];} this time!
+
+The careful reader will notice that, according to these guidelines, the
+``properly'' quoted @code{AC_CHECK_HEADER} example above is actually
+lacking three pairs of quotes!  Nevertheless, for the sake of readability,
+double quotation of literals is used only where needed in this manual.
+
+Some macros take optional arguments, which this documentation represents
+as @ovar{arg} (not to be confused with the quote characters).  You may
+just leave them empty, or use @samp{[]} to make the emptiness of the
+argument explicit, or you may simply omit the trailing commas.  The
+three lines below are equivalent:
+
+@example
+AC_CHECK_HEADERS(stdio.h, [], [], [])
+AC_CHECK_HEADERS(stdio.h,,,)
+AC_CHECK_HEADERS(stdio.h)
+@end example
+
+It is best to put each macro call on its own line in
+@file{configure.ac}.  Most of the macros don't add extra newlines; they
+rely on the newline after the macro call to terminate the commands.
+This approach makes the generated @code{configure} script a little
+easier to read by not inserting lots of blank lines.  It is generally
+safe to set shell variables on the same line as a macro call, because
+the shell allows assignments without intervening newlines.
+
+You can include comments in @file{configure.ac} files by starting them
+with the @samp{#}.  For example, it is helpful to begin
+@file{configure.ac} files with a line like this:
+
+@example
+# Process this file with autoconf to produce a configure script.
+@end example
+
+@node configure.ac Layout,  , Autoconf Language, Writing configure.ac
+@subsection Standard @file{configure.ac} Layout
+
+The order in which @file{configure.ac} calls the Autoconf macros is not
+important, with a few exceptions.  Every @file{configure.ac} must
+contain a call to @code{AC_INIT} before the checks, and a call to
+@code{AC_OUTPUT} at the end (@pxref{Output}).  Additionally, some macros
+rely on other macros having been called first, because they check
+previously set values of some variables to decide what to do.  These
+macros are noted in the individual descriptions (@pxref{Existing
+Tests}), and they also warn you when @code{configure} is created if they
+are called out of order.
+
+To encourage consistency, here is a suggested order for calling the
+Autoconf macros.  Generally speaking, the things near the end of this
+list are those that could depend on things earlier in it.  For example,
+library functions could be affected by types and libraries.
+
+@display
+@group
+Autoconf requirements
+@code{AC_INIT(@var{package}, @var{version}, @var{bug-report-address})}
+information on the package
+checks for programs
+checks for libraries
+checks for header files
+checks for types
+checks for structures
+checks for compiler characteristics
+checks for library functions
+checks for system services
+@code{AC_CONFIG_FILES(@r{[}@var{file@dots{}}@r{]})}
+@code{AC_OUTPUT}
+@end group
+@end display
+
+
+@node autoscan Invocation, ifnames Invocation, Writing configure.ac, Making configure Scripts
+@section Using @code{autoscan} to Create @file{configure.ac}
+@cindex @code{autoscan}
+
+The @code{autoscan} program can help you create and/or maintain a
+@file{configure.ac} file for a software package.  @code{autoscan}
+examines source files in the directory tree rooted at a directory given
+as a command line argument, or the current directory if none is given.
+It searches the source files for common portability problems and creates
+a file @file{configure.scan} which is a preliminary @file{configure.ac}
+for that package, and checks a possibly existing @file{configure.ac} for
+completeness.
+
+When using @command{autoscan} to create a @file{configure.ac}, you
+should manually examine @file{configure.scan} before renaming it to
+@file{configure.ac}; it will probably need some adjustments.
+Occasionally, @code{autoscan} outputs a macro in the wrong order
+relative to another macro, so that @code{autoconf} produces a warning;
+you need to move such macros manually.  Also, if you want the package to
+use a configuration header file, you must add a call to
+@code{AC_CONFIG_HEADERS} (@pxref{Configuration Headers}).  You might
+also have to change or add some @code{#if} directives to your program in
+order to make it work with Autoconf (@pxref{ifnames Invocation}, for
+information about a program that can help with that job).
+
+When using @command{autoscan} to maintain a @file{configure.ac}, simply
+consider adding its suggestions.  The file @file{autoscan.log} will
+contain detailed information on why a macro is requested.
+
+@code{autoscan} uses several data files (installed along with Autoconf)
+to determine which macros to output when it finds particular symbols in
+a package's source files.  These data files all have the same format:
+each line consists of a symbol, whitespace, and the Autoconf macro to
+output if that symbol is encountered.  Lines starting with @samp{#} are
+comments.
+
+@code{autoscan} is only installed if you already have Perl installed.
+@code{autoscan} accepts the following options:
+
+@table @option
+@item --help
+@itemx -h
+Print a summary of the command line options and exit.
+
+@item --version
+@itemx -V
+Print the version number of Autoconf and exit.
+
+@item --verbose
+@itemx -v
+Print the names of the files it examines and the potentially interesting
+symbols it finds in them.  This output can be voluminous.
+
+@item --autoconf-dir=@var{dir}
+@itemx -A @var{dir}
+@evindex AC_MACRODIR
+Override the location where the installed Autoconf data files are looked
+for.  You can also set the @code{AC_MACRODIR} environment variable to a
+directory; this option overrides the environment variable.
+
+This option is rarely needed and dangerous; it is only used when one
+plays with different versions of Autoconf simultaneously.
+@end table
+
+@node ifnames Invocation, autoconf Invocation, autoscan Invocation, Making configure Scripts
+@section Using @code{ifnames} to List Conditionals
+@cindex @code{ifnames}
+
+@code{ifnames} can help you write @file{configure.ac} for a software
+package.  It prints the identifiers that the package already uses in C
+preprocessor conditionals.  If a package has already been set up to have
+some portability, @code{ifnames} can thus help you figure out what its
+@code{configure} needs to check for.  It may help fill in some gaps in a
+@file{configure.ac} generated by @code{autoscan} (@pxref{autoscan
+Invocation}).
+
+@code{ifnames} scans all of the C source files named on the command line
+(or the standard input, if none are given) and writes to the standard
+output a sorted list of all the identifiers that appear in those files
+in @code{#if}, @code{#elif}, @code{#ifdef}, or @code{#ifndef}
+directives.  It prints each identifier on a line, followed by a
+space-separated list of the files in which that identifier occurs.
+
+@noindent
+@code{ifnames} accepts the following options:
+
+@table @option
+@item --help
+@itemx -h
+Print a summary of the command line options and exit.
+
+@item --version
+@itemx -V
+Print the version number of Autoconf and exit.
+@end table
+
+@node autoconf Invocation, autoreconf Invocation, ifnames Invocation, Making configure Scripts
+@section Using @code{autoconf} to Create @code{configure}
+@cindex @code{autoconf}
+
+To create @code{configure} from @file{configure.ac}, run the
+@code{autoconf} program with no arguments.  @code{autoconf} processes
+@file{configure.ac} with the @code{m4} macro processor, using the
+Autoconf macros.  If you give @code{autoconf} an argument, it reads that
+file instead of @file{configure.ac} and writes the configuration script
+to the standard output instead of to @code{configure}.  If you give
+@code{autoconf} the argument @option{-}, it reads from the standard
+input instead of @file{configure.ac} and writes the configuration script
+to the standard output.
+
+The Autoconf macros are defined in several files.  Some of the files are
+distributed with Autoconf; @code{autoconf} reads them first.  Then it
+looks for the optional file @file{acsite.m4} in the directory that
+contains the distributed Autoconf macro files, and for the optional file
+@file{aclocal.m4} in the current directory.  Those files can contain
+your site's or the package's own Autoconf macro definitions
+(@pxref{Writing Autoconf Macros}, for more information).  If a macro is defined
+in more than one of the files that @code{autoconf} reads, the last
+definition it reads overrides the earlier ones.
+
+@code{autoconf} accepts the following options:
+
+@table @option
+@item --help
+@itemx -h
+Print a summary of the command line options and exit.
+
+@item --version
+@itemx -V
+Print the version number of Autoconf and exit.
+
+@item --verbose
+@itemx -v
+Report processing steps.
+
+@item --debug
+@itemx -d
+Don't remove the temporary files.
+
+@item --autoconf-dir=@var{dir}
+@itemx -A @var{dir}
+@evindex AC_MACRODIR
+Override the location where the installed Autoconf data files are looked
+for.  You can also set the @code{AC_MACRODIR} environment variable to a
+directory; this option overrides the environment variable.
+
+This option is rarely needed and dangerous; it is only used when one
+plays with different versions of Autoconf simultaneously.
+
+@item --localdir=@var{dir}
+@itemx -l @var{dir}
+Look for the package file @file{aclocal.m4} in directory @var{dir}
+instead of in the current directory.
+
+@item --output=@var{file}
+@itemx -o @var{file}
+Save output (script or trace) to @var{file}.  The file @option{-} stands
+for the standard output.
+
+@item --warnings=@var{category}
+@itemx -W @var{category}
+@evindex WARNINGS
+Report the warnings related to @var{category} (which can actually be a
+comma separated list).  @xref{Reporting Messages}, macro
+@code{AC_DIAGNOSE}, for a comprehensive list of categories.  Special
+values include:
+
+@table @samp
+@item all
+report all the warnings
+
+@item none
+report none
+
+@item error
+treats warnings as errors
+
+@item no-@var{category}
+disable warnings falling into @var{category}
+@end table
+
+Warnings about @samp{syntax} are enabled by default, and the environment
+variable @code{WARNINGS}, a comma separated list of categories, is
+honored. @command{autoconf -W @var{category}} will actually
+behave as if you had run:
+
+@example
+autoconf --warnings=syntax,$WARNINGS,@var{category}
+@end example
+
+@noindent
+If you want to disable @command{autoconf}'s defaults and @code{WARNINGS},
+but (for example) enable the warnings about obsolete constructs, you
+would use @option{-W none,obsolete}.
+
+@cindex Back trace
+@cindex Macro invocation stack
+@command{autoconf} displays a back trace for errors, but not for
+warnings; if you want them, just pass @option{-W error}.  For instance,
+on this @file{configure.ac}:
+
+@example
+AC_DEFUN([INNER],
+[AC_TRY_RUN([true])])
+
+AC_DEFUN([OUTER],
+[INNER])
+
+AC_INIT
+OUTER
+@end example
+
+@noindent
+you get:
+
+@example
+$ autoconf -Wcross
+configure.ac:8: warning: AC_TRY_RUN called without default \
+to allow cross compiling
+$ autoconf -Wcross,error
+configure.ac:8: error: AC_TRY_RUN called without default \
+to allow cross compiling
+acgeneral.m4:3044: AC_TRY_RUN is expanded from...
+configure.ac:2: INNER is expanded from...
+configure.ac:5: OUTER is expanded from...
+configure.ac:8: the top level
+@end example
+
+@item --trace=@var{macro}[:@var{format}]
+@itemx -t @var{macro}[:@var{format}]
+Do not create the @code{configure} script, but list the calls to
+@var{macro} according to the @var{format}.  Multiple @option{--trace}
+arguments can be used to list several macros.  Multiple @option{--trace}
+arguments for a single macro are not cumulative; instead, you should
+just make @var{format} as long as needed.
+
+The @var{format} is a regular string, with newlines if desired, and
+several special escape codes.  It defaults to @samp{$f:$l:$n:$%}; see
+below for details on the @var{format}.
+
+@item --initialization
+@itemx -i
+By default, @option{--trace} does not trace the initialization of the
+Autoconf macros (typically the @code{AC_DEFUN} definitions).  This
+results in a noticeable speedup, but can be disabled by this option.
+@end table
+
+
+It is often necessary to check the content of a @file{configure.ac}
+file, but parsing it yourself is extremely fragile and error-prone.  It
+is suggested that you rely upon @option{--trace} to scan
+@file{configure.ac}.
+
+The @var{format} of @option{--trace} can use the following special
+escapes:
+
+@table @samp
+@item $$
+The character @samp{$}.
+
+@item $f
+The filename from which @var{macro} is called.
+
+@item $l
+The line number from which @var{macro} is called.
+
+@item $d
+The depth of the @var{macro} call.  This is an M4 technical detail that
+you probably don't want to know about.
+
+@item $n
+The name of the @var{macro}.
+
+@item $@var{num}
+The @var{num}th argument of the call to @var{macro}.
+
+@item $@@
+@itemx $@var{sep}@@
+@itemx $@{@var{separator}@}@@
+All the arguments passed to @var{macro}, separated by the character
+@var{sep} or the string @var{separator} (@samp{,} by default).  Each
+argument is quoted, i.e. enclosed in a pair of square brackets.
+
+@item $*
+@itemx $@var{sep}*
+@itemx $@{@var{separator}@}*
+As above, but the arguments are not quoted.
+
+@item $%
+@itemx $@var{sep}%
+@itemx $@{@var{separator}@}%
+As above, but the arguments are not quoted, all new line characters in
+the arguments are smashed, and the default separator is @samp{:}.
+
+The escape @samp{$%} produces single-line trace outputs (unless you put
+newlines in the @samp{separator}), while @samp{$@@} and @samp{$*} do
+not.
+@end table
+
+For instance, to find the list of variables that are substituted, use:
+
+@example
+@group
+$ autoconf -t AC_SUBST
+configure.ac:2:AC_SUBST:ECHO_C
+configure.ac:2:AC_SUBST:ECHO_N
+configure.ac:2:AC_SUBST:ECHO_T
+@i{More traces deleted}
+@end group
+@end example
+
+@noindent
+The example below highlights the difference between @samp{$@@},
+@samp{$*}, and @strong{$%}.
+
+@example
+@group
+$ cat configure.ac
+AC_DEFINE(This, is, [an
+[example]])
+$ autoconf -t 'AC_DEFINE:@@: $@@
+*: $*
+$: $%'
+@@: [This],[is],[an
+[example]]
+*: This,is,an
+[example]
+$: This:is:an [example]
+@end group
+@end example
+
+@noindent
+The @var{format} gives you a lot of freedom:
+
+@example
+@group
+$ autoconf -t 'AC_SUBST:$$ac_subst@{"$1"@} = "$f:$l";'
+$ac_subst@{"ECHO_C"@} = "configure.ac:2";
+$ac_subst@{"ECHO_N"@} = "configure.ac:2";
+$ac_subst@{"ECHO_T"@} = "configure.ac:2";
+@i{More traces deleted}
+@end group
+@end example
+
+@noindent
+A long @var{separator} can be used to improve the readability of complex
+structures, and to ease its parsing (for instance when no single
+character is suitable as a separator)):
+
+@example
+@group
+$ autoconf -t 'AM_MISSING_PROG:$@{|:::::|@}*'
+AUTOCONF|:::::|autoconf|:::::|$missing_dir
+@i{More traces deleted}
+@end group
+@end example
+
+@node autoreconf Invocation,  , autoconf Invocation, Making configure Scripts
+@section Using @code{autoreconf} to Update @code{configure} Scripts
+@cindex @code{autoreconf}
+
+If you have a lot of Autoconf-generated @code{configure} scripts, the
+@code{autoreconf} program can save you some work.  It runs
+@code{autoconf} (and @code{autoheader}, where appropriate) repeatedly to
+remake the Autoconf @code{configure} scripts and configuration header
+templates in the directory tree rooted at the current directory.  By
+default, it only remakes those files that are older than their
+@file{configure.ac} or (if present) @file{aclocal.m4}.  Since
+@code{autoheader} does not change the timestamp of its output file if
+the file wouldn't be changing, this is not necessarily the minimum
+amount of work.  If you install a new version of Autoconf, you can make
+@code{autoreconf} remake @emph{all} of the files by giving it the
+@option{--force} option.
+
+If you give @code{autoreconf} the @option{--autoconf-dir=@var{dir}} or
+@option{--localdir=@var{dir}} options, it passes them down to
+@code{autoconf} and @code{autoheader} (with relative paths adjusted
+properly).
+
+@code{autoreconf} does not support having, in the same directory tree,
+both directories that are parts of a larger package (sharing
+@file{aclocal.m4} and @file{acconfig.h}) and directories that are
+independent packages (each with their own @file{aclocal.m4} and
+@file{acconfig.h}).  It assumes that they are all part of the same
+package if you use @option{--localdir}, or that each directory is a
+separate package if you don't use it.  This restriction may be removed
+in the future.
+
+@xref{Automatic Remaking}, for @file{Makefile} rules to automatically
+remake @code{configure} scripts when their source files change.  That
+method handles the timestamps of configuration header templates
+properly, but does not pass @option{--autoconf-dir=@var{dir}} or
+@option{--localdir=@var{dir}}.
+
+@noindent
+@code{autoreconf} accepts the following options:
+
+@table @option
+@item --help
+@itemx -h
+Print a summary of the command line options and exit.
+
+@item --version
+@itemx -V
+Print the version number of Autoconf and exit.
+
+@item --verbose
+Print the name of each directory where @code{autoreconf} runs
+@code{autoconf} (and @code{autoheader}, if appropriate).
+
+@item --debug
+@itemx -d
+Don't remove the temporary files.
+
+@item --force
+@itemx -f
+Remake even @file{configure} scripts and configuration headers that are
+newer than their input files (@file{configure.ac} and, if present,
+@file{aclocal.m4}).
+
+@item --install
+@itemx -i
+Copy missing auxiliary files.  This option is similar to the option
+@code{--add-missing} in other tools.
+
+@item --symlink
+@itemx -s
+Instead of copying missing auxiliary files, install symbolic links.
+
+@item --localdir=@var{dir}
+@itemx -l @var{dir}
+Have @code{autoconf} and @code{autoheader} look for the package files
+@file{aclocal.m4} and (@code{autoheader} only) @file{acconfig.h} (but
+not @file{@var{file}.top} and @file{@var{file}.bot}) in directory
+@var{dir} instead of in the directory containing each @file{configure.ac}.
+
+@item --autoconf-dir=@var{dir}
+@itemx -A @var{dir}
+@evindex AC_MACRODIR
+Override the location where the installed Autoconf data files are looked
+for.  You can also set the @code{AC_MACRODIR} environment variable to a
+directory; this option overrides the environment variable.
+
+This option is rarely needed and dangerous; it is only used when one
+plays with different versions of Autoconf simultaneously.
+
+@item --m4dir=@var{dir}
+@itemx -M @var{dir}
+Specify location of additional macro files (@file{m4} by default).
+@end table
+
+
+@c ========================================= Initialization and Output Files.
+
+@node Setup, Existing Tests, Making configure Scripts, Top
+@chapter Initialization and Output Files
+
+Autoconf-generated @code{configure} scripts need some information about
+how to initialize, such as how to find the package's source files; and
+about the output files to produce.  The following sections describe
+initialization and the creation of output files.
+
+@menu
+* Notices::                     Copyright, version numbers in @code{configure}
+* Input::                       Where Autoconf should find files
+* Output::                      Outputting results from the configuration
+* Configuration Actions::       Preparing the output based on results
+* Configuration Files::         Creating output files
+* Makefile Substitutions::      Using output variables in @file{Makefile}s
+* Configuration Headers::       Creating a configuration header file
+* Configuration Commands::      Running arbitrary instantiation commands
+* Configuration Links::         Links depending from the configuration
+* Subdirectories::              Configuring independent packages together
+* Default Prefix::              Changing the default installation prefix
+@end menu
+
+@node Notices, Input, Setup, Setup
+@section Notices in @code{configure}
+
+The following macros manage version numbers for @code{configure}
+scripts.  Using them is optional.
+
+@c FIXME: AC_PREREQ should not be here, but where should it go?
+@defmac AC_PREREQ (@var{version})
+@maindex PREREQ
+@cindex Version
+Ensure that a recent enough version of Autoconf is being used.  If the
+version of Autoconf being used to create @code{configure} is earlier
+than @var{version}, print an error message to the standard error output
+and do not create @code{configure}.  For example:
+
+@example
+AC_PREREQ(@value{VERSION})
+@end example
+
+This macro is the only macro that may be used before @code{AC_INIT}, but
+for consistency, you are invited not to do so.
+@end defmac
+
+@defmac AC_COPYRIGHT (@var{copyright-notice})
+@maindex COPYRIGHT
+@cindex Copyright Notice
+State that, in addition to the Free Software Foundation's copyright on
+the Autoconf macros, parts of your @code{configure} are covered by the
+@var{copyright-notice}.
+
+The @var{copyright-notice} will show up in both the head of
+@code{configure} and in @samp{configure --version}.
+@end defmac
+
+
+@defmac AC_REVISION (@var{revision-info})
+@maindex REVISION
+@cindex Revision
+Copy revision stamp @var{revision-info} into the @code{configure}
+script, with any dollar signs or double-quotes removed.  This macro lets
+you put a revision stamp from @file{configure.ac} into @code{configure}
+without @sc{rcs} or @code{cvs} changing it when you check in
+@code{configure}.  That way, you can determine easily which revision of
+@file{configure.ac} a particular @code{configure} corresponds to.
+
+For example, this line in @file{configure.ac}:
+
+@c The asis prevents RCS from changing the example in the manual.
+@example
+AC_REVISION($@asis{Revision: 1.30 }$)
+@end example
+
+@noindent
+produces this in @code{configure}:
+
+@example
+#! /bin/sh
+# From configure.ac Revision: 1.30
+@end example
+@end defmac
+
+
+@node Input, Output, Notices, Setup
+@section Finding @code{configure} Input
+
+Every @code{configure} script must call @code{AC_INIT} before doing
+anything else.  The only other required macro is @code{AC_OUTPUT}
+(@pxref{Output}).
+
+@defmac AC_INIT (@var{package}, @var{version}, @ovar{bug-report-address})
+@maindex INIT
+Process any command-line arguments and perform various initializations
+and verifications.  Set the name of the @var{package} and its
+@var{version}.  The optional argument @var{bug-report-address} should be
+the email to which users should send bug reports.
+@end defmac
+
+@defmac AC_CONFIG_SRCDIR (@var{unique-file-in-source-dir})
+@maindex CONFIG_SRCDIR
+@var{unique-file-in-source-dir} is some file that is in the package's
+source directory; @code{configure} checks for this file's existence to
+make sure that the directory that it is told contains the source code in
+fact does.  Occasionally people accidentally specify the wrong directory
+with @option{--srcdir}; this is a safety check.  @xref{configure
+Invocation}, for more information.
+@end defmac
+
+
+@c FIXME: Remove definitively once --install explained.
+@c
+@c Small packages may store all their macros in @code{aclocal.m4}.  As the
+@c set of macros grows, or for maintenance reasons, a maintainer may prefer
+@c to split the macros in several files.  In this case, Autoconf must be
+@c told which files to load, and in which order.
+@c
+@c @defmac AC_INCLUDE (@var{file}@dots{})
+@c @maindex INCLUDE
+@c @c FIXME: There is no longer shell globbing.
+@c Read the macro definitions that appear in the listed files.  A list of
+@c space-separated filenames or shell globbing patterns is expected.  The
+@c files will be read in the order they're listed.
+@c
+@c Because the order of definition of macros is important (only the last
+@c definition of a macro is used), beware that it is @code{AC_INIT} that
+@c loads @file{acsite.m4} and @file{aclocal.m4}.  Note that
+@c @code{AC_INCLUDE}ing a file before @code{AC_INIT} or within
+@c @file{aclocal.m4} is different from doing so after @code{AC_INIT}: in
+@c the latter case, non-macro lines from included files may end up in the
+@c @file{configure} script, whereas in the former case, they'd be discarded
+@c just like any text that appear before @code{AC_INIT}.
+@c @end defmac
+
+Packages that do manual configuration or use the @code{install} program
+might need to tell @code{configure} where to find some other shell
+scripts by calling @code{AC_CONFIG_AUX_DIR}, though the default places
+it looks are correct for most cases.
+
+@defmac AC_CONFIG_AUX_DIR (@var{dir})
+@maindex CONFIG_AUX_DIR
+Use the auxiliary build tools (e.g., @file{install-sh},
+@file{config.sub}, @file{config.guess}, Cygnus @code{configure},
+Automake and Libtool scripts etc.) that are in directory @var{dir}.
+These are auxiliary files used in configuration.  @var{dir} can be
+either absolute or relative to @file{@var{srcdir}}.  The default is
+@file{@var{srcdir}} or @file{@var{srcdir}/..} or
+@file{@var{srcdir}/../..}, whichever is the first that contains
+@file{install-sh}.  The other files are not checked for, so that using
+@code{AC_PROG_INSTALL} does not automatically require distributing the
+other auxiliary files.  It checks for @file{install.sh} also, but that
+name is obsolete because some @command{make} have a rule that creates
+@file{install} from it if there is no @file{Makefile}.
+@end defmac
+
+
+@node Output, Configuration Actions, Input, Setup
+@section Outputting Files
+
+Every Autoconf-generated @code{configure} script must finish by calling
+@code{AC_OUTPUT}.  It is the macro that generates @file{config.status},
+which will create the @file{Makefile}s and any other files resulting
+from configuration.  The only other required macro is @code{AC_INIT}
+(@pxref{Input}).
+
+@defmac AC_OUTPUT
+@maindex OUTPUT
+@cindex Instantiation
+Generate @file{config.status} and launch it.  Call this macro once, at
+the end of @file{configure.ac}.
+
+@file{config.status} will take all the configuration actions: all the
+output files (see @ref{Configuration Files}, macro
+@code{AC_CONFIG_FILES}), header files (see @ref{Configuration Headers},
+macro @code{AC_CONFIG_HEADERS}), commands (see @ref{Configuration
+Commands}, macro @code{AC_CONFIG_COMMANDS}), links (see
+@ref{Configuration Links}, macro @code{AC_CONFIG_LINKS}), subdirectories
+to configure (see @ref{Subdirectories}, macro @code{AC_CONFIG_SUBDIRS})
+are honored.
+@end defmac
+
+Historically, the usage of @code{AC_OUTPUT} was somewhat different.
+@xref{Obsolete Macros}, for a description of the arguments that
+@code{AC_OUTPUT} used to support.
+
+
+If you run @code{make} on subdirectories, you should run it using the
+@code{make} variable @code{MAKE}.  Most versions of @code{make} set
+@code{MAKE} to the name of the @code{make} program plus any options it
+was given.  (But many do not include in it the values of any variables
+set on the command line, so those are not passed on automatically.)
+Some old versions of @code{make} do not set this variable.  The
+following macro allows you to use it even with those versions.
+
+@defmac AC_PROG_MAKE_SET
+@maindex PROG_MAKE_SET
+@ovindex SET_MAKE
+If @code{make} predefines the variable @code{MAKE}, define output
+variable @code{SET_MAKE} to be empty.  Otherwise, define @code{SET_MAKE}
+to contain @samp{MAKE=make}.  Calls @code{AC_SUBST} for @code{SET_MAKE}.
+@end defmac
+
+To use this macro, place a line like this in each @file{Makefile.in}
+that runs @code{MAKE} on other directories:
+
+@example
+@@SET_MAKE@@
+@end example
+
+
+
+@node Configuration Actions, Configuration Files, Output, Setup
+@section Taking Configuration Actions
+
+@file{configure} is designed so that it appears to do everything itself,
+but there is actually a hidden slave: @file{config.status}.
+@file{configure} is in charge of examining your system, but it is
+@file{config.status} that actually takes the proper actions based on the
+results of @file{configure}.  The most typical task of
+@file{config.status} is to @emph{instantiate} files.
+
+This section describes the common behavior of the four standard
+instantiating macros: @code{AC_CONFIG_FILES}, @code{AC_CONFIG_HEADERS},
+@code{AC_CONFIG_COMMANDS} and @code{AC_CONFIG_LINKS}.  They all
+have this prototype:
+
+@c Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something
+@c awful.
+@example
+AC_CONFIG_FOOS(@var{tag}@dots{}, [@var{commands}], [@var{init-cmds}])
+@end example
+
+@noindent
+where the arguments are:
+
+@table @var
+@item @var{tag}@dots{}
+A whitespace-separated list of tags, which are typically the names of
+the files to instantiate.
+
+@item commands
+Shell commands output literally into @file{config.status}, and
+associated with a tag that the user can use to tell @file{config.status}
+which the commands to run.  The commands are run each time a @var{tag}
+request is given to @file{config.status}; typically, each time the file
+@file{@var{tag}} is created.
+
+@item init-cmds
+Shell commands output @emph{unquoted} near the beginning of
+@file{config.status}, and executed each time @file{config.status} runs
+(regardless of the tag).  Because they are unquoted, for example,
+@samp{$var} will be output as the value of @code{var}.  @var{init-cmds}
+is typically used by @file{configure} to give @file{config.status} some
+variables it needs to run the @var{commands}.
+@end table
+
+All these macros can be called multiple times, with different
+@var{tag}s, of course!
+
+You are encouraged to use literals as @var{tags}.  In particular, you
+should avoid
+
+@example
+@dots{} && my_foos="$my_foos fooo"
+@dots{} && my_foos="$my_foos foooo"
+AC_CONFIG_FOOS($my_foos)
+@end example
+
+@noindent
+and use this instead:
+
+@example
+@dots{} && AC_CONFIG_FOOS(fooo)
+@dots{} && AC_CONFIG_FOOS(foooo)
+@end example
+
+The macro @code{AC_CONFIG_FILES} and @code{AC_CONFIG_HEADERS} use
+specials @var{tag}s: they may have the form @samp{@var{output}} or
+@samp{@var{output}:@var{inputs}}. The file @var{output} is instantiated
+from its templates, @var{inputs} if specified, defaulting to
+@samp{@var{output}.in}.
+
+For instance
+@samp{AC_CONFIG_FILES(Makefile:boiler/top.mk:boiler/bot.mk)} asks for
+the creation of @file{Makefile} that will be the expansion of the
+output variables in the concatenation of @file{boiler/top.mk} and
+@file{boiler/bot.mk}.
+
+The special value @samp{-} might be used to denote the standard output
+when used in @var{output}, or the standard input when used in the
+@var{inputs}.  You most probably don't need to use this in
+@file{configure.ac}, but it is convenient when using the command line
+interface of @file{./config.status}, see @ref{config.status Invocation},
+for more details.
+
+The @var{inputs} may be absolute or relative filenames.  In the latter
+case they are first looked for in the build tree, and then in the source
+tree.
+
+
+@node Configuration Files, Makefile Substitutions, Configuration Actions, Setup
+@section Creating Configuration Files
+
+Be sure to read the previous section, @ref{Configuration Actions}.
+
+@defmac AC_CONFIG_FILES (@var{file}@dots{}, @ovar{cmds}, @ovar{init-cmds})
+@maindex CONFIG_FILES
+Make @code{AC_OUTPUT} create each @file{@var{file}} by copying an input
+file (by default @file{@var{file}.in}), substituting the output variable
+values.
+@c Before we used to have this feature, which was later rejected
+@c because it complicates the write of Makefiles:
+@c If the file would be unchanged, it is left untouched, to preserve
+@c timestamp.
+This macro is one of the instantiating macros, see @ref{Configuration
+Actions}.  @xref{Makefile Substitutions}, for more information on using
+output variables.  @xref{Setting Output Variables}, for more information
+on creating them.  This macro creates the directory that the file is in
+if it doesn't exist.  Usually, @file{Makefile}s are created this way,
+but other files, such as @file{.gdbinit}, can be specified as well.
+
+Typical calls to @code{AC_CONFIG_FILES} look like this:
+
+@example
+AC_CONFIG_FILES(Makefile src/Makefile man/Makefile X/Imakefile)
+AC_CONFIG_FILES(autoconf, chmod +x autoconf)
+@end example
+
+You can override an input file name by appending to @var{file} a
+colon-separated list of input files.  Examples:
+
+@example
+AC_CONFIG_FILES(Makefile:boiler/top.mk:boiler/bot.mk
+                lib/Makefile:boiler/lib.mk)
+@end example
+
+@noindent
+Doing this allows you to keep your file names acceptable to MS-DOS, or
+to prepend and/or append boilerplate to the file.
+@end defmac
+
+
+
+@node Makefile Substitutions, Configuration Headers, Configuration Files, Setup
+@section Substitutions in Makefiles
+
+Each subdirectory in a distribution that contains something to be
+compiled or installed should come with a file @file{Makefile.in}, from
+which @code{configure} will create a @file{Makefile} in that directory.
+To create a @file{Makefile}, @code{configure} performs a simple variable
+substitution, replacing occurrences of @samp{@@@var{variable}@@} in
+@file{Makefile.in} with the value that @code{configure} has determined
+for that variable.  Variables that are substituted into output files in
+this way are called @dfn{output variables}.  They are ordinary shell
+variables that are set in @code{configure}.  To make @code{configure}
+substitute a particular variable into the output files, the macro
+@code{AC_SUBST} must be called with that variable name as an argument.
+Any occurrences of @samp{@@@var{variable}@@} for other variables are
+left unchanged.  @xref{Setting Output Variables}, for more information
+on creating output variables with @code{AC_SUBST}.
+
+A software package that uses a @code{configure} script should be
+distributed with a file @file{Makefile.in}, but no @file{Makefile}; that
+way, the user has to properly configure the package for the local system
+before compiling it.
+
+@xref{Makefile Conventions,, Makefile Conventions, standards, The
+GNU Coding Standards}, for more information on what to put in
+@file{Makefile}s.
+
+@menu
+* Preset Output Variables::     Output variables that are always set
+* Installation Directory Variables::  Other preset output variables
+* Build Directories::           Supporting multiple concurrent compiles
+* Automatic Remaking::          Makefile rules for configuring
+@end menu
+
+@node Preset Output Variables, Installation Directory Variables, Makefile Substitutions, Makefile Substitutions
+@subsection Preset Output Variables
+
+Some output variables are preset by the Autoconf macros.  Some of the
+Autoconf macros set additional output variables, which are mentioned in
+the descriptions for those macros.  @xref{Output Variable Index}, for a
+complete list of output variables.  @xref{Installation Directory
+Variables}, for the list of the preset ones related to installation
+directories.  Below are listed the other preset ones.  They all are
+precious variables (@pxref{Setting Output Variables},
+@code{AC_ARG_VAR}).
+
+@c Just say no to ASCII sorting!  We're humans, not computers.
+@c These variables are listed as they would be in a dictionary:
+@c actor
+@c Actress
+@c actress
+
+@defvar CFLAGS
+@ovindex CFLAGS
+Debugging and optimization options for the C compiler.  If it is not set
+in the environment when @code{configure} runs, the default value is set
+when you call @code{AC_PROG_CC} (or empty if you don't).  @code{configure}
+uses this variable when compiling programs to test for C features.
+@end defvar
+
+@defvar configure_input
+@ovindex configure_input
+A comment saying that the file was generated automatically by
+@code{configure} and giving the name of the input file.
+@code{AC_OUTPUT} adds a comment line containing this variable to the top
+of every @file{Makefile} it creates.  For other files, you should
+reference this variable in a comment at the top of each input file.  For
+example, an input shell script should begin like this:
+
+@example
+#! /bin/sh
+# @@configure_input@@
+@end example
+
+@noindent
+The presence of that line also reminds people editing the file that it
+needs to be processed by @code{configure} in order to be used.
+@end defvar
+
+@defvar CPPFLAGS
+@ovindex CPPFLAGS
+Header file search directory (@option{-I@var{dir}}) and any other
+miscellaneous options for the C and C++ preprocessors and compilers.  If
+it is not set in the environment when @code{configure} runs, the default
+value is empty.  @code{configure} uses this variable when compiling or
+preprocessing programs to test for C and C++ features.
+@end defvar
+
+@defvar CXXFLAGS
+@ovindex CXXFLAGS
+Debugging and optimization options for the C++ compiler.  If it is not
+set in the environment when @code{configure} runs, the default value is
+set when you call @code{AC_PROG_CXX} (or empty if you don't).
+@code{configure} uses this variable when compiling programs to test for
+C++ features.
+@end defvar
+
+@defvar DEFS
+@ovindex DEFS
+@option{-D} options to pass to the C compiler.  If @code{AC_CONFIG_HEADERS}
+is called, @code{configure} replaces @samp{@@DEFS@@} with
+@option{-DHAVE_CONFIG_H} instead (@pxref{Configuration Headers}).  This
+variable is not defined while @code{configure} is performing its tests,
+only when creating the output files.  @xref{Setting Output Variables}, for
+how to check the results of previous tests.
+@end defvar
+
+@defvar ECHO_C
+@defvarx ECHO_N
+@defvarx ECHO_T
+@ovindex ECHO_C
+@ovindex ECHO_N
+@ovindex ECHO_T
+How does one suppress the trailing newline from @code{echo} for
+question-answer message pairs?  These variables provide a way:
+
+@example
+echo $ECHO_N "And the winner is... $ECHO_C"
+sleep 100000000000
+echo "$@{ECHO_T@}dead."
+@end example
+
+@noindent
+Some old and uncommon @code{echo} implementations offer no means to
+achieve this, in which case @code{ECHO_T} is set to tab.  You might not
+want to use it.
+@end defvar
+
+@defvar FFLAGS
+@ovindex FFLAGS
+Debugging and optimization options for the Fortran 77 compiler.  If it
+is not set in the environment when @code{configure} runs, the default
+value is set when you call @code{AC_PROG_F77} (or empty if you don't).
+@code{configure} uses this variable when compiling programs to test for
+Fortran 77 features.
+@end defvar
+
+@defvar LDFLAGS
+@ovindex LDFLAGS
+Stripping (@option{-s}), path (@option{-L}), and any other miscellaneous
+options for the linker.  Don't use this variable to pass library names
+(@option{-l}) to the linker, use @code{LIBS} instead.  If it is not set
+in the environment when @code{configure} runs, the default value is empty.
+@code{configure} uses this variable when linking programs to test for
+C, C++ and Fortran 77 features.
+@end defvar
+
+@defvar LIBS
+@ovindex LIBS
+@option{-l} options to pass to the linker.  The default value is empty,
+but some Autoconf macros may prepend extra libraries to this variable if
+those libraries are found and provide necessary functions, see
+@ref{Libraries}.  @code{configure} uses this variable when linking
+programs to test for C, C++ and Fortran 77 features.
+@end defvar
+
+@defvar srcdir
+@ovindex srcdir
+The directory that contains the source code for that @file{Makefile}.
+@end defvar
+
+@defvar top_srcdir
+@ovindex top_srcdir
+The top-level source code directory for the package.  In the top-level
+directory, this is the same as @code{srcdir}.
+@end defvar
+
+@node Installation Directory Variables, Build Directories, Preset Output Variables, Makefile Substitutions
+@subsection Installation Directory Variables
+
+The following variables specify the directories where the package will
+be installed, see @ref{Directory Variables,, Variables for Installation
+Directories, standards, The GNU Coding Standards}, for more information.
+See the end of this section for details on when and how to use these
+variables.
+
+@defvar bindir
+@ovindex bindir
+The directory for installing executables that users run.
+@end defvar
+
+@defvar datadir
+@ovindex datadir
+The directory for installing read-only architecture-independent data.
+@end defvar
+
+@defvar exec_prefix
+@ovindex exec_prefix
+The installation prefix for architecture-dependent files.  By default
+it's the same as @var{prefix}.  You should avoid installing anything
+directly to @var{exec_prefix}.  However, the default value for
+directories containing architecture-dependent files should be relative
+to @var{exec_prefix}.
+@end defvar
+
+@defvar includedir
+@ovindex includedir
+The directory for installing C header files.
+@end defvar
+
+@defvar infodir
+@ovindex infodir
+The directory for installing documentation in Info format.
+@end defvar
+
+@defvar libdir
+@ovindex libdir
+The directory for installing object code libraries.
+@end defvar
+
+@defvar libexecdir
+@ovindex libexecdir
+The directory for installing executables that other programs run.
+@end defvar
+
+@defvar localstatedir
+@ovindex localstatedir
+The directory for installing modifiable single-machine data.
+@end defvar
+
+@defvar mandir
+@ovindex mandir
+The top-level directory for installing documentation in man format.
+@end defvar
+
+@defvar oldincludedir
+@ovindex oldincludedir
+The directory for installing C header files for non-gcc compilers.
+@end defvar
+
+@defvar prefix
+@ovindex prefix
+The common installation prefix for all files. If @var{exec_prefix}
+is defined to a different value, @var{prefix} is used only for
+architecture-independent files.
+@end defvar
+
+@defvar sbindir
+@ovindex sbindir
+The directory for installing executables that system
+administrators run.
+@end defvar
+
+@defvar sharedstatedir
+@ovindex sharedstatedir
+The directory for installing modifiable architecture-independent data.
+@end defvar
+
+@defvar sysconfdir
+@ovindex sysconfdir
+The directory for installing read-only single-machine data.
+@end defvar
+
+
+Most of these variables have values that rely on @code{prefix} or
+@code{exec_prefix}.  It is on purpose that the directory output
+variables keep them unexpanded: typically @samp{@@datadir@@} will be
+replaced by @samp{$@{prefix@}/share}, not @samp{/usr/local/share}.
+
+This behavior is mandated by the @sc{gnu} coding standards, so that when
+the user runs:
+
+@table @samp
+@item make
+she can still specify a different prefix from the one specified to
+@command{configure}, in which case, if needed, the package shall hard
+code dependencies to her late desires.
+
+@item make install
+she can specify a different installation location, in which case the
+package @emph{must} still depend on the location which was compiled in
+(i.e., never recompile when @samp{make install} is run).  This is an
+extremely important feature, as many people may decide to install all
+the files of a package grouped together, and then install links from
+the final locations to there.
+@end table
+
+In order to support these features, it is essential that @code{datadir}
+remains being defined as @samp{$@{prefix@}/share} to depend upon the
+current value of @code{prefix}.
+
+A corollary is that you should not use these variables but in Makefiles.
+For instance, instead of trying to evaluate @code{datadir} in
+@file{configure} and hardcoding it in Makefiles using
+e.g. @samp{AC_DEFINE_UNQUOTED(DATADIR, "$datadir")}, you should add
+@samp{-DDATADIR="$(datadir)"} to your @code{CPPFLAGS}.
+
+Similarly you should not rely on @code{AC_OUTPUT_FILES} to replace
+@code{datadir} and friends in your shell scripts and other files, rather
+let @command{make} manage their replacement.  For instance Autoconf
+ships templates of its shell scripts ending with @samp{.sh}, and uses
+this Makefile snippet:
+
+@example
+.sh:
+        rm -f $@@ $@@.tmp
+        sed 's,@@datadir\@@,$(pkgdatadir),g' $< >$@@.tmp
+        chmod +x $@@.tmp
+        mv $@@.tmp $@@
+@end example
+
+Three things are noteworthy:
+
+@table @samp
+@item @@datadir\@@
+The backslash prevents @command{configure} from replacing
+@samp{@@datadir@@} in the sed expression itself.
+
+@item $(pkgdatadir)
+Don't use @samp{@@pkgdatadir@@}!  Use the matching makefile variable
+instead.
+
+@item ,
+Don't use @samp{/} in the sed expression(s) since most probably the
+variables you use, such as @samp{$(pkgdatadir)}, will contain
+some.
+@end table
+
+
+@node Build Directories, Automatic Remaking, Installation Directory Variables, Makefile Substitutions
+@subsection Build Directories
+
+You can support compiling a software package for several architectures
+simultaneously from the same copy of the source code.  The object files
+for each architecture are kept in their own directory.
+
+To support doing this, @code{make} uses the @code{VPATH} variable to
+find the files that are in the source directory.  @sc{gnu} @code{make}
+and most other recent @code{make} programs can do this.  Older
+@code{make} programs do not support @code{VPATH}; when using them, the
+source code must be in the same directory as the object files.
+
+To support @code{VPATH}, each @file{Makefile.in} should contain two
+lines that look like:
+
+@example
+srcdir = @@srcdir@@
+VPATH = @@srcdir@@
+@end example
+
+Do not set @code{VPATH} to the value of another variable, for example
+@samp{VPATH = $(srcdir)}, because some versions of @code{make} do not do
+variable substitutions on the value of @code{VPATH}.
+
+@code{configure} substitutes in the correct value for @code{srcdir} when
+it produces @file{Makefile}.
+
+Do not use the @code{make} variable @code{$<}, which expands to the
+file name of the file in the source directory (found with @code{VPATH}),
+except in implicit rules.  (An implicit rule is one such as @samp{.c.o},
+which tells how to create a @file{.o} file from a @file{.c} file.)  Some
+versions of @code{make} do not set @code{$<} in explicit rules; they
+expand it to an empty value.
+
+Instead, @file{Makefile} command lines should always refer to source
+files by prefixing them with @samp{$(srcdir)/}.  For example:
+
+@example
+time.info: time.texinfo
+        $(MAKEINFO) $(srcdir)/time.texinfo
+@end example
+
+@node Automatic Remaking,  , Build Directories, Makefile Substitutions
+@subsection Automatic Remaking
+
+You can put rules like the following in the top-level @file{Makefile.in}
+for a package to automatically update the configuration information when
+you change the configuration files.  This example includes all of the
+optional files, such as @file{aclocal.m4} and those related to
+configuration header files.  Omit from the @file{Makefile.in} rules for
+any of these files that your package does not use.
+
+The @samp{$(srcdir)/} prefix is included because of limitations in the
+@code{VPATH} mechanism.
+
+The @file{stamp-} files are necessary because the timestamps of
+@file{config.h.in} and @file{config.h} will not be changed if remaking
+them does not change their contents.  This feature avoids unnecessary
+recompilation.  You should include the file @file{stamp-h.in} your
+package's distribution, so @command{make} will consider
+@file{config.h.in} up to date.  Don't use @command{touch}
+(@pxref{Limitations of Usual Tools}), rather use @command{echo} (using
+@command{date} would cause needless differences, hence @sc{cvs}
+conflicts etc.).
+
+@example
+@group
+$(srcdir)/configure: configure.ac aclocal.m4
+        cd $(srcdir) && autoconf
+
+# autoheader might not change config.h.in, so touch a stamp file.
+$(srcdir)/config.h.in: stamp-h.in
+$(srcdir)/stamp-h.in: configure.ac aclocal.m4
+        cd $(srcdir) && autoheader
+        echo timestamp > $(srcdir)/stamp-h.in
+
+config.h: stamp-h
+stamp-h: config.h.in config.status
+        ./config.status
+
+Makefile: Makefile.in config.status
+        ./config.status
+
+config.status: configure
+        ./config.status --recheck
+@end group
+@end example
+
+@noindent
+(Be careful if you copy these lines directly into your Makefile, as you
+will need to convert the indented lines to start with the tab character.)
+
+In addition, you should use @samp{AC_CONFIG_FILES(stamp-h, echo
+timestamp > stamp-h)} so @file{config.status} will ensure that
+@file{config.h} is considered up to date.  @xref{Output}, for more
+information about @code{AC_OUTPUT}.
+
+@xref{config.status Invocation}, for more examples of handling
+configuration-related dependencies.
+
+@node Configuration Headers, Configuration Commands, Makefile Substitutions, Setup
+@section Configuration Header Files
+@cindex Configuration Header
+@cindex @file{config.h}
+
+When a package tests more than a few C preprocessor symbols, the command
+lines to pass @option{-D} options to the compiler can get quite long.
+This causes two problems.  One is that the @code{make} output is hard to
+visually scan for errors.  More seriously, the command lines can exceed
+the length limits of some operating systems.  As an alternative to
+passing @option{-D} options to the compiler, @code{configure} scripts can
+create a C header file containing @samp{#define} directives.  The
+@code{AC_CONFIG_HEADERS} macro selects this kind of output.  It should
+be called right after @code{AC_INIT}.
+
+The package should @samp{#include} the configuration header file before
+any other header files, to prevent inconsistencies in declarations (for
+example, if it redefines @code{const}).  Use @samp{#include <config.h>}
+instead of @samp{#include "config.h"}, and pass the C compiler a
+@option{-I.} option (or @option{-I..}; whichever directory contains
+@file{config.h}).  That way, even if the source directory is configured
+itself (perhaps to make a distribution), other build directories can
+also be configured without finding the @file{config.h} from the source
+directory.
+
+@defmac AC_CONFIG_HEADERS (@var{header} @dots{}, @ovar{cmds}, @ovar{init-cmds})
+@maindex CONFIG_HEADERS
+@cvindex HAVE_CONFIG_H
+This macro is one of the instantiating macros, see @ref{Configuration
+Actions}.  Make @code{AC_OUTPUT} create the file(s) in the
+whitespace-separated list @var{header} containing C preprocessor
+@code{#define} statements, and replace @samp{@@DEFS@@} in generated
+files with @option{-DHAVE_CONFIG_H} instead of the value of @code{DEFS}.
+The usual name for @var{header} is @file{config.h}.
+
+If @var{header} already exists and its contents are identical to what
+@code{AC_OUTPUT} would put in it, it is left alone.  Doing this allows
+some changes in configuration without needlessly causing object files
+that depend on the header file to be recompiled.
+
+Usually the input file is named @file{@var{header}.in}; however, you can
+override the input file name by appending to @var{header}, a
+colon-separated list of input files.  Examples:
+
+@example
+AC_CONFIG_HEADERS(config.h:config.hin)
+AC_CONFIG_HEADERS(defines.h:defs.pre:defines.h.in:defs.post)
+@end example
+
+@noindent
+Doing this allows you to keep your file names acceptable to MS-DOS, or
+to prepend and/or append boilerplate to the file.
+@end defmac
+
+@xref{Configuration Actions}, for more details on @var{header}.
+
+@menu
+* Header Templates::            Input for the configuration headers
+* autoheader Invocation::       How to create configuration templates
+* Autoheader Macros::           How to specify CPP templates
+@end menu
+
+@node Header Templates, autoheader Invocation, Configuration Headers, Configuration Headers
+@subsection Configuration Header Templates
+@cindex Configuration Header Template
+@cindex @file{config.h.in}
+
+Your distribution should contain a template file that looks as you want
+the final header file to look, including comments, with @code{#undef}
+statements which are used as hooks.  For example, suppose your
+@file{configure.ac} makes these calls:
+
+@example
+AC_CONFIG_HEADERS(conf.h)
+AC_CHECK_HEADERS(unistd.h)
+@end example
+
+@noindent
+Then you could have code like the following in @file{conf.h.in}.  On
+systems that have @file{unistd.h}, @code{configure} will @samp{#define}
+@samp{HAVE_UNISTD_H} to 1.  On other systems, the whole line will be
+commented out (in case the system predefines that symbol).
+
+@example
+@group
+/* Define as 1 if you have unistd.h.  */
+#undef HAVE_UNISTD_H
+@end group
+@end example
+
+You can then decode the configuration header using the preprocessor
+directives:
+
+@example
+@group
+#include <conf.h>
+
+#if HAVE_UNISTD_H
+# include <unistd.h>
+#else
+/* We are in trouble. */
+#endif
+@end group
+@end example
+
+The use of old form templates, with @samp{#define} instead of
+@samp{#undef} is strongly discouraged.
+
+Since it is a tedious task to keep a template header up to date, you may
+use @code{autoheader} to generate it, see @ref{autoheader Invocation}.
+
+
+@node autoheader Invocation, Autoheader Macros, Header Templates, Configuration Headers
+@subsection Using @code{autoheader} to Create @file{config.h.in}
+@cindex @code{autoheader}
+
+The @command{autoheader} program can create a template file of C
+@samp{#define} statements for @code{configure} to use.  If
+@file{configure.ac} invokes @code{AC_CONFIG_HEADERS(@var{file})},
+@command{autoheader} creates @file{@var{file}.in}; if multiple file
+arguments are given, the first one is used.  Otherwise,
+@command{autoheader} creates @file{config.h.in}.
+
+In order to do its job, @command{autoheader} needs you to document all
+of the symbols that you might use; i.e., there must be at least one
+@code{AC_DEFINE} or one @code{AC_DEFINE_UNQUOTED} using its third
+argument for each symbol (@pxref{Defining Symbols}).  An additional
+constraint is that the first argument of @code{AC_DEFINE} must be a
+literal.  Note that all symbols defined by Autoconf's built-in tests are
+already documented properly; you only need to document those that you
+define yourself.
+
+You might wonder why @command{autoheader} is needed: after all, why
+would @command{configure} need to ``patch'' a @file{config.h.in} to
+produce a @file{config.h} instead of just creating @file{config.h} from
+scratch?  Well, when everything rocks, the answer is just that we are
+wasting our time maintaining @command{autoheader}: generating
+@file{config.h} directly is all that is needed.  When things go wrong,
+however, you'll be thankful for the existence of @command{autoheader}.
+
+The fact that the symbols are documented is important in order to
+@emph{check} that @file{config.h} makes sense.  The fact that there is a
+well defined list of symbols that should be @code{#define}'d (or not) is
+also important for people who are porting packages to environments where
+@command{configure} cannot be run: they just have to @emph{fill in the
+blanks}.
+
+But let's come back to the point: @command{autoheader}'s invocation@dots{}
+
+If you give @command{autoheader} an argument, it uses that file instead
+of @file{configure.ac} and writes the header file to the standard output
+instead of to @file{config.h.in}.  If you give @command{autoheader} an
+argument of @option{-}, it reads the standard input instead of
+@file{configure.ac} and writes the header file to the standard output.
+
+@code{autoheader} accepts the following options:
+
+@table @option
+@item --help
+@itemx -h
+Print a summary of the command line options and exit.
+
+@item --version
+@itemx -V
+Print the version number of Autoconf and exit.
+
+@item --debug
+@itemx -d
+Don't remove the temporary files.
+
+@item --verbose
+@itemx -v
+Report processing steps.
+
+@item --autoconf-dir=@var{dir}
+@itemx -A @var{dir}
+@evindex AC_MACRODIR
+Override the location where the installed Autoconf data files are looked
+for.  You can also set the @code{AC_MACRODIR} environment variable to a
+directory; this option overrides the environment variable.
+
+This option is rarely needed and dangerous; it is only used when one
+plays with different versions of Autoconf simultaneously.
+
+@item --localdir=@var{dir}
+@itemx -l @var{dir}
+Look for the package files @file{aclocal.m4} and @file{acconfig.h} (but
+not @file{@var{file}.top} and @file{@var{file}.bot}) in directory
+@var{dir} instead of in the current directory.
+
+@item --warnings=@var{category}
+@itemx -W @var{category}
+@evindex WARNINGS
+Report the warnings related to @var{category} (which can actually be a
+comma separated list). Current categories include:
+
+@table @samp
+@item obsolete
+report the uses of obsolete constructs
+
+@item all
+report all the warnings
+
+@item none
+report none
+
+@item error
+treats warnings as errors
+
+@item no-@var{category}
+disable warnings falling into @var{category}
+@end table
+
+@end table
+
+
+
+@node Autoheader Macros,  , autoheader Invocation, Configuration Headers
+@subsection Autoheader Macros
+
+@code{autoheader} scans @file{configure.ac} and figures out which C
+preprocessor symbols it might define.  It knows how to generate
+templates for symbols defined by @code{AC_CHECK_HEADERS},
+@code{AC_CHECK_FUNCS} etc., but if you @code{AC_DEFINE} any additional
+symbol, you must define a template for it.  If there are missing
+templates, @code{autoheader} fails with an error message.
+
+The simplest way to create a template for a @var{symbol} is to supply
+the @var{description} argument to an @samp{AC_DEFINE(@var{symbol})}; see
+@ref{Defining Symbols}.  You may also use one of the following macros.
+
+@defmac AH_VERBATIM (@var{key}, @var{template})
+@maindex AH_VERBATIM
+@maindex VERBATIM
+Tell @code{autoheader} to include the @var{template} as-is in the header
+template file.  This @var{template} is associated with the @var{key},
+which is used to sort all the different templates and guarantee their
+uniqueness.  It should be the symbol that can be @code{AC_DEFINE}'d.
+
+For example:
+
+@example
+AH_VERBATIM([_GNU_SOURCE],
+[/* Enable GNU extensions on systems that have them.  */
+#ifndef _GNU_SOURCE
+# define _GNU_SOURCE
+#endif])
+@end example
+@end defmac
+
+
+@defmac AH_TEMPLATE (@var{key}, @var{description})
+@maindex AH_TEMPLATE
+@maindex TEMPLATE
+Tell @code{autoheader} to generate a template for @var{key}.  This macro
+generates standard templates just like @code{AC_DEFINE} when a
+@var{description} is given.
+
+For example:
+
+@example
+AH_TEMPLATE([CRAY_STACKSEG_END],
+            [Define to one of _getb67, GETB67, getb67
+             for Cray-2 and Cray-YMP systems.  This
+             function is required for alloca.c support
+             on those systems.])
+@end example
+
+@noindent
+will generate the following template, with the description properly
+justified.
+
+@example
+/* Define to one of _getb67, GETB67, getb67 for Cray-2 and
+   Cray-YMP systems. This function is required for alloca.c
+   support on those systems. */
+#undef CRAY_STACKSEG_END
+@end example
+@end defmac
+
+
+@defmac AH_TOP (@var{text})
+@maindex AH_TOP
+@maindex TOP
+Include @var{text} at the top of the header template file.
+@end defmac
+
+
+@defmac AH_BOTTOM (@var{text})
+@maindex AH_BOTTOM
+@maindex BOTTOM
+Include @var{text} at the bottom of the header template file.
+@end defmac
+
+
+@node Configuration Commands, Configuration Links, Configuration Headers, Setup
+@section Running Arbitrary Configuration Commands
+
+You execute arbitrary commands either before, during and after
+@file{config.status} is run.  The three following macros accumulate the
+commands to run when they are called multiple times.
+@code{AC_CONFIG_COMMANDS} replaces the obsolete macro
+@code{AC_OUTPUT_COMMANDS}, see @ref{Obsolete Macros}, for details.
+
+@defmac AC_CONFIG_COMMANDS (@var{tag}@dots{}, @ovar{cmds}, @ovar{init-cmds})
+@maindex CONFIG_COMMANDS
+Specify additional shell commands to run at the end of
+@file{config.status}, and shell commands to initialize any variables
+from @code{configure}.  Associate the commands to the @var{tag}.  Since
+typically the @var{cmds} create a file, @var{tag} should naturally be
+the name of that file.  This macro is one of the instantiating macros,
+see @ref{Configuration Actions}.
+
+Here is an unrealistic example:
+@example
+fubar=42
+AC_CONFIG_COMMANDS(fubar,
+                   [echo this is extra $fubar, and so on.],
+                   [fubar=$fubar])
+@end example
+
+Here is a better one:
+@example
+AC_CONFIG_COMMANDS(time-stamp, [date >time-stamp])
+@end example
+@end defmac
+
+@defmac AC_CONFIG_COMMANDS_PRE (@var{cmds})
+@maindex OUTPUT_COMMANDS_PRE
+Execute the @var{cmds} right before creating @file{config.status}.  A
+typical use is computing values derived from variables built during the
+execution of @code{configure}:
+
+@example
+AC_CONFIG_COMMANDS_PRE(
+[LTLIBOBJS=`echo $LIBOBJS | sed 's/\.o/\.lo/g'`
+AC_SUBST(LTLIBOBJS)])
+@end example
+@end defmac
+
+@defmac AC_CONFIG_COMMANDS_POST (@var{cmds})
+@maindex OUTPUT_COMMANDS_POST
+Execute the @var{cmds} right after creating @file{config.status}.
+@end defmac
+
+
+
+
+@node Configuration Links, Subdirectories, Configuration Commands, Setup
+@section Creating Configuration Links
+
+You may find it convenient to create links whose destinations depend upon
+results of tests.  One can use @code{AC_CONFIG_COMMANDS} but the
+creation of relative symbolic links can be delicate when the package is
+built in another directory than its sources.
+
+@defmac AC_CONFIG_LINKS (@var{dest}:@var{source}@dots{}, @ovar{cmds}, @ovar{init-cmds})
+@maindex CONFIG_LINKS
+@cindex Links
+Make @code{AC_OUTPUT} link each of the existing files @var{source} to
+the corresponding link name @var{dest}.  Makes a symbolic link if
+possible, otherwise a hard link.  The @var{dest} and @var{source} names
+should be relative to the top level source or build directory.  This
+macro is one of the instantiating macros, see @ref{Configuration
+Actions}.
+
+For example, this call:
+
+@example
+AC_CONFIG_LINKS(host.h:config/$machine.h
+                object.h:config/$obj_format.h)
+@end example
+
+@noindent
+creates in the current directory @file{host.h} as a link to
+@file{@var{srcdir}/config/$machine.h}, and @file{object.h} as a
+link to @file{@var{srcdir}/config/$obj_format.h}.
+
+The tempting value @samp{.} for @var{dest} is invalid: it makes it
+impossible for @samp{config.status} to guess the links to establish.
+
+One can then run:
+@example
+./config.status host.h object.h
+@end example
+@noindent
+to create the links.
+@end defmac
+
+
+
+@node Subdirectories, Default Prefix, Configuration Links, Setup
+@section Configuring Other Packages in Subdirectories
+
+In most situations, calling @code{AC_OUTPUT} is sufficient to produce
+@file{Makefile}s in subdirectories.  However, @code{configure} scripts
+that control more than one independent package can use
+@code{AC_CONFIG_SUBDIRS} to run @code{configure} scripts for other
+packages in subdirectories.
+
+@defmac AC_CONFIG_SUBDIRS (@var{dir} @dots{})
+@maindex CONFIG_SUBDIRS
+@ovindex subdirs
+Make @code{AC_OUTPUT} run @code{configure} in each subdirectory
+@var{dir} in the given whitespace-separated list.  Each @var{dir} should
+be a literal, i.e., please do not use:
+
+@example
+if test "$package_foo_enabled" = yes; then
+  $my_subdirs="$my_subdirs foo"
+fi
+AC_CONFIG_SUBDIRS($my_subdirs)
+@end example
+
+@noindent
+because this prevents @samp{./configure --help=recursive} from
+displaying the options of the package @code{foo}.  Rather, you should
+write:
+
+@example
+if test "$package_foo_enabled" = yes then;
+  AC_CONFIG_SUBDIRS(foo)
+fi
+@end example
+
+If a given @var{dir} is not found, no error is reported, so a
+@code{configure} script can configure whichever parts of a large source
+tree are present.  If a given @var{dir} contains @code{configure.gnu},
+it is run instead of @code{configure}. This is for packages that might
+use a non-autoconf script @code{Configure}, which can't be called
+through a wrapper @code{configure} since it would be the same file on
+case-insensitive filesystems. Likewise, if a @var{dir} contains
+@file{configure.ac} but no @code{configure}, the Cygnus @code{configure}
+script found by @code{AC_CONFIG_AUX_DIR} is used.
+
+The subdirectory @code{configure} scripts are given the same command
+line options that were given to this @code{configure} script, with minor
+changes if needed (e.g., to adjust a relative path for the cache file or
+source directory).  This macro also sets the output variable
+@code{subdirs} to the list of directories @samp{@var{dir} @dots{}}.
+@file{Makefile} rules can use this variable to determine which
+subdirectories to recurse into.  This macro may be called multiple
+times.
+@end defmac
+
+@node Default Prefix,  , Subdirectories, Setup
+@section Default Prefix
+
+By default, @code{configure} sets the prefix for files it installs to
+@file{/usr/local}.  The user of @code{configure} can select a different
+prefix using the @option{--prefix} and @option{--exec-prefix} options.
+There are two ways to change the default: when creating
+@code{configure}, and when running it.
+
+Some software packages might want to install in a directory besides
+@file{/usr/local} by default.  To accomplish that, use the
+@code{AC_PREFIX_DEFAULT} macro.
+
+@defmac AC_PREFIX_DEFAULT (@var{prefix})
+@maindex PREFIX_DEFAULT
+Set the default installation prefix to @var{prefix} instead of
+@file{/usr/local}.
+@end defmac
+
+It may be convenient for users to have @code{configure} guess the
+installation prefix from the location of a related program that they
+have already installed.  If you wish to do that, you can call
+@code{AC_PREFIX_PROGRAM}.
+
+@defmac AC_PREFIX_PROGRAM (@var{program})
+@maindex PREFIX_PROGRAM
+If the user did not specify an installation prefix (using the
+@option{--prefix} option), guess a value for it by looking for
+@var{program} in @code{PATH}, the way the shell does.  If @var{program}
+is found, set the prefix to the parent of the directory containing
+@var{program}; otherwise leave the prefix specified in
+@file{Makefile.in} unchanged.  For example, if @var{program} is
+@code{gcc} and the @code{PATH} contains @file{/usr/local/gnu/bin/gcc},
+set the prefix to @file{/usr/local/gnu}.
+@end defmac
+
+
+
+@c ======================================================== Existing tests
+
+@node Existing Tests, Writing Tests, Setup, Top
+@chapter Existing Tests
+
+These macros test for particular system features that packages might
+need or want to use.  If you need to test for a kind of feature that
+none of these macros check for, you can probably do it by calling
+primitive test macros with appropriate arguments (@pxref{Writing
+Tests}).
+
+These tests print messages telling the user which feature they're
+checking for, and what they find.  They cache their results for future
+@code{configure} runs (@pxref{Caching Results}).
+
+Some of these macros set output variables.  @xref{Makefile
+Substitutions}, for how to get their values.  The phrase ``define
+@var{name}'' is used below as a shorthand to mean ``define C
+preprocessor symbol @var{name} to the value 1''.  @xref{Defining
+Symbols}, for how to get those symbol definitions into your program.
+
+@menu
+* Common Behavior::             Macros' standard schemes
+* Alternative Programs::        Selecting between alternative programs
+* Files::                       Checking for the existence of files
+* Libraries::                   Library archives that might be missing
+* Library Functions::           C library functions that might be missing
+* Header Files::                Header files that might be missing
+* Declarations::                Declarations that may be missing
+* Structures::                  Structures or members that might be missing
+* Types::                       Types that might be missing
+* Compilers and Preprocessors::  Checking for compiling programs
+* System Services::             Operating system services
+* UNIX Variants::               Special kludges for specific UNIX variants
+@end menu
+
+@node Common Behavior, Alternative Programs, Existing Tests, Existing Tests
+@section Common Behavior
+
+Much effort has been expended to make Autoconf easy to learn.  The most
+obvious way to reach this goal is simply to enforce standard interfaces
+and behaviors, avoiding exceptions as much as possible.  Because of
+history and inertia, unfortunately, there are still too many exceptions
+in Autoconf; nevertheless, this section describes some of the common
+rules.
+
+@menu
+* Standard Symbols::            Symbols defined by the macros
+* Default Includes::            Includes used by the generic macros
+@end menu
+
+@node Standard Symbols, Default Includes, Common Behavior, Common Behavior
+@subsection Standard Symbols
+
+All the generic macros that @code{AC_DEFINE} a symbol as a result of
+their test transform their @var{argument}s to a standard alphabet.
+First, @var{argument} is converted to upper case and any asterisks
+(@samp{*}) are each converted to @samp{P}.  Any remaining characters
+that are not alphanumeric are converted to underscores.
+
+For instance,
+
+@example
+AC_CHECK_TYPES(struct $Expensive*)
+@end example
+
+@noindent
+will define the symbol @samp{HAVE_STRUCT__EXPENSIVEP} if the check succeeds.
+
+
+@node Default Includes,  , Standard Symbols, Common Behavior
+@subsection Default Includes
+@cindex Includes, default
+
+Several tests depend upon a set of header files.  Since these headers
+are not universally available, tests actually have to provide a set of
+protected includes, such as:
+
+@example
+@group
+#if TIME_WITH_SYS_TIME
+# include <sys/time.h>
+# include <time.h>
+#else
+# if HAVE_SYS_TIME_H
+#  include <sys/time.h>
+# else
+#  include <time.h>
+# endif
+#endif
+@end group
+@end example
+
+@noindent
+Unless you know exactly what you are doing, you should avoid using
+unconditional includes, and check the existence of the headers you
+include beforehand (@pxref{Header Files}).
+
+Most generic macros provide the following default set of includes:
+
+@example
+@group
+#include <stdio.h>
+#if HAVE_SYS_TYPES_H
+# include <sys/types.h>
+#endif
+#if HAVE_SYS_STAT_H
+# include <sys/stat.h>
+#endif
+#if STDC_HEADERS
+# include <stdlib.h>
+# include <stddef.h>
+#else
+# if HAVE_STDLIB_H
+#  include <stdlib.h>
+# endif
+#endif
+#if HAVE_STRING_H
+# if !STDC_HEADERS && HAVE_MEMORY_H
+#  include <memory.h>
+# endif
+# include <string.h>
+#endif
+#if HAVE_STRINGS_H
+# include <strings.h>
+#endif
+#if HAVE_INTTYPES_H
+# include <inttypes.h>
+#else
+# if HAVE_STDINT_H
+#  include <stdint.h>
+# endif
+#endif
+#if HAVE_UNISTD_H
+# include <unistd.h>
+#endif
+@end group
+@end example
+
+If the default includes are used, then Autoconf will automatically check
+for the presence of these headers and their compatibility, i.e., you
+don't need to run @code{AC_HEADERS_STDC}, nor check for @file{stdlib.h}
+etc.
+
+These headers are checked for in the same order as they are included.
+For instance, on some systems @file{string.h} and @file{strings.h} both
+exist, but conflict.  Then @code{HAVE_STRING_H} will be defined, but
+@code{HAVE_STRINGS_H} won't.
+
+@node Alternative Programs, Files, Common Behavior, Existing Tests
+@section Alternative Programs
+@cindex Programs, checking
+
+These macros check for the presence or behavior of particular programs.
+They are used to choose between several alternative programs and to
+decide what to do once one has been chosen.  If there is no macro
+specifically defined to check for a program you need, and you don't need
+to check for any special properties of it, then you can use one of the
+general program-check macros.
+
+@menu
+* Particular Programs::         Special handling to find certain programs
+* Generic Programs::            How to find other programs
+@end menu
+
+@node Particular Programs, Generic Programs, Alternative Programs, Alternative Programs
+@subsection Particular Program Checks
+
+These macros check for particular programs---whether they exist, and
+in some cases whether they support certain features.
+
+@defmac AC_PROG_AWK
+@maindex PROG_AWK
+@ovindex AWK
+Check for @code{mawk}, @code{gawk}, @code{nawk}, and @code{awk}, in that
+order, and set output variable @code{AWK} to the first one that is found.
+It tries @code{mawk} first because that is reported to be the
+fastest implementation.
+@end defmac
+
+
+@defmac AC_PROG_EGREP
+@ovindex EGREP
+Check for @code{grep -E}, @code{egrep} in that
+order, and set output variable @code{EGREP} to the first one that is found.
+@end defmac
+
+
+@defmac AC_PROG_FGREP
+@ovindex FGREP
+Check for @code{grep -F}, @code{fgrep} in that
+order, and set output variable @code{FGREP} to the first one that is found.
+@end defmac
+
+
+@defmac AC_PROG_GREP
+@ovindex GREP
+Check for @code{grep}, @code{ggrep} in that
+order, and set output variable @code{GREP} to the first one that is found.
+@end defmac
+
+
+@defmac AC_PROG_INSTALL
+@maindex PROG_INSTALL
+@ovindex INSTALL
+@ovindex INSTALL_PROGRAM
+@ovindex INSTALL_DATA
+@ovindex INSTALL_SCRIPT
+Set output variable @code{INSTALL} to the path of a @sc{bsd} compatible
+@code{install} program, if one is found in the current @code{PATH}.
+Otherwise, set @code{INSTALL} to @samp{@var{dir}/install-sh -c},
+checking the directories specified to @code{AC_CONFIG_AUX_DIR} (or its
+default directories) to determine @var{dir} (@pxref{Output}).  Also set
+the variables @code{INSTALL_PROGRAM} and @code{INSTALL_SCRIPT} to
+@samp{$@{INSTALL@}} and @code{INSTALL_DATA} to @samp{$@{INSTALL@} -m 644}.
+
+This macro screens out various instances of @code{install} known not to
+work.  It prefers to find a C program rather than a shell script, for
+speed.  Instead of @file{install-sh}, it can also use @file{install.sh},
+but that name is obsolete because some @code{make} programs have a rule
+that creates @file{install} from it if there is no @file{Makefile}.
+
+Autoconf comes with a copy of @file{install-sh} that you can use.  If
+you use @code{AC_PROG_INSTALL}, you must include either
+@file{install-sh} or @file{install.sh} in your distribution, or
+@code{configure} will produce an error message saying it can't find
+them---even if the system you're on has a good @code{install} program.
+This check is a safety measure to prevent you from accidentally leaving
+that file out, which would prevent your package from installing on
+systems that don't have a @sc{bsd}-compatible @code{install} program.
+
+If you need to use your own installation program because it has features
+not found in standard @code{install} programs, there is no reason to use
+@code{AC_PROG_INSTALL}; just put the file name of your program into your
+@file{Makefile.in} files.
+@end defmac
+
+@defmac AC_PROG_LEX
+@maindex PROG_LEX
+@ovindex LEX
+@ovindex LEXLIB
+@cvindex YYTEXT_POINTER
+@ovindex LEX_OUTPUT_ROOT
+If @code{flex} is found, set output variable @code{LEX} to @samp{flex}
+and @code{LEXLIB} to @option{-lfl}, if that library is in a standard
+place.  Otherwise set @code{LEX} to @samp{lex} and @code{LEXLIB} to
+@option{-ll}.
+
+Define @code{YYTEXT_POINTER} if @code{yytext} is a @samp{char *} instead
+of a @samp{char []}.  Also set output variable @code{LEX_OUTPUT_ROOT} to
+the base of the file name that the lexer generates; usually
+@file{lex.yy}, but sometimes something else.  These results vary
+according to whether @code{lex} or @code{flex} is being used.
+
+You are encouraged to use Flex in your sources, since it is both more
+pleasant to use than plain Lex and the C source it produces is portable.
+In order to ensure portability, however, you must either provide a
+function @code{yywrap} or, if you don't use it (e.g., your scanner has
+no @samp{#include}-like feature), simply include a @samp{%noyywrap}
+statement in the scanner's source.  Once this done, the scanner is
+portable (unless @emph{you} felt free to use nonportable constructs) and
+does not depend on any library.  In this case, and in this case only, it
+is suggested that you use this Autoconf snippet:
+
+@example
+AC_PROG_LEX
+if test "$LEX" != flex; then
+  LEX="$SHELL $missing_dir/missing flex"
+  AC_SUBST(LEX_OUTPUT_ROOT, lex.yy)
+  AC_SUBST(LEXLIB, '')
+fi
+@end example
+
+The shell script @command{missing} can be found in the Automake
+distribution.
+
+To ensure backward compatibility, Automake's @code{AM_PROG_LEX} invokes
+(indirectly) this macro twice, which will cause an annoying but benign
+``@code{AC_PROG_LEX} invoked multiple times'' warning.  Future versions
+of Automake will fix this issue, meanwhile, just ignore this message.
+@end defmac
+
+@defmac AC_PROG_LN_S
+@maindex PROG_LN_S
+@ovindex LN_S
+If @samp{ln -s} works on the current file system (the operating system
+and file system support symbolic links), set the output variable
+@code{LN_S} to @samp{ln -s}; otherwise, if @samp{ln} works, set
+@code{LN_S} to @samp{ln} and otherwise set it to @samp{cp -p}.
+
+If you make a link a directory other than the current directory, its
+meaning depends on whether @samp{ln} or @samp{ln -s} is used.  To safely
+create links using @samp{$(LN_S)}, either find out which form is used
+and adjust the arguments, or always invoke @code{ln} in the directory
+where the link is to be created.
+
+In other words, it does not work to do:
+@example
+$(LN_S) foo /x/bar
+@end example
+
+Instead, do:
+
+@example
+(cd /x && $(LN_S) foo bar)
+@end example
+@end defmac
+
+@defmac AC_PROG_RANLIB
+@maindex PROG_RANLIB
+@ovindex RANLIB
+Set output variable @code{RANLIB} to @samp{ranlib} if @code{ranlib}
+is found, and otherwise to @samp{:} (do nothing).
+@end defmac
+
+@defmac AC_PROG_YACC
+@maindex PROG_YACC
+@ovindex YACC
+If @code{byacc} is found, set @code{YACC} to @samp{byacc}.
+Otherwise, if @code{bison} is found,
+set output variable @code{YACC} to @samp{bison -y}.
+Finally, if neither @code{byacc} or @code{bison} is found,
+set @code{YACC} to @samp{yacc}.
+@end defmac
+
+@node Generic Programs,  , Particular Programs, Alternative Programs
+@subsection Generic Program and File Checks
+
+These macros are used to find programs not covered by the ``particular''
+test macros.  If you need to check the behavior of a program as well as
+find out whether it is present, you have to write your own test for it
+(@pxref{Writing Tests}).  By default, these macros use the environment
+variable @code{PATH}.  If you need to check for a program that might not
+be in the user's @code{PATH}, you can pass a modified path to use
+instead, like this:
+
+@example
+AC_PATH_PROG(INETD, inetd, /usr/libexec/inetd,
+  $PATH:/usr/libexec:/usr/sbin:/usr/etc:etc)
+@end example
+
+You are strongly encouraged to declare the @var{variable} passed to
+@code{AC_CHECK_PROG} etc. as precious, @xref{Setting Output Variables},
+@code{AC_ARG_VAR}, for more details.
+
+@defmac AC_CHECK_PROG (@var{variable}, @var{prog-to-check-for}, @var{value-if-found}, @ovar{value-if-not-found}, @ovar{path},  @ovar{reject})
+@maindex CHECK_PROG
+Check whether program @var{prog-to-check-for} exists in @code{PATH}.  If
+it is found, set @var{variable} to @var{value-if-found}, otherwise to
+@var{value-if-not-found}, if given.  Always pass over @var{reject} (an
+absolute file name) even if it is the first found in the search path; in
+that case, set @var{variable} using the absolute file name of the
+@var{prog-to-check-for} found that is not @var{reject}.  If
+@var{variable} was already set, do nothing.  Calls @code{AC_SUBST} for
+@var{variable}.
+@end defmac
+
+@defmac AC_CHECK_PROGS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
+@maindex CHECK_PROGS
+Check for each program in the whitespace-separated list
+@var{progs-to-check-for} exists on the @code{PATH}.  If it is found, set
+@var{variable} to the name of that program.  Otherwise, continue
+checking the next program in the list.  If none of the programs in the
+list are found, set @var{variable} to @var{value-if-not-found}; if
+@var{value-if-not-found} is not specified, the value of @var{variable}
+is not changed.  Calls @code{AC_SUBST} for @var{variable}.
+@end defmac
+
+@defmac AC_CHECK_TOOL (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
+@maindex CHECK_TOOL
+Like @code{AC_CHECK_PROG}, but first looks for @var{prog-to-check-for}
+with a prefix of the host type as determined by
+@code{AC_CANONICAL_HOST}, followed by a dash (@pxref{Canonicalizing}).
+For example, if the user runs @samp{configure --host=i386-gnu}, then
+this call:
+@example
+AC_CHECK_TOOL(RANLIB, ranlib, :)
+@end example
+@noindent
+sets @code{RANLIB} to @file{i386-gnu-ranlib} if that program exists in
+@code{PATH}, or otherwise to @samp{ranlib} if that program exists in
+@code{PATH}, or to @samp{:} if neither program exists.
+@end defmac
+
+@defmac AC_CHECK_TOOLS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
+@maindex CHECK_TOOLS
+Like @code{AC_CHECK_TOOL}, each of the tools in the list @var{progs-to-check-for} are
+checked with a prefix of the host type as determined by @code{AC_CANONICAL_HOST},
+followed by a dash (@pxref{Canonicalizing}). If none of the tools can be found with a
+prefix, then the first one without a prefix is used. If a tool is found, set
+@var{variable} to the name of that program. If none of the tools in the
+list are found, set @var{variable} to @var{value-if-not-found}; if
+@var{value-if-not-found} is not specified, the value of @var{variable}
+is not changed.  Calls @code{AC_SUBST} for @var{variable}.
+@end defmac
+
+@defmac AC_PATH_PROG (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
+@maindex PATH_PROG
+Like @code{AC_CHECK_PROG}, but set @var{variable} to the entire
+path of @var{prog-to-check-for} if found.
+@end defmac
+
+@defmac AC_PATH_PROGS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
+@maindex PATH_PROGS
+Like @code{AC_CHECK_PROGS}, but if any of @var{progs-to-check-for}
+are found, set @var{variable} to the entire path of the program
+found.
+@end defmac
+
+@defmac AC_PATH_TOOL (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
+@maindex PATH_TOOL
+Like @code{AC_CHECK_TOOL}, but set @var{variable} to the entire
+path of the program if it is found.
+@end defmac
+
+
+@node Files, Libraries, Alternative Programs, Existing Tests
+@section Files
+@cindex File, checking
+
+You might also need to check for the existence of files.  Before using
+these macros, ask yourself whether a run time test might not be a better
+solution.  Be aware that, like most Autoconf macros, they test a feature
+of the host machine, and therefore, they die when cross-compiling.
+
+@defmac AC_CHECK_FILE (@var{file}, @ovar{action-if-found}, @ovar{action-if-not-found})
+@maindex CHECK_FILE
+Check whether file @var{file} exists on the native system.  If it is
+found, execute @var{action-if-found}, otherwise do
+@var{action-if-not-found}, if given.
+@end defmac
+
+@defmac AC_CHECK_FILES (@var{files}, @ovar{action-if-found}, @ovar{action-if-not-found})
+@maindex CHECK_FILES
+Executes @code{AC_CHECK_FILE} once for each file listed in @var{files}.
+Additionally, defines @samp{HAVE_@var{file}} (@pxref{Standard Symbols})
+for each file found.
+@end defmac
+
+
+@node Libraries, Library Functions, Files, Existing Tests
+@section Library Files
+@cindex Library, checking
+
+The following macros check for the presence of certain C, C++ or Fortran
+77 library archive files.
+
+@defmac AC_CHECK_LIB (@var{library}, @var{function}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})
+@maindex CHECK_LIB
+Depending on the current language(@pxref{Language Choice}), try to
+ensure that the C, C++, or Fortran 77 function @var{function} is
+available by checking whether a test program can be linked with the
+library @var{library} to get the function.  @var{library} is the base
+name of the library; e.g., to check for @option{-lmp}, use @samp{mp} as
+the @var{library} argument.
+
+@var{action-if-found} is a list of shell commands to run if the link
+with the library succeeds; @var{action-if-not-found} is a list of shell
+commands to run if the link fails.  If @var{action-if-found} is not
+specified, the default action will prepend @option{-l@var{library}} to
+@code{LIBS} and define @samp{HAVE_LIB@var{library}} (in all
+capitals). This macro is intended to support building of @code{LIBS} in
+a right-to-left (least-dependent to most-dependent) fashion such that
+library dependencies are satisfied as a natural side-effect of
+consecutive tests. Some linkers are very sensitive to library ordering
+so the order in which @code{LIBS} is generated is important to reliable
+detection of libraries.
+
+If linking with @var{library} results in unresolved symbols that would
+be resolved by linking with additional libraries, give those libraries
+as the @var{other-libraries} argument, separated by spaces:
+e.g. @option{-lXt -lX11}.  Otherwise, this macro will fail to detect
+that @var{library} is present, because linking the test program will
+always fail with unresolved symbols. The @var{other-libraries} argument
+should be limited to cases where it is desirable to test for one library
+in the presence of another that is not already in @code{LIBS}.
+@end defmac
+
+
+@defmac AC_SEARCH_LIBS (@var{function}, @var{search-libs}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})
+@maindex SEARCH_LIBS
+Search for a library defining @var{function} if it's not already
+available.  This equates to calling @code{AC_TRY_LINK_FUNC} first
+with no libraries, then for each library listed in @var{search-libs}.
+
+Add @option{-l@var{library}} to @code{LIBS} for the first library found
+to contain @var{function}, and run @var{action-if-found}.  If the
+function is not found, run @var{action-if-not-found}.
+
+If linking with @var{library} results in unresolved symbols that would
+be resolved by linking with additional libraries, give those libraries
+as the @var{other-libraries} argument, separated by spaces:
+e.g. @option{-lXt -lX11}.  Otherwise, this macro will fail to detect
+that @var{function} is present, because linking the test program will
+always fail with unresolved symbols.
+@end defmac
+
+
+
+@node Library Functions, Header Files, Libraries, Existing Tests
+@section Library Functions
+
+The following macros check for particular C library functions.
+If there is no macro specifically defined to check for a function you need,
+and you don't need to check for any special properties of
+it, then you can use one of the general function-check macros.
+
+@menu
+* Function Portability::        Pitfalls with usual functions
+* Particular Functions::        Special handling to find certain functions
+* Generic Functions::           How to find other functions
+@end menu
+
+@node Function Portability, Particular Functions, Library Functions, Library Functions
+@subsection Portability of Classical Functions
+
+Most usual functions can either be missing, or be buggy, or be limited
+on some architectures.  This section tries to make an inventory of these
+portability issues.  By definition, this list will always require
+additions, please help us keeping it as complete as possible
+
+@table @code
+
+@item unlink
+The @sc{posix} spec says that @code{unlink} causes the given files to be
+removed only after there are no more open file handles for it.  Not all
+OS's support this behaviour though.  So even on systems that provide
+@code{unlink}, you cannot portably assume it is OK to call it on files
+that are open.  For example, on Windows 9x and ME, such a call would fail;
+on DOS it could even lead to file system corruption, as the file might end
+up being written to after the OS has removed it.
+
+@end table
+
+
+@node Particular Functions, Generic Functions, Function Portability, Library Functions
+@subsection Particular Function Checks
+@cindex Function, checking
+
+These macros check for particular C functions---whether they exist, and
+in some cases how they respond when given certain arguments.
+
+@defmac AC_FUNC_ALLOCA
+@maindex FUNC_ALLOCA
+@cvindex C_ALLOCA
+@cvindex HAVE_ALLOCA_H
+@ovindex ALLOCA
+Check how to get @code{alloca}.  Tries to get a builtin version by
+checking for @file{alloca.h} or the predefined C preprocessor macros
+@code{__GNUC__} and @code{_AIX}.  If this macro finds @file{alloca.h},
+it defines @code{HAVE_ALLOCA_H}.
+
+If those attempts fail, it looks for the function in the standard C
+library.  If any of those methods succeed, it defines
+@code{HAVE_ALLOCA}.  Otherwise, it sets the output variable
+@code{ALLOCA} to @samp{alloca.o} and defines @code{C_ALLOCA} (so
+programs can periodically call @samp{alloca(0)} to garbage collect).
+This variable is separate from @code{LIBOBJS} so multiple programs can
+share the value of @code{ALLOCA} without needing to create an actual
+library, in case only some of them use the code in @code{LIBOBJS}.
+
+This macro does not try to get @code{alloca} from the System V R3
+@file{libPW} or the System V R4 @file{libucb} because those libraries
+contain some incompatible functions that cause trouble.  Some versions
+do not even contain @code{alloca} or contain a buggy version.  If you
+still want to use their @code{alloca}, use @code{ar} to extract
+@file{alloca.o} from them instead of compiling @file{alloca.c}.
+
+Source files that use @code{alloca} should start with a piece of code
+like the following, to declare it properly.  In some versions of AIX,
+the declaration of @code{alloca} must precede everything else except for
+comments and preprocessor directives.  The @code{#pragma} directive is
+indented so that pre-@sc{ansi} C compilers will ignore it, rather than
+choke on it.
+
+@example
+@group
+/* AIX requires this to be the first thing in the file.  */
+#ifndef __GNUC__
+# if HAVE_ALLOCA_H
+#  include <alloca.h>
+# else
+#  ifdef _AIX
+ #pragma alloca
+#  else
+#   ifndef alloca /* predefined by HP cc +Olibcalls */
+char *alloca ();
+#   endif
+#  endif
+# endif
+#endif
+@end group
+@end example
+@end defmac
+
+@defmac AC_FUNC_CHOWN
+@maindex FUNC_CHOWN
+If the @code{chown} function is available and works (in particular, it
+should accept @option{-1} for @code{uid} and @code{gid}), define
+@code{HAVE_CHOWN}.
+@end defmac
+
+
+@defmac AC_FUNC_CLOSEDIR_VOID
+@maindex FUNC_CLOSEDIR_VOID
+@cvindex CLOSEDIR_VOID
+If the @code{closedir} function does not return a meaningful value,
+define @code{CLOSEDIR_VOID}.  Otherwise, callers ought to check its
+return value for an error indicator.
+@end defmac
+
+@defmac AC_FUNC_ERROR_AT_LINE
+@maindex FUNC_ERROR_AT_LINE
+If the @code{error_at_line} function is not found, require an
+@code{AC_LIBOBJ} replacement of @samp{error}.
+@end defmac
+
+@defmac AC_FUNC_FNMATCH
+@maindex FUNC_FNMATCH
+If the @code{fnmatch} function is available and works (unlike the one on
+Solaris 2.4), define @code{HAVE_FNMATCH}.
+@end defmac
+
+@defmac AC_FUNC_FORK
+@maindex FUNC_FORK
+@cvindex HAVE_VFORK_H
+@cvindex HAVE_WORKING_FORK
+@cvindex HAVE_WORKING_VFORK
+@cvindex vfork
+This macro checks for the @code{fork} and @code{vfork} functions. If a
+working @code{fork} is found, define @code{HAVE_WORKING_FORK}. This macro
+checks whether @code{fork} is just a stub by trying to run it.
+
+If @file{vfork.h} is found, define @code{HAVE_VFORK_H}. If a working
+@code{vfork} is found, define @code{HAVE_WORKING_VFORK}. Otherwise,
+define @code{vfork} to be @code{fork} for backward compatibility with
+previous versions of @command{autoconf}. This macro checks for several known
+errors in implementations of @code{vfork} and considers the system to not
+have a working @code{vfork} if it detects any of them. It is not considered
+to be an implementation error if a child's invocation of @code{signal}
+modifies the parent's signal handler, since child processes rarely change
+their signal handlers.
+
+Since this macro defines @code{vfork} only for backward compatibility with
+previous versions of @command{autoconf} you're encouraged to define it
+yourself in new code:
+@example
+@group
+#if !HAVE_WORKING_VFORK
+# define vfork fork
+#endif
+@end group
+@end example
+@end defmac
+
+@defmac AC_FUNC_FSEEKO
+@maindex FUNC_FSEEKO
+@cvindex _LARGEFILE_SOURCE
+If the @code{fseeko} function is available, define @code{HAVE_FSEEKO}.
+Define @code{_LARGEFILE_SOURCE} if necessary.
+@end defmac
+
+@defmac AC_FUNC_GETGROUPS
+@maindex FUNC_GETGROUPS
+@ovindex GETGROUPS_LIBS
+If the @code{getgroups} function is available and works (unlike on
+Ultrix 4.3, where @samp{getgroups (0, 0)} always fails), define
+@code{HAVE_GETGROUPS}.  Set @code{GETGROUPS_LIBS} to any libraries
+needed to get that function.  This macro runs @code{AC_TYPE_GETGROUPS}.
+@end defmac
+
+@defmac AC_FUNC_GETLOADAVG
+@maindex FUNC_GETLOADAVG
+@cvindex SVR4
+@cvindex DGUX
+@cvindex UMAX
+@cvindex UMAX4_3
+@cvindex NLIST_STRUCT
+@cvindex NLIST_NAME_UNION
+@cvindex GETLODAVG_PRIVILEGED
+@cvindex NEED_SETGID
+@cvindex C_GETLOADAVG
+@ovindex LIBOBJS
+@ovindex NEED_SETGID
+@ovindex KMEM_GROUP
+@ovindex GETLOADAVG_LIBS
+Check how to get the system load averages.  If the system has the
+@code{getloadavg} function, define @code{HAVE_GETLOADAVG}, and set
+@code{GETLOADAVG_LIBS} to any libraries needed to get that function.
+Also add @code{GETLOADAVG_LIBS} to @code{LIBS}.
+
+Otherwise, require an @code{AC_LIBOBJ} replacement (@file{getloadavg.c})
+of @samp{getloadavg}, and possibly define several other C preprocessor
+macros and output variables:
+
+@enumerate
+@item
+Define @code{C_GETLOADAVG}.
+
+@item
+Define @code{SVR4}, @code{DGUX}, @code{UMAX}, or @code{UMAX4_3} if on
+those systems.
+
+@item
+If @file{nlist.h} is found, define @code{NLIST_STRUCT}.
+
+@item
+If @samp{struct nlist} has an @samp{n_un.n_name} member, define
+@code{HAVE_STRUCT_NLIST_N_UN_N_NAME}.  The obsolete symbol
+@code{NLIST_NAME_UNION} is still defined, but do not depend upon it.
+
+@item
+Programs may need to be installed setgid (or setuid) for
+@code{getloadavg} to work.  In this case, define
+@code{GETLOADAVG_PRIVILEGED}, set the output variable @code{NEED_SETGID}
+to @samp{true} (and otherwise to @samp{false}), and set
+@code{KMEM_GROUP} to the name of the group that should own the installed
+program.
+@end enumerate
+@end defmac
+
+@defmac AC_FUNC_GETMNTENT
+@maindex FUNC_GETMNTENT
+@cvindex HAVE_GETMNTENT
+Check for @code{getmntent} in the @file{sun}, @file{seq}, and @file{gen}
+libraries, for Irix 4, PTX, and Unixware, respectively.  Then, if
+@code{getmntent} is available, define @code{HAVE_GETMNTENT}.
+@end defmac
+
+@defmac AC_FUNC_GETPGRP
+@maindex FUNC_GETPGRP
+@cvindex GETPGRP_VOID
+If @code{getpgrp} takes no argument (the @sc{posix.1} version), define
+@code{GETPGRP_VOID}.  Otherwise, it is the @sc{bsd} version, which takes
+a process ID as an argument.  This macro does not check whether
+@code{getpgrp} exists at all; if you need to work in that situation,
+first call @code{AC_CHECK_FUNC} for @code{getpgrp}.
+@end defmac
+
+@defmac AC_FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK
+@maindex FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK
+@cvindex LSTAT_FOLLOWS_SLASHED_SYMLINK
+If @file{link} is a symbolic link, then @code{lstat} should treat
+@file{link/} the same as @file{link/.}.  However, many older
+@code{lstat} implementations incorrectly ignore trailing slashes.
+
+It is safe to assume that if @code{lstat} incorrectly ignores
+trailing slashes, then other symbolic-link-aware functions like
+@code{unlink} and @code{unlink} also incorrectly ignore trailing slashes.
+
+If @code{lstat} behaves properly, define
+@code{LSTAT_FOLLOWS_SLASHED_SYMLINK}, otherwise require an
+@code{AC_LIBOBJ} replacement of @code{lstat}.
+@end defmac
+
+@defmac AC_FUNC_MALLOC
+@maindex FUNC_MALLOC
+If the @code{malloc} works correctly (@samp{malloc (0)} returns a valid
+pointer), define @code{HAVE_MALLOC}.
+@end defmac
+
+@defmac AC_FUNC_MEMCMP
+@maindex FUNC_MEMCMP
+@ovindex LIBOBJS
+If the @code{memcmp} function is not available, or does not work on
+8-bit data (like the one on SunOS 4.1.3), or fails when comparing 16
+bytes or more and with at least one buffer not starting on a 4-byte
+boundary (such as the one on NeXT x86 OpenStep), require an
+@code{AC_LIBOBJ} replacement for @samp{memcmp}.
+@end defmac
+
+@defmac AC_FUNC_MKTIME
+@maindex FUNC_MKTIME
+@ovindex LIBOBJS
+If the @code{mktime} function is not available, or does not work
+correctly, require an @code{AC_LIBOBJ} replacement for @samp{mktime}.
+@end defmac
+
+@defmac AC_FUNC_MMAP
+@maindex FUNC_MMAP
+@cvindex HAVE_MMAP
+If the @code{mmap} function exists and works correctly, define
+@code{HAVE_MMAP}.  Only checks private fixed mapping of already-mapped
+memory.
+@end defmac
+
+@defmac AC_FUNC_OBSTACK
+@maindex FUNC_OBSTACK
+@cvindex HAVE_OBSTACK
+@cindex obstack
+If the obstacks are found, define @code{HAVE_OBSTACK}, else require an
+@code{AC_LIBOBJ} replacement for @samp{obstack}.
+@end defmac
+
+@defmac AC_FUNC_SELECT_ARGTYPES
+@maindex FUNC_SELECT_ARGTYPES
+@cvindex SELECT_TYPE_ARG1
+@cvindex SELECT_TYPE_ARG234
+@cvindex SELECT_TYPE_ARG5
+Determines the correct type to be passed for each of the
+@code{select} function's arguments, and defines those types
+in @code{SELECT_TYPE_ARG1}, @code{SELECT_TYPE_ARG234}, and
+@code{SELECT_TYPE_ARG5} respectively.  @code{SELECT_TYPE_ARG1} defaults
+to @samp{int}, @code{SELECT_TYPE_ARG234} defaults to @samp{int *},
+and @code{SELECT_TYPE_ARG5} defaults to @samp{struct timeval *}.
+@end defmac
+
+@defmac AC_FUNC_SETPGRP
+@maindex FUNC_SETPGRP
+@cvindex SETPGRP_VOID
+If @code{setpgrp} takes no argument (the @sc{posix.1} version), define
+@code{SETPGRP_VOID}.  Otherwise, it is the @sc{bsd} version, which takes
+two process IDs as arguments.  This macro does not check whether
+@code{setpgrp} exists at all; if you need to work in that situation,
+first call @code{AC_CHECK_FUNC} for @code{setpgrp}.
+@end defmac
+
+@defmac AC_FUNC_STAT
+@defmacx AC_FUNC_LSTAT
+@maindex FUNC_STAT
+@maindex FUNC_LSTAT
+@cvindex HAVE_STAT_EMPTY_STRING_BUG
+@cvindex HAVE_LSTAT_EMPTY_STRING_BUG
+Determine whether @code{stat} or @code{lstat} have the bug that it
+succeeds when given the zero-length file name argument.  The @code{stat}
+and @code{lstat} from SunOS 4.1.4 and the Hurd (as of 1998-11-01) do
+this.
+
+If it does, then define @code{HAVE_STAT_EMPTY_STRING_BUG} (or
+@code{HAVE_LSTAT_EMPTY_STRING_BUG}) and ask for an @code{AC_LIBOBJ}
+replacement of it.
+@end defmac
+
+@defmac AC_FUNC_SETVBUF_REVERSED
+@maindex FUNC_SETVBUF_REVERSED
+@cvindex SETVBUF_REVERSED
+If @code{setvbuf} takes the buffering type as its second argument and
+the buffer pointer as the third, instead of the other way around, define
+@code{SETVBUF_REVERSED}.
+@end defmac
+
+@defmac AC_FUNC_STRCOLL
+@maindex FUNC_STRCOLL
+@cvindex HAVE_STRCOLL
+If the @code{strcoll} function exists and works correctly, define
+@code{HAVE_STRCOLL}.  This does a bit more than
+@samp{AC_CHECK_FUNCS(strcoll)}, because some systems have incorrect
+definitions of @code{strcoll} that should not be used.
+@end defmac
+
+@defmac AC_FUNC_STRTOD
+@maindex FUNC_STRTOD
+@ovindex POW_LIB
+If the @code{strtod} function does not exist or doesn't work correctly,
+ask for an @code{AC_LIBOBJ} replacement of @samp{strtod}.  In this case,
+because @file{strtod.c} is likely to need @samp{pow}, set the output
+variable @code{POW_LIB} to the extra library needed.
+@end defmac
+
+@defmac AC_FUNC_STRERROR_R
+@maindex FUNC_STRERROR_R
+@cvindex HAVE_STRERROR_R
+@cvindex HAVE_WORKING_STRERROR_R
+If @code{strerror_r} is available, define @code{HAVE_STRERROR_R}.  If
+its implementation correctly returns a @code{char *}, define
+@code{HAVE_WORKING_STRERROR_R}.  On at least DEC UNIX 4.0[A-D] and HP-UX
+B.10.20, @code{strerror_r} returns @code{int}.  Actually, this tests
+only whether it returns a scalar or an array, but that should be enough.
+This is used by the common @file{error.c}.
+@end defmac
+
+@defmac AC_FUNC_STRFTIME
+@maindex FUNC_STRFTIME
+@cvindex HAVE_STRFTIME
+Check for @code{strftime} in the @file{intl} library, for SCO @sc{unix}.
+Then, if @code{strftime} is available, define @code{HAVE_STRFTIME}.
+@end defmac
+
+@defmac AC_FUNC_UTIME_NULL
+@maindex FUNC_UTIME_NULL
+@cvindex HAVE_UTIME_NULL
+If @samp{utime(@var{file}, NULL)} sets @var{file}'s timestamp to
+the present, define @code{HAVE_UTIME_NULL}.
+@end defmac
+
+@defmac AC_FUNC_VPRINTF
+@maindex FUNC_VPRINTF
+@cvindex HAVE_VPRINTF
+@cvindex HAVE_DOPRNT
+If @code{vprintf} is found, define @code{HAVE_VPRINTF}.  Otherwise, if
+@code{_doprnt} is found, define @code{HAVE_DOPRNT}.  (If @code{vprintf}
+is available, you may assume that @code{vfprintf} and @code{vsprintf}
+are also available.)
+@end defmac
+
+@node Generic Functions,  , Particular Functions, Library Functions
+@subsection Generic Function Checks
+
+These macros are used to find functions not covered by the ``particular''
+test macros.  If the functions might be in libraries other than the
+default C library, first call @code{AC_CHECK_LIB} for those libraries.
+If you need to check the behavior of a function as well as find out
+whether it is present, you have to write your own test for
+it (@pxref{Writing Tests}).
+
+@defmac AC_CHECK_FUNC (@var{function}, @ovar{action-if-found}, @ovar{action-if-not-found})
+@maindex CHECK_FUNC
+If C function @var{function} is available, run shell commands
+@var{action-if-found}, otherwise @var{action-if-not-found}.  If you just
+want to define a symbol if the function is available, consider using
+@code{AC_CHECK_FUNCS} instead.  This macro checks for functions with C
+linkage even when @code{AC_LANG(C++)} has been called, since C is more
+standardized than C++.  (@pxref{Language Choice}, for more information
+about selecting the language for checks.)
+@end defmac
+
+@defmac AC_CHECK_FUNCS (@var{function}@dots{}, @ovar{action-if-found}, @ovar{action-if-not-found})
+@maindex CHECK_FUNCS
+@cvindex HAVE_@var{function}
+For each @var{function} in the whitespace-separated argument list,
+define @code{HAVE_@var{function}} (in all capitals) if it is available.
+If @var{action-if-found} is given, it is additional shell code to
+execute when one of the functions is found.  You can give it a value of
+@samp{break} to break out of the loop on the first match.  If
+@var{action-if-not-found} is given, it is executed when one of the
+functions is not found.
+@end defmac
+
+Autoconf follows a philosophy that was formed over the years by those
+who have struggled for portability: isolate the portability issues in
+specific files, and then program as if you were in a @sc{posix}
+environment.  Some functions may be missing or unfixable, and your
+package must be ready to replace them.
+
+Use the first three of the following macros to specify a function to be
+replaced, and the last one (@code{AC_REPLACE_FUNCS}) to check for and
+replace the function if needed.
+
+@defmac AC_LIBOBJ (@var{function})
+@maindex LIBOBJ
+@ovindex LIBOBJS
+Specify that @samp{@var{function}.c} must be included in the executables
+to replace a missing or broken implementation of @var{function}.
+
+Technically, it adds @samp{@var{function}.$ac_objext} to the output
+variable @code{LIBOBJS} and calls @code{AC_LIBSOURCE} for
+@samp{@var{function}.c}.  You should not directly change @code{LIBOBJS},
+since this is not traceable.
+@end defmac
+
+@defmac AC_LIBSOURCE (@var{file})
+@maindex LIBSOURCE
+Specify that @var{file} might be needed to compile the project.  If you
+need to know what files might be needed by a @file{configure.ac}, you
+should trace @code{AC_LIBSOURCE}.  @var{file} must be a literal.
+
+This macro is called automatically from @code{AC_LIBOBJ}, but you must
+call it explicitly if you pass a shell variable to @code{AC_LIBOBJ}.  In
+that case, since shell variables cannot be traced statically, you must
+pass to @code{AC_LIBSOURCE} any possible files that the shell variable
+might cause @code{AC_LIBOBJ} to need.  For example, if you want to pass
+a variable @code{$foo_or_bar} to @code{AC_LIBOBJ} that holds either
+@code{"foo"} or @code{"bar"}, you should do:
+
+@example
+AC_LIBSOURCE(foo.c)
+AC_LIBSOURCE(bar.c)
+AC_LIBOBJ($foo_or_bar)
+@end example
+
+@noindent
+There is usually a way to avoid this, however, and you are encouraged to
+simply call @code{AC_LIBOBJ} with literal arguments.
+
+Note that this macro replaces the obsolete @code{AC_LIBOBJ_DECL}, with
+slightly different semantics: the old macro took the function name,
+e.g. @code{foo}, as its argument rather than the file name.
+@end defmac
+
+@defmac AC_LIBSOURCES (@var{files})
+@maindex LIBSOURCES
+Like @code{AC_LIBSOURCE}, but accepts one or more @var{files} in a
+comma-separated M4 list.  Thus, the above example might be rewritten:
+
+@example
+AC_LIBSOURCES([foo.c, bar.c])
+AC_LIBOBJ($foo_or_bar)
+@end example
+@end defmac
+
+@defmac AC_REPLACE_FUNCS (@var{function}@dots{})
+@maindex REPLACE_FUNCS
+@ovindex LIBOBJS
+Like @code{AC_CHECK_FUNCS}, but uses @samp{AC_LIBOBJ(@var{function})} as
+@var{action-if-not-found}.  You can declare your replacement function by
+enclosing the prototype in @samp{#if !HAVE_@var{function}}.  If the
+system has the function, it probably declares it in a header file you
+should be including, so you shouldn't redeclare it lest your declaration
+conflict.
+@end defmac
+
+@node Header Files, Declarations, Library Functions, Existing Tests
+@section Header Files
+@cindex Header, checking
+
+The following macros check for the presence of certain C header files.
+If there is no macro specifically defined to check for a header file you need,
+and you don't need to check for any special properties of
+it, then you can use one of the general header-file check macros.
+
+@menu
+* Particular Headers::          Special handling to find certain headers
+* Generic Headers::             How to find other headers
+@end menu
+
+@node Particular Headers, Generic Headers, Header Files, Header Files
+@subsection Particular Header Checks
+
+These macros check for particular system header files---whether they
+exist, and in some cases whether they declare certain symbols.
+
+@defmac AC_HEADER_DIRENT
+@maindex HEADER_DIRENT
+@cvindex HAVE_DIRENT_H
+@cvindex HAVE_NDIR_H
+@cvindex HAVE_SYS_DIR_H
+@cvindex HAVE_SYS_NDIR_H
+Check for the following header files.  For the first one that is
+found and defines @samp{DIR}, define the listed C preprocessor macro:
+
+@multitable {@file{sys/ndir.h}} {@code{HAVE_SYS_NDIR_H}}
+@item @file{dirent.h}   @tab @code{HAVE_DIRENT_H}
+@item @file{sys/ndir.h} @tab @code{HAVE_SYS_NDIR_H}
+@item @file{sys/dir.h}  @tab @code{HAVE_SYS_DIR_H}
+@item @file{ndir.h}     @tab @code{HAVE_NDIR_H}
+@end multitable
+
+The directory-library declarations in your source code should look
+something like the following:
+
+@example
+@group
+#if HAVE_DIRENT_H
+# include <dirent.h>
+# define NAMLEN(dirent) strlen((dirent)->d_name)
+#else
+# define dirent direct
+# define NAMLEN(dirent) (dirent)->d_namlen
+# if HAVE_SYS_NDIR_H
+#  include <sys/ndir.h>
+# endif
+# if HAVE_SYS_DIR_H
+#  include <sys/dir.h>
+# endif
+# if HAVE_NDIR_H
+#  include <ndir.h>
+# endif
+#endif
+@end group
+@end example
+
+Using the above declarations, the program would declare variables to be
+of type @code{struct dirent}, not @code{struct direct}, and would access
+the length of a directory entry name by passing a pointer to a
+@code{struct dirent} to the @code{NAMLEN} macro.
+
+This macro also checks for the SCO Xenix @file{dir} and @file{x} libraries.
+@end defmac
+
+@defmac AC_HEADER_MAJOR
+@maindex HEADER_MAJOR
+@cvindex MAJOR_IN_MKDEV
+@cvindex MAJOR_IN_SYSMACROS
+If @file{sys/types.h} does not define @code{major}, @code{minor}, and
+@code{makedev}, but @file{sys/mkdev.h} does, define
+@code{MAJOR_IN_MKDEV}; otherwise, if @file{sys/sysmacros.h} does, define
+@code{MAJOR_IN_SYSMACROS}.
+@end defmac
+
+
+@defmac AC_HEADER_STAT
+@maindex HEADER_STAT
+@maindex STAT_MACROS_BROKEN
+If the macros @code{S_ISDIR}, @code{S_ISREG} et al. defined in
+@file{sys/stat.h} do not work properly (returning false positives),
+define @code{STAT_MACROS_BROKEN}.  This is the case on Tektronix UTekV,
+Amdahl UTS and Motorola System V/88.
+@end defmac
+
+
+@defmac AC_HEADER_STDC
+@maindex HEADER_STDC
+@cvindex STDC_HEADERS
+Define @code{STDC_HEADERS} if the system has @sc{ansi} C header files.
+Specifically, this macro checks for @file{stdlib.h}, @file{stdarg.h},
+@file{string.h}, and @file{float.h}; if the system has those, it
+probably has the rest of the @sc{ansi} C header files.  This macro also
+checks whether @file{string.h} declares @code{memchr} (and thus
+presumably the other @code{mem} functions), whether @file{stdlib.h}
+declare @code{free} (and thus presumably @code{malloc} and other related
+functions), and whether the @file{ctype.h} macros work on characters
+with the high bit set, as @sc{ansi} C requires.
+
+Use @code{STDC_HEADERS} instead of @code{__STDC__} to determine whether
+the system has @sc{ansi}-compliant header files (and probably C library
+functions) because many systems that have GCC do not have @sc{ansi} C
+header files.
+
+On systems without @sc{ansi} C headers, there is so much variation that
+it is probably easier to declare the functions you use than to figure
+out exactly what the system header files declare.  Some systems contain
+a mix of functions @sc{ansi} and @sc{bsd}; some are mostly @sc{ansi} but
+lack @samp{memmove}; some define the @sc{bsd} functions as macros in
+@file{string.h} or @file{strings.h}; some have only the @sc{bsd}
+functions but @file{string.h}; some declare the memory functions in
+@file{memory.h}, some in @file{string.h}; etc.  It is probably
+sufficient to check for one string function and one memory function; if
+the library has the @sc{ansi} versions of those then it probably has
+most of the others.  If you put the following in @file{configure.ac}:
+
+@example
+AC_HEADER_STDC
+AC_CHECK_FUNCS(strchr memcpy)
+@end example
+
+@noindent
+then, in your code, you can put declarations like this:
+
+@example
+@group
+#if STDC_HEADERS
+# include <string.h>
+#else
+# if !HAVE_STRCHR
+#  define strchr index
+#  define strrchr rindex
+# endif
+char *strchr (), *strrchr ();
+# if !HAVE_MEMCPY
+#  define memcpy(d, s, n) bcopy ((s), (d), (n))
+#  define memmove(d, s, n) bcopy ((s), (d), (n))
+# endif
+#endif
+@end group
+@end example
+
+@noindent
+If you use a function like @code{memchr}, @code{memset}, @code{strtok},
+or @code{strspn}, which have no @sc{bsd} equivalent, then macros won't
+suffice; you must provide an implementation of each function.  An easy
+way to incorporate your implementations only when needed (since the ones
+in system C libraries may be hand optimized) is to, taking @code{memchr}
+for example, put it in @file{memchr.c} and use
+@samp{AC_REPLACE_FUNCS(memchr)}.
+@end defmac
+
+@defmac AC_HEADER_SYS_WAIT
+@maindex HEADER_SYS_WAIT
+@cvindex HAVE_SYS_WAIT_H
+If @file{sys/wait.h} exists and is compatible with @sc{posix.1}, define
+@code{HAVE_SYS_WAIT_H}.  Incompatibility can occur if @file{sys/wait.h}
+does not exist, or if it uses the old @sc{bsd} @code{union wait} instead
+of @code{int} to store a status value.  If @file{sys/wait.h} is not
+@sc{posix.1} compatible, then instead of including it, define the
+@sc{posix.1} macros with their usual interpretations.  Here is an
+example:
+
+@example
+@group
+#include <sys/types.h>
+#if HAVE_SYS_WAIT_H
+# include <sys/wait.h>
+#endif
+#ifndef WEXITSTATUS
+# define WEXITSTATUS(stat_val) ((unsigned)(stat_val) >> 8)
+#endif
+#ifndef WIFEXITED
+# define WIFEXITED(stat_val) (((stat_val) & 255) == 0)
+#endif
+@end group
+@end example
+@end defmac
+
+@cvindex _POSIX_VERSION
+@code{_POSIX_VERSION} is defined when @file{unistd.h} is included on
+@sc{posix.1} systems.  If there is no @file{unistd.h}, it is definitely
+not a @sc{posix.1} system.  However, some non-@sc{posix.1} systems do
+have @file{unistd.h}.
+
+The way to check if the system supports @sc{posix.1} is:
+
+@example
+@group
+#if HAVE_UNISTD_H
+# include <sys/types.h>
+# include <unistd.h>
+#endif
+
+#ifdef _POSIX_VERSION
+/* Code for POSIX.1 systems.  */
+#endif
+@end group
+@end example
+
+@defmac AC_HEADER_TIME
+@maindex HEADER_TIME
+@cvindex TIME_WITH_SYS_TIME
+If a program may include both @file{time.h} and @file{sys/time.h},
+define @code{TIME_WITH_SYS_TIME}.  On some older systems,
+@file{sys/time.h} includes @file{time.h}, but @file{time.h} is not
+protected against multiple inclusion, so programs should not explicitly
+include both files.  This macro is useful in programs that use, for
+example, @code{struct timeval} or @code{struct timezone} as well as
+@code{struct tm}.  It is best used in conjunction with
+@code{HAVE_SYS_TIME_H}, which can be checked for using
+@code{AC_CHECK_HEADERS(sys/time.h)}.
+
+@example
+@group
+#if TIME_WITH_SYS_TIME
+# include <sys/time.h>
+# include <time.h>
+#else
+# if HAVE_SYS_TIME_H
+#  include <sys/time.h>
+# else
+#  include <time.h>
+# endif
+#endif
+@end group
+@end example
+@end defmac
+
+
+@defmac AC_HEADER_TIOCGWINSZ
+@maindex HEADER_TIOCGWINSZ
+@cvindex GWINSZ_IN_SYS_IOCTL
+@c FIXME: I need clarifications from Jim.
+If the use of @code{TIOCGWINSZ} requires @file{<sys/ioctl.h>}, then
+define @code{GWINSZ_IN_SYS_IOCTL}.  Otherwise @code{TIOCGWINSZ} can be
+found in @file{<termios.h>}.
+
+Use:
+
+@example
+@group
+#if HAVE_TERMIOS_H
+# include <termios.h>
+#endif
+
+#if GWINSZ_IN_SYS_IOCTL
+# include <sys/ioctl.h>
+#endif
+@end group
+@end example
+@end defmac
+
+@node Generic Headers,  , Particular Headers, Header Files
+@subsection Generic Header Checks
+
+These macros are used to find system header files not covered by the
+``particular'' test macros.  If you need to check the contents of a header
+as well as find out whether it is present, you have to write your own
+test for it (@pxref{Writing Tests}).
+
+@defmac AC_CHECK_HEADER (@var{header-file}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{includes})
+@maindex CHECK_HEADER
+If the system header file @var{header-file} is usable, execute shell
+commands @var{action-if-found}, otherwise execute
+@var{action-if-not-found}.  If you just want to define a symbol if the
+header file is available, consider using @code{AC_CHECK_HEADERS}
+instead.
+
+The meaning of ``usable'' depends upon the content of @var{includes}:
+
+@table @asis
+@item if @var{includes} is empty
+check whether
+
+@example
+@var{header-file}
+@end example
+
+@noindent
+can be @emph{preprocessed} without error.
+
+@item if @var{include} is set
+Check whether
+
+@example
+@var{includes}
+#include <@var{header-file}>
+@end example
+
+@noindent
+can be @emph{compiled} without error.  You may use
+@code{AC_CHECK_HEADER} (and @code{AC_CHECK_HEADERS}) to check whether
+two headers are compatible.
+@end table
+
+You may pass any kind of dummy content for @var{includes}, such as a
+single space, a comment, to check whether @var{header-file} compiles
+with success.
+@end defmac
+
+@defmac AC_CHECK_HEADERS (@var{header-file}@dots{}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{includes})
+@maindex CHECK_HEADERS
+@cvindex HAVE_@var{header}
+For each given system header file @var{header-file} in the
+whitespace-separated argument list that exists, define
+@code{HAVE_@var{header-file}} (in all capitals).  If @var{action-if-found}
+is given, it is additional shell code to execute when one of the header
+files is found.  You can give it a value of @samp{break} to break out of
+the loop on the first match.  If @var{action-if-not-found} is given, it
+is executed when one of the header files is not found.
+
+Be sure to read the documentation of @code{AC_CHECK_HEADER} to
+understand the influence of @var{includes}.
+@end defmac
+
+@node Declarations, Structures, Header Files, Existing Tests
+@section Declarations
+@cindex Declaration, checking
+
+The following macros check for the declaration of variables and
+functions.  If there is no macro specifically defined to check for a
+symbol you need, then you can use the general macros (@pxref{Generic
+Declarations}) or, for more complex tests, you may use
+@code{AC_TRY_COMPILE} (@pxref{Examining Syntax}).
+
+@menu
+* Particular Declarations::     Macros to check for certain declarations
+* Generic Declarations::        How to find other declarations
+@end menu
+
+@node Particular Declarations, Generic Declarations, Declarations, Declarations
+@subsection Particular Declaration Checks
+
+The following macros check for certain declarations.
+
+@defmac AC_DECL_SYS_SIGLIST
+@maindex DECL_SYS_SIGLIST
+@cvindex SYS_SIGLIST_DECLARED
+Define @code{SYS_SIGLIST_DECLARED} if the variable @code{sys_siglist}
+is declared in a system header file, either @file{signal.h} or
+@file{unistd.h}.
+@end defmac
+
+@node Generic Declarations,  , Particular Declarations, Declarations
+@subsection Generic Declaration Checks
+
+These macros are used to find declarations not covered by the ``particular''
+test macros.
+
+@defmac AC_CHECK_DECL (@var{symbol}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{includes})
+@maindex CHECK_DECL
+If @var{symbol} (a function or a variable) is not declared in
+@var{includes} and a declaration is needed, run the shell commands
+@var{action-if-not-found}, otherwise @var{action-if-found}.  If no
+@var{includes} are specified, the default includes are used
+(@pxref{Default Includes}).
+
+This macro actually tests whether it is valid to use @var{symbol} as an
+r-value, not if it is really declared, because it is much safer to avoid
+introducing extra declarations when they are not needed.
+@end defmac
+
+@defmac AC_CHECK_DECLS (@var{symbols}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{includes})
+@maindex CHECK_DECLS
+@cvindex HAVE_DECL_@var{symbol}
+For each of the @var{symbols} (@emph{comma}-separated list), define
+@code{HAVE_DECL_@var{symbol}} (in all capitals) to @samp{1} if
+@var{symbol} is declared, otherwise to @samp{0}.  If
+@var{action-if-not-found} is given, it is additional shell code to
+execute when one of the function declarations is needed, otherwise
+@var{action-if-found} is executed.
+
+This macro uses an m4 list as first argument:
+@example
+AC_CHECK_DECLS(strdup)
+AC_CHECK_DECLS([strlen])
+AC_CHECK_DECLS([malloc, realloc, calloc, free])
+@end example
+
+Unlike the other @samp{AC_CHECK_*S} macros, when a @var{symbol} is not
+declared, @code{HAVE_DECL_@var{symbol}} is defined to @samp{0} instead
+of leaving @code{HAVE_DECL_@var{symbol}} undeclared.  When you are
+@emph{sure} that the check was performed, use
+@code{HAVE_DECL_@var{symbol}} just like any other result of Autoconf:
+
+@example
+#if !HAVE_DECL_SYMBOL
+extern char *symbol;
+#endif
+@end example
+
+@noindent
+If the test may have not been performed, however, because it is safer
+@emph{not} to declare a symbol than to use a declaration that conflicts
+with the system's one, you should use:
+
+@example
+#if defined HAVE_DECL_MALLOC && !HAVE_DECL_MALLOC
+char *malloc (size_t *s);
+#endif
+@end example
+
+@noindent
+You fall into the second category only in extreme situations: either
+your files may be used without being configured, or they are used during
+the configuration.  In most cases the traditional approach is enough.
+@end defmac
+
+
+@node Structures, Types, Declarations, Existing Tests
+@section Structures
+@cindex Structure, checking
+
+The following macros check for the presence of certain members in C
+structures.  If there is no macro specifically defined to check for a
+member you need, then you can use the general structure-member macro
+(@pxref{Generic Structures}) or, for more complex tests, you may use
+@code{AC_TRY_COMPILE} (@pxref{Examining Syntax}).
+
+@menu
+* Particular Structures::       Macros to check for certain structure members
+* Generic Structures::          How to find other structure members
+@end menu
+
+@node Particular Structures, Generic Structures, Structures, Structures
+@subsection Particular Structure Checks
+
+The following macros check for certain structures or structure members.
+
+@defmac AC_STRUCT_ST_BLKSIZE
+@maindex STRUCT_ST_BLKSIZE
+@cvindex HAVE_STRUCT_STAT_ST_BLKSIZE
+@cvindex HAVE_ST_BLKSIZE
+If @code{struct stat} contains an @code{st_blksize} member, define
+@code{HAVE_STRUCT_STAT_ST_BLKSIZE}.  The former name,
+@code{HAVE_ST_BLKSIZE} is to be avoided, as its support will cease in
+the future.  This macro is obsoleted, and should be replaced by
+
+@example
+AC_CHECK_MEMBERS([struct stat.st_blksize])
+@end example
+@end defmac
+
+@defmac AC_STRUCT_ST_BLOCKS
+@maindex STRUCT_ST_BLOCKS
+@cvindex HAVE_STRUCT_STAT_ST_BLOCKS
+@cvindex HAVE_ST_BLOCKS
+@ovindex LIBOBJS
+If @code{struct stat} contains an @code{st_blocks} member, define
+@code{HAVE_STRUCT STAT_ST_BLOCKS}.  Otherwise, require an
+@code{AC_LIBOBJ} replacement of @samp{fileblocks}.  The former name,
+@code{HAVE_ST_BLOCKS} is to be avoided, as its support will cease in the
+future.
+@end defmac
+
+@defmac AC_STRUCT_ST_RDEV
+@maindex STRUCT_ST_RDEV
+@cvindex HAVE_ST_RDEV
+@cvindex HAVE_STRUCT_STAT_ST_RDEV
+If @code{struct stat} contains an @code{st_rdev} member, define
+@code{HAVE_STRUCT_STAT_ST_RDEV}.  The former name for this macro,
+@code{HAVE_ST_RDEV}, is to be avoided as it will cease to be supported
+in the future.  Actually, even the new macro is obsolete, and should be
+replaced by:
+@example
+AC_CHECK_MEMBERS([struct stat.st_rdev])
+@end example
+@end defmac
+
+@defmac AC_STRUCT_TM
+@maindex STRUCT_TM
+@cvindex TM_IN_SYS_TIME
+If @file{time.h} does not define @code{struct tm}, define
+@code{TM_IN_SYS_TIME}, which means that including @file{sys/time.h}
+had better define @code{struct tm}.
+@end defmac
+
+@defmac AC_STRUCT_TIMEZONE
+@maindex STRUCT_TIMEZONE
+@cvindex HAVE_TM_ZONE
+@cvindex HAVE_TZNAME
+Figure out how to get the current timezone.  If @code{struct tm} has a
+@code{tm_zone} member, define @code{HAVE_STRUCT_TM_TM_ZONE} (and the
+obsoleted @code{HAVE_TM_ZONE}).  Otherwise, if the external array
+@code{tzname} is found, define @code{HAVE_TZNAME}.
+@end defmac
+
+@node Generic Structures,  , Particular Structures, Structures
+@subsection Generic Structure Checks
+
+These macros are used to find structure members not covered by the
+``particular'' test macros.
+
+@defmac AC_CHECK_MEMBER (@var{aggregate}.@var{member}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{includes})
+@maindex CHECK_MEMBER
+Check whether @var{member} is a member of the aggregate @var{aggregate}.
+If no @var{includes} are specified, the default includes are used
+(@pxref{Default Includes}).
+
+@example
+AC_CHECK_MEMBER(struct passwd.pw_gecos,,
+                [AC_MSG_ERROR([We need `passwd.pw_gecos'!])],
+                [#include <pwd.h>])
+@end example
+
+You can use this macro for sub-members:
+
+@example
+AC_CHECK_MEMBER(struct top.middle.bot)
+@end example
+@end defmac
+
+@defmac AC_CHECK_MEMBERS (@var{members}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{includes})
+@maindex CHECK_MEMBERS
+Check for the existence of each @samp{@var{aggregate}.@var{member}} of
+@var{members} using the previous macro.  When @var{member} belongs to
+@var{aggregate}, define @code{HAVE_@var{aggregate}_@var{member}} (in all
+capitals, with spaces and dots replaced by underscores).
+
+This macro uses m4 lists:
+@example
+AC_CHECK_MEMBERS([struct stat.st_rdev, struct stat.st_blksize])
+@end example
+@end defmac
+
+
+@node Types, Compilers and Preprocessors, Structures, Existing Tests
+@section Types
+
+The following macros check for C types, either builtin or typedefs.  If
+there is no macro specifically defined to check for a type you need, and
+you don't need to check for any special properties of it, then you can
+use a general type-check macro.
+
+@menu
+* Particular Types::            Special handling to find certain types
+* Generic Types::               How to find other types
+@end menu
+
+@node Particular Types, Generic Types, Types, Types
+@subsection Particular Type Checks
+
+These macros check for particular C types in @file{sys/types.h},
+@file{stdlib.h} and others, if they exist.
+
+@defmac AC_TYPE_GETGROUPS
+@maindex TYPE_GETGROUPS
+@cvindex GETGROUPS_T
+Define @code{GETGROUPS_T} to be whichever of @code{gid_t} or @code{int}
+is the base type of the array argument to @code{getgroups}.
+@end defmac
+
+@defmac AC_TYPE_MODE_T
+@maindex TYPE_MODE_T
+@cvindex mode_t
+Equivalent to @samp{AC_CHECK_TYPE(mode_t, int)}.
+@end defmac
+
+@defmac AC_TYPE_OFF_T
+@maindex TYPE_OFF_T
+@cvindex off_t
+Equivalent to @samp{AC_CHECK_TYPE(off_t, long)}.
+@end defmac
+
+@defmac AC_TYPE_PID_T
+@maindex TYPE_PID_T
+@cvindex pid_t
+Equivalent to @samp{AC_CHECK_TYPE(pid_t, int)}.
+@end defmac
+
+@defmac AC_TYPE_SIGNAL
+@maindex TYPE_SIGNAL
+@cvindex RETSIGTYPE
+If @file{signal.h} declares @code{signal} as returning a pointer to a
+function returning @code{void}, define @code{RETSIGTYPE} to be
+@code{void}; otherwise, define it to be @code{int}.
+
+Define signal handlers as returning type @code{RETSIGTYPE}:
+
+@example
+@group
+RETSIGTYPE
+hup_handler ()
+@{
+@dots{}
+@}
+@end group
+@end example
+@end defmac
+
+@defmac AC_TYPE_SIZE_T
+@maindex TYPE_SIZE_T
+@cvindex size_t
+Equivalent to @samp{AC_CHECK_TYPE(size_t, unsigned)}.
+@end defmac
+
+@defmac AC_TYPE_UID_T
+@maindex TYPE_UID_T
+@cvindex uid_t
+@cvindex gid_t
+If @code{uid_t} is not defined, define @code{uid_t} to be @code{int} and
+@code{gid_t} to be @code{int}.
+@end defmac
+
+@node Generic Types,  , Particular Types, Types
+@subsection Generic Type Checks
+
+These macros are used to check for types not covered by the ``particular''
+test macros.
+
+@defmac AC_CHECK_TYPE (@var{type}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{includes})
+@maindex CHECK_TYPE
+Check whether @var{type} is defined.  It may be a compiler builtin type
+or defined by the @ovar{includes} (@pxref{Default Includes}).
+@end defmac
+
+
+@defmac AC_CHECK_TYPES (@var{types}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{includes})
+@maindex CHECK_TYPES
+For each @var{type} of the @var{types} that is defined, define
+@code{HAVE_@var{type}} (in all capitals).  If no @var{includes} are
+specified, the default includes are used (@pxref{Default Includes}).  If
+@var{action-if-found} is given, it is additional shell code to execute
+when one of the types is found.  If @var{action-if-not-found} is given,
+it is executed when one of the types is not found.
+
+This macro uses m4 lists:
+@example
+AC_CHECK_TYPES(ptrdiff_t)
+AC_CHECK_TYPES([unsigned long long, uintmax_t])
+@end example
+
+@end defmac
+
+Autoconf, up to 2.13, used to provide to another version of
+@code{AC_CHECK_TYPE}, broken by design.  In order to keep backward
+compatibility, a simple heuristics, quite safe but not totally, is
+implemented.  In case of doubt, read the documentation of the former
+@code{AC_CHECK_TYPE}, see @ref{Obsolete Macros}.
+
+
+@node Compilers and Preprocessors, System Services, Types, Existing Tests
+@section Compilers and Preprocessors
+
+@ovindex EXEEXT
+All the tests for compilers (@code{AC_PROG_CC}, @code{AC_PROG_CXX},
+@code{AC_PROG_F77}) define the output variable @code{EXEEXT} based on
+the output of the compiler, typically to the empty string if Unix and
+@samp{.exe} if Win32 or OS/2.
+
+@ovindex OBJEXT
+They also define the output variable @code{OBJEXT} based on the
+output of the compiler, after .c files have been excluded, typically
+to @samp{o} if Unix, @samp{obj} if Win32.
+
+If the compiler being used does not produce executables, they fail.  If
+the executables can't be run, and cross-compilation is not enabled, they
+fail too.  @xref{Manual Configuration}, for more on support for cross
+compiling.
+
+@menu
+* Generic Compiler Characteristics::  Language independent tests
+* C Compiler::                  Checking its characteristics
+* C++ Compiler::                Likewise
+* Fortran 77 Compiler::         Likewise
+@end menu
+
+@node Generic Compiler Characteristics, C Compiler, Compilers and Preprocessors, Compilers and Preprocessors
+@subsection Generic Compiler Characteristics
+
+@defmac AC_CHECK_SIZEOF (@var{type}, @ovar{unused}, @ovar{includes})
+@maindex CHECK_SIZEOF
+Define @code{SIZEOF_@var{type}} (@pxref{Standard Symbols}) to be the
+size in bytes of @var{type}.  If @samp{type} is unknown, it gets a size
+of 0.  If no @var{includes} are specified, the default includes are used
+(@pxref{Default Includes}).  If you provide @var{include}, make sure to
+include @file{stdio.h} which is required for this macro to run.
+
+This macro now works even when cross-compiling.  The @var{unused}
+argument was used when cross-compiling.
+
+For example, the call
+
+@example
+AC_CHECK_SIZEOF(int *)
+@end example
+
+@noindent
+defines @code{SIZEOF_INT_P} to be 8 on DEC Alpha AXP systems.
+@end defmac
+
+
+@node C Compiler, C++ Compiler, Generic Compiler Characteristics, Compilers and Preprocessors
+@subsection C Compiler Characteristics
+
+@defmac AC_PROG_CC (@ovar{compiler-search-list})
+@maindex PROG_CC
+@ovindex CC
+@ovindex CFLAGS
+Determine a C compiler to use.  If @code{CC} is not already set in the
+environment, check for @code{gcc} and @code{cc}, then for other C
+compilers.  Set output variable @code{CC} to the name of the compiler
+found.
+
+This macro may, however, be invoked with an optional first argument
+which, if specified, must be a space separated list of C compilers to
+search for.  This just gives the user an opportunity to specify an
+alternative search list for the C compiler.  For example, if you didn't
+like the default order, then you could invoke @code{AC_PROG_CC} like
+this:
+
+@example
+AC_PROG_CC(cl egcs gcc cc)
+@end example
+
+If using the @sc{gnu} C compiler, set shell variable @code{GCC} to
+@samp{yes}.  If output variable @code{CFLAGS} was not already set, set
+it to @option{-g -O2} for the @sc{gnu} C compiler (@option{-O2} on systems
+where GCC does not accept @option{-g}), or @option{-g} for other compilers.
+@end defmac
+
+@defmac AC_PROG_CC_C_O
+@maindex PROG_CC_C_O
+@cvindex NO_MINUS_C_MINUS_O
+If the C compiler does not accept the @option{-c} and @option{-o} options
+simultaneously, define @code{NO_MINUS_C_MINUS_O}.  This macro actually
+tests both the compiler found by @code{AC_PROG_CC}, and, if different,
+the first @code{cc} in the path.  The test fails if one fails.  This
+macro was created for @sc{gnu} Make to choose the default C compilation
+rule.
+@end defmac
+
+@defmac AC_PROG_CC_STDC
+@maindex PROG_CC_STDC
+@ovindex CC
+If the C compiler is not in @sc{ansi} C mode by default, try to add an
+option to output variable @code{CC} to make it so.  This macro tries
+various options that select @sc{ansi} C on some system or another.  It
+considers the compiler to be in @sc{ansi} C mode if it handles function
+prototypes correctly.
+
+If you use this macro, you should check after calling it whether the C
+compiler has been set to accept @sc{ansi} C; if not, the shell variable
+@code{ac_cv_prog_cc_stdc} is set to @samp{no}.  If you wrote your source
+code in @sc{ansi} C, you can make an un-@sc{ansi}fied copy of it by
+using the program @code{ansi2knr}, which comes with Automake.
+@end defmac
+
+
+@defmac AC_PROG_CPP
+@maindex PROG_CPP
+@ovindex CPP
+Set output variable @code{CPP} to a command that runs the
+C preprocessor.  If @samp{$CC -E} doesn't work, @file{/lib/cpp} is used.
+It is only portable to run @code{CPP} on files with a @file{.c}
+extension.
+
+If the current language is C (@pxref{Language Choice}), many of the
+specific test macros use the value of @code{CPP} indirectly by calling
+@code{AC_TRY_CPP}, @code{AC_CHECK_HEADER}, @code{AC_EGREP_HEADER}, or
+@code{AC_EGREP_CPP}.
+
+Some preprocessors don't indicate missing include files by the error
+status.  For such preprocessors an internal variable is set that causes
+other macros to check the standard error from the preprocessor and
+consider the test failed if any warnings have been reported.
+@end defmac
+
+
+The following macros check for C compiler or machine architecture
+features.  To check for characteristics not listed here, use
+@code{AC_TRY_COMPILE} (@pxref{Examining Syntax}) or @code{AC_TRY_RUN}
+(@pxref{Run Time})
+
+@defmac AC_C_BIGENDIAN
+@maindex C_BIGENDIAN
+@cvindex WORDS_BIGENDIAN
+@cindex Endianness
+If words are stored with the most significant byte first (like Motorola
+and SPARC, but not Intel and VAX, CPUs), define @code{WORDS_BIGENDIAN}.
+@end defmac
+
+
+@defmac AC_C_CONST
+@maindex C_CONST
+@cvindex const
+If the C compiler does not fully support the @sc{ansi} C qualifier
+@code{const}, define @code{const} to be empty.  Some C compilers that do
+not define @code{__STDC__} do support @code{const}; some compilers that
+define @code{__STDC__} do not completely support @code{const}.  Programs
+can simply use @code{const} as if every C compiler supported it; for
+those that don't, the @file{Makefile} or configuration header file will
+define it as empty.
+
+Occasionally installers use a C++ compiler to compile C code, typically
+because they lack a C compiler.  This causes problems with @code{const},
+because C and C++ treat @code{const} differently.  For example:
+
+@example
+const int foo;
+@end example
+
+@noindent
+is valid in C but not in C++.  These differences unfortunately cannot be
+papered over by defining @code{const} to be empty.
+
+If @code{autoconf} detects this situation, it leaves @code{const} alone,
+as this generally yields better results in practice.  However, using a
+C++ compiler to compile C code is not recommended or supported, and
+installers who run into trouble in this area should get a C compiler
+like GCC to compile their C code.
+@end defmac
+
+@defmac AC_C_VOLATILE
+@maindex C_VOLATILE
+@cvindex volatile
+If the C compiler does not understand the keyword @code{volatile},
+define @code{volatile} to be empty.  Programs can simply use
+@code{volatile} as if every C compiler supported it; for those that do
+not, the @file{Makefile} or configuration header will define it as
+empty.
+
+If the correctness of your program depends on the semantics of
+@code{volatile}, simply defining it to be empty does, in a sense, break
+your code.  However, given that the compiler does not support
+@code{volatile}, you are at its mercy anyway.  At least your
+program will compile, when it wouldn't before.
+
+In general, the @code{volatile} keyword is a feature of @sc{ansi} C, so
+you might expect that @code{volatile} is available only when
+@code{__STDC__} is defined.  However, Ultrix 4.3's native compiler does
+support volatile, but does not defined @code{__STDC__}.
+@end defmac
+
+@defmac AC_C_INLINE
+@maindex C_INLINE
+@cvindex inline
+If the C compiler supports the keyword @code{inline}, do nothing.
+Otherwise define @code{inline} to @code{__inline__} or @code{__inline}
+if it accepts one of those, otherwise define @code{inline} to be empty.
+@end defmac
+
+@defmac AC_C_CHAR_UNSIGNED
+@maindex C_CHAR_UNSIGNED
+@cvindex __CHAR_UNSIGNED__
+If the C type @code{char} is unsigned, define @code{__CHAR_UNSIGNED__},
+unless the C compiler predefines it.
+@end defmac
+
+@defmac AC_C_LONG_DOUBLE
+@maindex C_LONG_DOUBLE
+@cvindex HAVE_LONG_DOUBLE
+If the C compiler supports the @code{long double} type, define
+@code{HAVE_LONG_DOUBLE}.  Some C compilers that do not define
+@code{__STDC__} do support the @code{long double} type; some compilers
+that define @code{__STDC__} do not support @code{long double}.
+@end defmac
+
+@defmac AC_C_STRINGIZE
+@maindex C_STRINGIZE
+@cvindex HAVE_STRINGIZE
+If the C preprocessor supports the stringizing operator, define
+@code{HAVE_STRINGIZE}.  The stringizing operator is @samp{#} and is
+found in macros such as this:
+
+@example
+#define x(y) #y
+@end example
+@end defmac
+
+@defmac AC_C_PROTOTYPES
+@maindex C_PROTOTYPES
+@cvindex PROTOTYPES
+@cvindex PARAMS
+Check to see if function prototypes are understood by the compiler.  If
+so, define @samp{PROTOTYPES}.  In the case the compiler does not handle
+prototypes, you should use @code{ansi2knr}, which comes with the
+Automake distribution, to unprotoize function definitions.  For
+function prototypes, you should first define @code{PARAMS}:
+
+@example
+#ifndef PARAMS
+# if PROTOTYPES
+#  define PARAMS(protos) protos
+# else /* no PROTOTYPES */
+#  define PARAMS(protos) ()
+# endif /* no PROTOTYPES */
+#endif
+@end example
+
+@noindent
+then use it this way:
+
+@example
+size_t my_strlen PARAMS ((const char *));
+@end example
+@end defmac
+
+@defmac AC_PROG_GCC_TRADITIONAL
+@maindex PROG_GCC_TRADITIONAL
+@ovindex CC
+Add @option{-traditional} to output variable @code{CC} if using the
+@sc{gnu} C compiler and @code{ioctl} does not work properly without
+@option{-traditional}.  That usually happens when the fixed header files
+have not been installed on an old system.  Since recent versions of the
+@sc{gnu} C compiler fix the header files automatically when installed,
+this is becoming a less prevalent problem.
+@end defmac
+
+
+@node C++ Compiler, Fortran 77 Compiler, C Compiler, Compilers and Preprocessors
+@subsection C++ Compiler Characteristics
+
+
+@defmac AC_PROG_CXX (@ovar{compiler-search-list})
+@maindex PROG_CXX
+@ovindex CXX
+@ovindex CXXFLAGS
+Determine a C++ compiler to use.  Check if the environment variable
+@code{CXX} or @code{CCC} (in that order) is set; if so, then set output
+variable @code{CXX} to its value.
+
+Otherwise, if the macro is invoked without an argument, then search for
+a C++ compiler under the likely names (first @code{g++} and @code{c++}
+then other names).  If none of those checks succeed, then as a last
+resort set @code{CXX} to @code{g++}.
+
+This macro may, however, be invoked with an optional first argument
+which, if specified, must be a space separated list of C++ compilers to
+search for.  This just gives the user an opportunity to specify an
+alternative search list for the C++ compiler.  For example, if you
+didn't like the default order, then you could invoke @code{AC_PROG_CXX}
+like this:
+
+@example
+AC_PROG_CXX(cl KCC CC cxx cc++ xlC aCC c++ g++ egcs gcc)
+@end example
+
+If using the @sc{gnu} C++ compiler, set shell variable @code{GXX} to
+@samp{yes}.  If output variable @code{CXXFLAGS} was not already set, set
+it to @option{-g -O2} for the @sc{gnu} C++ compiler (@option{-O2} on
+systems where G++ does not accept @option{-g}), or @option{-g} for other
+compilers.
+@end defmac
+
+@defmac AC_PROG_CXXCPP
+@maindex PROG_CXXCPP
+@ovindex CXXCPP
+Set output variable @code{CXXCPP} to a command that runs the C++
+preprocessor.  If @samp{$CXX -E} doesn't work, @file{/lib/cpp} is used.
+It is only portable to run @code{CXXCPP} on files with a @file{.c},
+@file{.C}, or @file{.cc} extension.
+
+If the current language is C++ (@pxref{Language Choice}), many of the
+specific test macros use the value of @code{CXXCPP} indirectly by
+calling @code{AC_TRY_CPP}, @code{AC_CHECK_HEADER},
+@code{AC_EGREP_HEADER}, or @code{AC_EGREP_CPP}.
+
+Some preprocessors don't indicate missing include files by the error
+status.  For such preprocessors an internal variable is set that causes
+other macros to check the standard error from the preprocessor and
+consider the test failed if any warnings have been reported.  However,
+it is not known whether such broken preprocessors exist for C++.
+@end defmac
+
+
+
+@node Fortran 77 Compiler,  , C++ Compiler, Compilers and Preprocessors
+@subsection Fortran 77 Compiler Characteristics
+
+@defmac AC_PROG_F77 (@ovar{compiler-search-list})
+@maindex PROG_FORTRAN
+@ovindex F77
+@ovindex FFLAGS
+Determine a Fortran 77 compiler to use.  If @code{F77} is not already
+set in the environment, then check for @code{g77} and @code{f77}, and
+then some other names.  Set the output variable @code{F77} to the name
+of the compiler found.
+
+This macro may, however, be invoked with an optional first argument
+which, if specified, must be a space separated list of Fortran 77
+compilers to search for.  This just gives the user an opportunity to
+specify an alternative search list for the Fortran 77 compiler.  For
+example, if you didn't like the default order, then you could invoke
+@code{AC_PROG_F77} like this:
+
+@example
+AC_PROG_F77(fl32 f77 fort77 xlf cf77 g77 f90 xlf90)
+@end example
+
+If using @code{g77} (the @sc{gnu} Fortran 77 compiler), then
+@code{AC_PROG_F77} will set the shell variable @code{G77} to @samp{yes}.
+If the output variable @code{FFLAGS} was not already set in the
+environment, then set it to @option{-g -02} for @code{g77} (or @option{-O2}
+where @code{g77} does not accept @option{-g}).  Otherwise, set
+@code{FFLAGS} to @option{-g} for all other Fortran 77 compilers.
+@end defmac
+
+@defmac AC_PROG_F77_C_O
+@maindex PROG_F77_C_O
+@cvindex F77_NO_MINUS_C_MINUS_O
+Test if the Fortran 77 compiler accepts the options @option{-c} and
+@option{-o} simultaneously, and define @code{F77_NO_MINUS_C_MINUS_O} if it
+does not.
+@end defmac
+
+
+The following macros check for Fortran 77 compiler characteristics.  To
+check for characteristics not listed here, use @code{AC_TRY_COMPILE}
+(@pxref{Examining Syntax}) or @code{AC_TRY_RUN} (@pxref{Run Time}),
+making sure to first set the current language to Fortran 77
+@code{AC_LANG(Fortran 77)} (@pxref{Language Choice}).
+
+
+@defmac AC_F77_LIBRARY_LDFLAGS
+@maindex F77_LIBRARY_LDFLAGS
+@ovindex FLIBS
+Determine the linker flags (e.g. @option{-L} and @option{-l}) for the
+@dfn{Fortran 77 intrinsic and run-time libraries} that are required to
+successfully link a Fortran 77 program or shared library.  The output
+variable @code{FLIBS} is set to these flags.
+
+This macro is intended to be used in those situations when it is
+necessary to mix, e.g. C++ and Fortran 77 source code into a single
+program or shared library (@pxref{Mixing Fortran 77 With C and C++,,,
+automake, GNU Automake}).
+
+For example, if object files from a C++ and Fortran 77 compiler must be
+linked together, then the C++ compiler/linker must be used for linking
+(since special C++-ish things need to happen at link time like calling
+global constructors, instantiating templates, enabling exception
+support, etc.).
+
+However, the Fortran 77 intrinsic and run-time libraries must be linked
+in as well, but the C++ compiler/linker doesn't know by default how to
+add these Fortran 77 libraries.  Hence, the macro
+@code{AC_F77_LIBRARY_LDFLAGS} was created to determine these Fortran 77
+libraries.
+
+The macro @code{AC_F77_DUMMY_MAIN} or @code{AC_F77_MAIN} will probably
+also be necessary to link C/C++ with Fortran; see below.
+@end defmac
+
+
+@defmac AC_F77_DUMMY_MAIN (@ovar{action-if-found}, @ovar{action-if-not-found})
+@maindex F77_DUMMY_MAIN
+@cvindex F77_DUMMY_MAIN
+With many compilers, the Fortran libraries detected by
+@code{AC_F77_LIBRARY_LDFLAGS} provide their own @code{main} entry
+function that initializes things like Fortran I/O, and which then calls
+a user-provided entry function named e.g. @code{MAIN__} to run the
+user's program.  The @code{AC_F77_DUMMY_MAIN} or @code{AC_F77_MAIN}
+macro figures out how to deal with this interaction.
+
+When using Fortran for purely numerical functions (no I/O, etcetera),
+users often prefer to provide their own @code{main} and skip the Fortran
+library initializations.  In this case, however, one may still need to
+provide a dummy @code{MAIN__} routine in order to prevent linking errors
+on some systems.  @code{AC_F77_DUMMY_MAIN} detects whether any such
+routine is @emph{required} for linking, and what its name is; the shell
+variable @code{F77_DUMMY_MAIN} holds this name, @code{unknown} when no
+solution was found, and @code{none} when no such dummy main is needed.
+
+By default, @var{action-if-found} defines @code{F77_DUMMY_MAIN} to the
+name of this routine (e.g. @code{MAIN__}) @emph{if} it is required.
+@ovar{action-if-not-found} defaults to exiting with an error.
+
+In order to link with Fortran routines, the user's C/C++ program should
+then include the following code to define the dummy main if it is
+needed:
+
+@example
+#ifdef F77_DUMMY_MAIN
+#  ifdef __cplusplus
+     extern "C"
+#  endif
+   int F77_DUMMY_MAIN() @{ return 1; @}
+#endif
+@end example
+
+Note that @code{AC_F77_DUMMY_MAIN} is called automatically from
+@code{AC_F77_WRAPPERS}; there is generally no need to call it explicitly
+unless one wants to change the default actions.
+@end defmac
+
+@defmac AC_F77_MAIN
+@maindex F77_MAIN
+@cvindex F77_MAIN
+As discussed above for @code{AC_F77_DUMMY_MAIN}, many Fortran libraries
+allow you to provide an entry point called e.g. @code{MAIN__} instead of
+the usual @code{main}, which is then called by a @code{main} function in
+the Fortran libraries that initializes things like Fortran I/O.  The
+@code{AC_F77_MAIN} macro detects whether it is @emph{possible} to
+utilize such an alternate main function, and defines @code{F77_MAIN} to
+the name of the function.  (If no alternate main function name is found,
+@code{F77_MAIN} is simply defined to @code{main}.)
+
+Thus, when calling Fortran routines from C that perform things like I/O,
+one should use this macro and name the "main" function @code{F77_MAIN}
+instead of @code{main}.
+@end defmac
+
+@defmac AC_F77_WRAPPERS
+@maindex F77_WRAPPERS
+@cvindex F77_FUNC
+@cvindex F77_FUNC_
+Defines C macros @code{F77_FUNC(name,NAME)} and
+@code{F77_FUNC_(name,NAME)} to properly mangle the names of C/C++
+identifiers, and identifiers with underscores, respectively, so that
+they match the name-mangling scheme used by the Fortran 77 compiler.
+
+Fortran 77 is case-insensitive, and in order to achieve this the Fortran
+77 compiler converts all identifiers into a canonical case and format.
+To call a Fortran 77 subroutine from C or to write a C function that is
+callable from Fortran 77, the C program must explicitly use identifiers
+in the format expected by the Fortran 77 compiler.  In order to do this,
+one simply wraps all C identifiers in one of the macros provided by
+@code{AC_F77_WRAPPERS}.  For example, suppose you have the following
+Fortran 77 subroutine:
+
+@example
+      subroutine foobar(x,y)
+      double precision x, y
+      y = 3.14159 * x
+      return
+      end
+@end example
+
+You would then declare its prototype in C or C++ as:
+
+@example
+#define FOOBAR_F77 F77_FUNC(foobar,FOOBAR)
+#ifdef __cplusplus
+extern "C"  /* prevent C++ name mangling */
+#endif
+void FOOBAR_F77(double *x, double *y);
+@end example
+
+Note that we pass both the lowercase and uppercase versions of the
+function name to @code{F77_FUNC} so that it can select the right one.
+Note also that all parameters to Fortran 77 routines are passed as
+pointers (@pxref{Mixing Fortran 77 With C and C++,,, automake, GNU
+Automake}).
+
+Although Autoconf tries to be intelligent about detecting the
+name-mangling scheme of the Fortran 77 compiler, there may be Fortran 77
+compilers that it doesn't support yet.  In this case, the above code
+will generate a compile-time error, but some other behavior
+(e.g. disabling Fortran-related features) can be induced by checking
+whether the @code{F77_FUNC} macro is defined.
+
+Now, to call that routine from a C program, we would do something like:
+
+@example
+@{
+    double x = 2.7183, y;
+    FOOBAR_F77(&x, &y);
+@}
+@end example
+
+If the Fortran 77 identifier contains an underscore
+(e.g. @code{foo_bar}), you should use @code{F77_FUNC_} instead of
+@code{F77_FUNC} (with the same arguments).  This is because some Fortran
+77 compilers mangle names differently if they contain an underscore.
+@end defmac
+
+@defmac AC_F77_FUNC (@var{name}, @ovar{shellvar})
+@maindex F77_FUNC
+Given an identifier @var{name}, set the shell variable @var{shellvar} to
+hold the mangled version @var{name} according to the rules of the
+Fortran 77 linker (see also @code{AC_F77_WRAPPERS}).  @var{shellvar} is
+optional; if it is not supplied, the shell variable will be simply
+@var{name}.  The purpose of this macro is to give the caller a way to
+access the name-mangling information other than through the C
+preprocessor as above; for example, to call Fortran routines from some
+language other than C/C++.
+@end defmac
+
+@node System Services, UNIX Variants, Compilers and Preprocessors, Existing Tests
+@section System Services
+
+The following macros check for operating system services or capabilities.
+
+@defmac AC_PATH_X
+@maindex PATH_X
+Try to locate the X Window System include files and libraries.  If the
+user gave the command line options @option{--x-includes=@var{dir}} and
+@option{--x-libraries=@var{dir}}, use those directories.  If either or
+both were not given, get the missing values by running @code{xmkmf} on a
+trivial @file{Imakefile} and examining the @file{Makefile} that it
+produces.  If that fails (such as if @code{xmkmf} is not present), look
+for them in several directories where they often reside.  If either
+method is successful, set the shell variables @code{x_includes} and
+@code{x_libraries} to their locations, unless they are in directories
+the compiler searches by default.
+
+If both methods fail, or the user gave the command line option
+@option{--without-x}, set the shell variable @code{no_x} to @samp{yes};
+otherwise set it to the empty string.
+@end defmac
+
+@defmac AC_PATH_XTRA
+@maindex PATH_XTRA
+@ovindex X_CFLAGS
+@ovindex X_LIBS
+@ovindex X_EXTRA_LIBS
+@ovindex X_PRE_LIBS
+@cvindex X_DISPLAY_MISSING
+An enhanced version of @code{AC_PATH_X}.  It adds the C compiler flags
+that X needs to output variable @code{X_CFLAGS}, and the X linker flags
+to @code{X_LIBS}.  Define @code{X_DISPLAY_MISSING} if X is not
+available.
+
+This macro also checks for special libraries that some systems need in
+order to compile X programs.  It adds any that the system needs to
+output variable @code{X_EXTRA_LIBS}.  And it checks for special X11R6
+libraries that need to be linked with before @option{-lX11}, and adds
+any found to the output variable @code{X_PRE_LIBS}.
+
+@c This is an incomplete kludge.  Make a real way to do it.
+@c If you need to check for other X functions or libraries yourself, then
+@c after calling this macro, add the contents of @code{X_EXTRA_LIBS} to
+@c @code{LIBS} temporarily, like this: (FIXME - add example)
+@end defmac
+
+@defmac AC_SYS_INTERPRETER
+@maindex SYS_INTERPRETER
+Check whether the system supports starting scripts with a line of the
+form @samp{#! /bin/csh} to select the interpreter to use for the script.
+After running this macro, shell code in @code{configure.ac} can check
+the shell variable @code{interpval}; it will be set to @samp{yes}
+if the system supports @samp{#!}, @samp{no} if not.
+@end defmac
+
+@defmac AC_SYS_LARGEFILE
+@maindex SYS_LARGEFILE
+@cvindex _FILE_OFFSET_BITS
+@cvindex _LARGE_FILES
+@ovindex CC
+Arrange for
+@href{http://www.sas.com/standards/large.file/x_open.20Mar96.html,
+large-file support}.  On some hosts, one must use special compiler
+options to build programs that can access large files.  Append any such
+options to the output variable @code{CC}.  Define
+@code{_FILE_OFFSET_BITS} and @code{_LARGE_FILES} if necessary.
+
+Large-file support can be disabled by configuring with the
+@option{--disable-largefile} option.
+
+If you use this macro, check that your program works even when
+@code{off_t} is longer than @code{long}, since this is common when
+large-file support is enabled.  For example, it is not correct to print
+an arbitrary @code{off_t} value @code{X} with @code{printf ("%ld",
+(long) X)}.
+@end defmac
+
+@defmac AC_SYS_LONG_FILE_NAMES
+@maindex SYS_LONG_FILE_NAMES
+@cvindex HAVE_LONG_FILE_NAMES
+If the system supports file names longer than 14 characters, define
+@code{HAVE_LONG_FILE_NAMES}.
+@end defmac
+
+@defmac AC_SYS_POSIX_TERMIOS
+@maindex SYS_POSIX_TERMIOS
+@cindex POSIX termios headers
+@cindex termios POSIX headers
+Check to see if POSIX termios headers and functions are available on the
+system.  If so, set the shell variable @code{am_cv_sys_posix_termios} to
+@samp{yes}.  If not, set the variable to @samp{no}.
+@end defmac
+
+@node UNIX Variants,  , System Services, Existing Tests
+@section UNIX Variants
+
+The following macros check for certain operating systems that need
+special treatment for some programs, due to exceptional oddities in
+their header files or libraries.  These macros are warts; they will be
+replaced by a more systematic approach, based on the functions they make
+available or the environments they provide.
+
+@defmac AC_AIX
+@maindex AIX
+@cvindex _ALL_SOURCE
+If on AIX, define @code{_ALL_SOURCE}.  Allows the use of some @sc{bsd}
+functions.  Should be called before any macros that run the C compiler.
+@end defmac
+
+@defmac AC_ISC_POSIX
+@maindex ISC_POSIX
+@cvindex _POSIX_SOURCE
+@ovindex CC
+If on a POSIXized ISC @sc{unix}, define @code{_POSIX_SOURCE} and add
+@option{-posix} (for the @sc{gnu} C compiler) or @option{-Xp} (for other C
+compilers) to output variable @code{CC}.  This allows the use of
+@sc{posix} facilities.  Must be called after @code{AC_PROG_CC} and
+before any other macros that run the C compiler.
+@end defmac
+
+@defmac AC_MINIX
+@maindex MINIX
+@cvindex _MINIX
+@cvindex _POSIX_SOURCE
+@cvindex _POSIX_1_SOURCE
+If on Minix, define @code{_MINIX} and @code{_POSIX_SOURCE} and define
+@code{_POSIX_1_SOURCE} to be 2.  This allows the use of @sc{posix}
+facilities.  Should be called before any macros that run the C compiler.
+@end defmac
+
+
+
+
+@c ========================================================= Writing Tests
+
+@node Writing Tests, Results, Existing Tests, Top
+@chapter Writing Tests
+
+If the existing feature tests don't do something you need, you have to
+write new ones.  These macros are the building blocks.  They provide
+ways for other macros to check whether various kinds of features are
+available and report the results.
+
+This chapter contains some suggestions and some of the reasons why the
+existing tests are written the way they are.  You can also learn a lot
+about how to write Autoconf tests by looking at the existing ones.  If
+something goes wrong in one or more of the Autoconf tests, this
+information can help you understand the assumptions behind them, which
+might help you figure out how to best solve the problem.
+
+These macros check the output of the C compiler system.  They do
+not cache the results of their tests for future use (@pxref{Caching
+Results}), because they don't know enough about the information they are
+checking for to generate a cache variable name.  They also do not print
+any messages, for the same reason.  The checks for particular kinds of C
+features call these macros and do cache their results and print messages
+about what they're checking for.
+
+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.
+@xref{Writing Autoconf Macros}, for how to do that.
+
+@menu
+* Examining Declarations::      Detecting header files and declarations
+* Examining Syntax::            Detecting language syntax features
+* Examining Libraries::         Detecting functions and global variables
+* Run Time::                    Testing for run-time features
+* Systemology::                 A zoology of operating systems
+* Multiple Cases::              Tests for several possible values
+* Language Choice::             Selecting which language to use for testing
+@end menu
+
+@node Examining Declarations, Examining Syntax, Writing Tests, Writing Tests
+@section Examining Declarations
+
+The macro @code{AC_TRY_CPP} is used to check whether particular header
+files exist.  You can check for one at a time, or more than one if you
+need several header files to all exist for some purpose.
+
+@defmac AC_TRY_CPP (@var{includes}, @ovar{action-if-true}, @ovar{action-if-false})
+@maindex TRY_CPP
+@var{includes} is C or C++ @code{#include} statements and declarations,
+on which shell variable, back quote, and backslash substitutions are
+performed.  (Actually, it can be any C program, but other statements are
+probably not useful.)  If the preprocessor produces no error messages
+while processing it, run shell commands @var{action-if-true}.  Otherwise
+run shell commands @var{action-if-false}.
+
+This macro uses @code{CPPFLAGS}, but not @code{CFLAGS}, because
+@option{-g}, @option{-O}, etc. are not valid options to many C
+preprocessors.
+@end defmac
+
+Here is how to find out whether a header file contains a particular
+declaration, such as a typedef, a structure, a structure member, or a
+function.  Use @code{AC_EGREP_HEADER} instead of running @code{grep}
+directly on the header file; on some systems the symbol might be defined
+in another header file that the file you are checking @samp{#include}s.
+
+@defmac AC_EGREP_HEADER (@var{pattern}, @var{header-file}, @var{action-if-found}, @ovar{action-if-not-found})
+@maindex EGREP_HEADER
+If the output of running the preprocessor on the system header file
+@var{header-file} matches the @code{egrep} regular expression
+@var{pattern}, execute shell commands @var{action-if-found}, otherwise
+execute @var{action-if-not-found}.
+@end defmac
+
+To check for C preprocessor symbols, either defined by header files or
+predefined by the C preprocessor, use @code{AC_EGREP_CPP}.  Here is an
+example of the latter:
+
+@example
+AC_EGREP_CPP(yes,
+[#ifdef _AIX
+  yes
+#endif
+], is_aix=yes, is_aix=no)
+@end example
+
+@defmac AC_EGREP_CPP (@var{pattern}, @var{program}, @ovar{action-if-found}, @ovar{action-if-not-found})
+@maindex EGREP_CPP
+@var{program} is the text of a C or C++ program, on which shell
+variable, back quote, and backslash substitutions are performed.  If the
+output of running the preprocessor on @var{program} matches the
+@code{egrep} regular expression @var{pattern}, execute shell commands
+@var{action-if-found}, otherwise execute @var{action-if-not-found}.
+
+This macro calls @code{AC_PROG_CPP} or @code{AC_PROG_CXXCPP} (depending
+on which language is current, @pxref{Language Choice}), if it hasn't
+been called already.
+@end defmac
+
+@node Examining Syntax, Examining Libraries, Examining Declarations, Writing Tests
+@section Examining Syntax
+
+To check for a syntax feature of the C, C++ or Fortran 77 compiler, such
+as whether it recognizes a certain keyword, use @code{AC_TRY_COMPILE} to
+try to compile a small program that uses that feature.  You can also use
+it to check for structures and structure members that are not present on
+all systems.
+
+@defmac AC_TRY_COMPILE (@var{includes}, @var{function-body}, @ovar{action-if-found}, @ovar{action-if-not-found})
+@maindex TRY_COMPILE
+Create a C, C++ or Fortran 77 test program (depending on which language
+is current, @pxref{Language Choice}), to see whether a function whose
+body consists of @var{function-body} can be compiled.
+
+For C and C++, @var{includes} is any @code{#include} statements needed
+by the code in @var{function-body} (@var{includes} will be ignored if
+the currently selected language is Fortran 77).  This macro also uses
+@code{CFLAGS} or @code{CXXFLAGS} if either C or C++ is the currently
+selected language, as well as @code{CPPFLAGS}, when compiling.  If
+Fortran 77 is the currently selected language then @code{FFLAGS} will be
+used when compiling.
+
+If the file compiles successfully, run shell commands
+@var{action-if-found}, otherwise run @var{action-if-not-found}.
+
+This macro does not try to link; use @code{AC_TRY_LINK} if you need to
+do that (@pxref{Examining Libraries}).
+@end defmac
+
+@node Examining Libraries, Run Time, Examining Syntax, Writing Tests
+@section Examining Libraries
+
+To check for a library, a function, or a global variable, Autoconf
+@code{configure} scripts try to compile and link a small program that
+uses it.  This is unlike Metaconfig, which by default uses @code{nm}
+or @code{ar} on the C library to try to figure out which functions are
+available.  Trying to link with the function is usually a more reliable
+approach because it avoids dealing with the variations in the options
+and output formats of @code{nm} and @code{ar} and in the location of the
+standard libraries.  It also allows configuring for cross-compilation or
+checking a function's runtime behavior if needed.  On the other hand, it
+can be slower than scanning the libraries once.
+
+A few systems have linkers that do not return a failure exit status when
+there are unresolved functions in the link.  This bug makes the
+configuration scripts produced by Autoconf unusable on those systems.
+However, some of them can be given options that make the exit status
+correct.  This is a problem that Autoconf does not currently handle
+automatically.  If users encounter this problem, they might be able to
+solve it by setting @code{LDFLAGS} in the environment to pass whatever
+options the linker needs (for example, @option{-Wl,-dn} on @sc{mips
+risc/os}).
+
+@code{AC_TRY_LINK} is used to compile test programs to test for
+functions and global variables.  It is also used by @code{AC_CHECK_LIB}
+to check for libraries (@pxref{Libraries}), by adding the library being
+checked for to @code{LIBS} temporarily and trying to link a small
+program.
+
+@defmac AC_TRY_LINK (@var{includes}, @var{function-body}, @ovar{action-if-found}, @ovar{action-if-not-found})
+@maindex TRY_LINK
+Depending on the current language (@pxref{Language Choice}), create a
+test program to see whether a function whose body consists of
+@var{function-body} can be compiled and linked.
+
+For C and C++, @var{includes} is any @code{#include} statements needed
+by the code in @var{function-body} (@var{includes} will be ignored if
+the currently selected language is Fortran 77).  This macro also uses
+@code{CFLAGS} or @code{CXXFLAGS} if either C or C++ is the currently
+selected language, as well as @code{CPPFLAGS}, when compiling.  If
+Fortran 77 is the currently selected language then @code{FFLAGS} will be
+used when compiling.  However, both @code{LDFLAGS} and @code{LIBS} will
+be used during linking in all cases.
+
+If the file compiles and links successfully, run shell commands
+@var{action-if-found}, otherwise run @var{action-if-not-found}.
+@end defmac
+
+@defmac AC_TRY_LINK_FUNC (@var{function}, @ovar{action-if-found}, @ovar{action-if-not-found})
+@maindex TRY_LINK_FUNC
+Depending on the current language (@pxref{Language Choice}), create a
+test program to see whether a program whose body consists of
+a prototype of and a call to @var{function} can be compiled and linked.
+
+If the file compiles and links successfully, run shell commands
+@var{action-if-found}, otherwise run @var{action-if-not-found}.
+@end defmac
+
+
+
+@node Run Time, Systemology, Examining Libraries, Writing Tests
+@section Checking Run Time Behavior
+
+Sometimes you need to find out how a system performs at run time, such
+as whether a given function has a certain capability or bug.  If you
+can, make such checks when your program runs instead of when it is
+configured.  You can check for things like the machine's endianness when
+your program initializes itself.
+
+If you really need to test for a run-time behavior while configuring,
+you can write a test program to determine the result, and compile and
+run it using @code{AC_TRY_RUN}.  Avoid running test programs if
+possible, because this prevents people from configuring your package for
+cross-compiling.
+
+@menu
+* Test Programs::               Running test programs
+* Guidelines::                  General rules for writing test programs
+* Test Functions::              Avoiding pitfalls in test programs
+@end menu
+
+@node Test Programs, Guidelines, Run Time, Run Time
+@subsection Running Test Programs
+
+Use the following macro if you need to test run-time behavior of the
+system while configuring.
+
+@defmac AC_TRY_RUN (@var{program}, @ovar{action-if-true}, @ovar{action-if-false}, @ovar{action-if-cross-compiling})
+@maindex TRY_RUN
+@var{program} is the text of a C program, on which shell variable and
+back quote substitutions are performed.  If it compiles and links
+successfully and returns an exit status of 0 when executed, run shell
+commands @var{action-if-true}.  Otherwise, run shell commands
+@var{action-if-false}; the exit status of the program is available in
+the shell variable @samp{$?}.  This macro uses @code{CFLAGS} or
+@code{CXXFLAGS}, @code{CPPFLAGS}, @code{LDFLAGS}, and @code{LIBS} when
+compiling.
+
+If the C compiler being used does not produce executables that run on
+the system where @code{configure} is being run, then the test program is
+not run.  If the optional shell commands @var{action-if-cross-compiling}
+are given, they are run instead.  Otherwise, @code{configure} prints
+an error message and exits.
+@end defmac
+
+Try to provide a pessimistic default value to use when cross-compiling
+makes run-time tests impossible.  You do this by passing the optional
+last argument to @code{AC_TRY_RUN}.  @code{autoconf} prints a warning
+message when creating @code{configure} each time it encounters a call to
+@code{AC_TRY_RUN} with no @var{action-if-cross-compiling} argument
+given.  You may ignore the warning, though users will not be able to
+configure your package for cross-compiling.  A few of the macros
+distributed with Autoconf produce this warning message.
+
+To configure for cross-compiling you can also choose a value for those
+parameters based on the canonical system name (@pxref{Manual
+Configuration}).  Alternatively, set up a test results cache file with
+the correct values for the host system (@pxref{Caching Results}).
+
+To provide a default for calls of @code{AC_TRY_RUN} that are embedded in
+other macros, including a few of the ones that come with Autoconf, you
+can call @code{AC_PROG_CC} before running them.  Then, if the shell
+variable @code{cross_compiling} is set to @samp{yes}, use an alternate
+method to get the results instead of calling the macros.
+
+
+@node Guidelines, Test Functions, Test Programs, Run Time
+@subsection Guidelines for Test Programs
+
+Test programs should not write anything to the standard output.  They
+should return 0 if the test succeeds, nonzero otherwise, so that success
+can be distinguished easily from a core dump or other failure;
+segmentation violations and other failures produce a nonzero exit
+status.  Test programs should @code{exit}, not @code{return}, from
+@code{main}, because on some systems (old Suns, at least) the argument
+to @code{return} in @code{main} is ignored.
+
+Test programs can use @code{#if} or @code{#ifdef} to check the values of
+preprocessor macros defined by tests that have already run.  For
+example, if you call @code{AC_HEADER_STDC}, then later on in
+@file{configure.ac} you can have a test program that includes an
+@sc{ansi} C header file conditionally:
+
+@example
+@group
+#if STDC_HEADERS
+# include <stdlib.h>
+#endif
+@end group
+@end example
+
+If a test program needs to use or create a data file, give it a name
+that starts with @file{conftest}, such as @file{conftest.data}.  The
+@code{configure} script cleans up by running @samp{rm -rf conftest*}
+after running test programs and if the script is interrupted.
+
+@node Test Functions,  , Guidelines, Run Time
+@subsection Test Functions
+
+Function declarations in test programs should have a prototype
+conditionalized for C++.  In practice, though, test programs rarely need
+functions that take arguments.
+
+@example
+#ifdef __cplusplus
+foo (int i)
+#else
+foo (i) int i;
+#endif
+@end example
+
+Functions that test programs declare should also be conditionalized for
+C++, which requires @samp{extern "C"} prototypes.  Make sure to not
+include any header files containing clashing prototypes.
+
+@example
+#ifdef __cplusplus
+extern "C" void *malloc (size_t);
+#else
+char *malloc ();
+#endif
+@end example
+
+If a test program calls a function with invalid parameters (just to see
+whether it exists), organize the program to ensure that it never invokes
+that function.  You can do this by calling it in another function that is
+never invoked.  You can't do it by putting it after a call to
+@code{exit}, because GCC version 2 knows that @code{exit} never returns
+and optimizes out any code that follows it in the same block.
+
+If you include any header files, make sure to call the functions
+relevant to them with the correct number of arguments, even if they are
+just 0, to avoid compilation errors due to prototypes.  GCC version 2
+has internal prototypes for several functions that it automatically
+inlines; for example, @code{memcpy}.  To avoid errors when checking for
+them, either pass them the correct number of arguments or redeclare them
+with a different return type (such as @code{char}).
+
+@node Systemology, Multiple Cases, Run Time, Writing Tests
+@section Systemology
+
+This section aims at presenting some systems and pointers to
+documentation.  It may help you addressing particular problems reported
+by users.
+
+@table @asis
+@item @sc{qnx 4.25}
+@cindex @sc{qnx 4.25}
+@c FIXME: Please, if you feel like writing something more precise,
+@c it'd be great.  In particular, I can't understand the difference with
+@c QNX Neutrino.
+@sc{qnx} is a realtime operating system running on Intel architecture
+meant to be scalable from the small embedded systems to hundred
+processor super-computer.  It claims to be @sc{posix} certified. More
+information is available on the @href{www.qnx.com, @sc{qnx} home page},
+including the @href{http://support.qnx.com/support/docs/qnx4/, @sc{qnx}
+man pages}.
+@end table
+
+
+@node Multiple Cases, Language Choice, Systemology, Writing Tests
+@section Multiple Cases
+
+Some operations are accomplished in several possible ways, depending on
+the @sc{unix} variant.  Checking for them essentially requires a ``case
+statement''.  Autoconf does not directly provide one; however, it is
+easy to simulate by using a shell variable to keep track of whether a
+way to perform the operation has been found yet.
+
+Here is an example that uses the shell variable @code{fstype} to keep
+track of whether the remaining cases need to be checked.
+
+@example
+@group
+AC_MSG_CHECKING([how to get file system type])
+fstype=no
+# The order of these tests is important.
+AC_TRY_CPP([#include <sys/statvfs.h>
+#include <sys/fstyp.h>],
+           [AC_DEFINE(FSTYPE_STATVFS) fstype=SVR4])
+if test $fstype = no; then
+  AC_TRY_CPP([#include <sys/statfs.h>
+#include <sys/fstyp.h>],
+             [AC_DEFINE(FSTYPE_USG_STATFS) fstype=SVR3])
+fi
+if test $fstype = no; then
+  AC_TRY_CPP([#include <sys/statfs.h>
+#include <sys/vmount.h>],
+             [AC_DEFINE(FSTYPE_AIX_STATFS) fstype=AIX])
+fi
+# (more cases omitted here)
+AC_MSG_RESULT([$fstype])
+@end group
+@end example
+
+@node Language Choice,  , Multiple Cases, Writing Tests
+@section Language Choice
+@cindex Language
+
+Autoconf-generated @code{configure} scripts check for the C compiler and
+its features by default.  Packages that use other programming languages
+(maybe more than one, e.g. C and C++) need to test features of the
+compilers for the respective languages.  The following macros determine
+which programming language is used in the subsequent tests in
+@file{configure.ac}.
+
+@defmac AC_LANG (@var{language})
+Do compilation tests using the compiler, preprocessor and file
+extensions for the specified @var{language}.
+
+Supported languages are:
+
+@table @samp
+@item C
+Do compilation tests using @code{CC} and @code{CPP} and use extension
+@file{.c} for test programs.
+
+@item C++
+Do compilation tests using @code{CXX} and @code{CXXCPP} and use
+extension @file{.C} for test programs.
+
+@item Fortran 77
+Do compilation tests using @code{F77} and use extension @file{.f} for
+test programs.
+@end table
+@end defmac
+
+@defmac AC_LANG_PUSH (@var{language})
+@maindex LANG_PUSH
+Remember the current language (as set by @code{AC_LANG}) on a stack, and
+then select the @var{language}.  Use this macro and @code{AC_LANG_POP}
+in macros that need to temporarily switch to a particular language.
+@end defmac
+
+@defmac AC_LANG_POP (@ovar{language})
+@maindex LANG_POP
+Select the language that is saved on the top of the stack, as set by
+@code{AC_LANG_PUSH}, and remove it from the stack.
+
+If given, @var{language} specifies the language we just @emph{quit}.  It
+is a good idea to specify it when it's known (which should be the
+case@dots{}), since Autoconf will detect inconsistencies.
+
+@example
+AC_LANG_PUSH(Fortran 77)
+# Perform some tests on Fortran 77.
+# ...
+AC_LANG_POP(Fortran 77)
+@end example
+@end defmac
+
+@defmac AC_REQUIRE_CPP
+@maindex REQUIRE_CPP
+Ensure that whichever preprocessor would currently be used for tests has
+been found.  Calls @code{AC_REQUIRE} (@pxref{Prerequisite Macros}) with an
+argument of either @code{AC_PROG_CPP} or @code{AC_PROG_CXXCPP},
+depending on which language is current.
+@end defmac
+
+
+
+@c ====================================================== Results of Tests.
+
+@node Results, Programming in M4, Writing Tests, 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
+
+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}.
+
+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:
+
+@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
+
+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.
+
+@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
+AC_DEFINE(EQUATION, "$a > $b")
+@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:
+
+@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
+
+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:
+
+@example
+AC_CHECK_HEADER(elf.h, [AC_DEFINE(SVR4) LIBS="$LIBS -lelf"])
+@end example
+
+@noindent
+or this:
+
+@example
+AC_CHECK_HEADER(elf.h,
+ [AC_DEFINE(SVR4)
+  LIBS="$LIBS -lelf"])
+@end example
+
+@noindent
+instead of this:
+
+@example
+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
+
+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.
+
+@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.
+
+If @var{value} is given, in addition assign it to @samp{variable}.
+@end defmac
+
+@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.
+
+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
+AC_SUBST_FILE(host_frag)
+host_frag=$srcdir/conf/sun4.mh
+@end example
+
+@noindent
+and then a @file{Makefile.in} could contain:
+
+@example
+@@host_frag@@
+@end example
+@end defmac
+
+@cindex Previous Variable
+@cindex Variable, Precious
+Running @command{configure} in different environments can be extremely
+dangerous.  If for instance the user runs @samp{CC=bizarre-cc
+./configure}, then the cache, @file{config.h} and many other output
+files will depend upon @command{bizarre-cc} being the C compiler.  If
+for some reason the user runs @command{/configure} again, or if it is
+run via @samp{./config.status --recheck}, (@xref{Automatic Remaking},
+and @pxref{config.status Invocation}), then the configuration can be
+inconsistent, composed of results depending upon two different
+compilers.
+
+Such variables are named @dfn{precious variables}, and can be declared
+as such by @code{AC_ARG_VAR}.
+
+@defmac AC_ARG_VAR (@var{variable}, @var{description})
+@maindex ARG_VAR
+Declare @var{variable} is a precious variable, and include its
+@var{description} in the variable section of @samp{./configure --help}.
+
+Being precious means that
+@itemize @minus
+@item
+@var{variable} is @code{AC_SUBST}'d.
+
+@item
+@var{variable} is kept in the cache including if it was not specified on
+the @samp{./configure} command line.  Indeed, while @command{configure}
+can notice the definition of @code{CC} in @samp{./configure
+CC=bizarre-cc}, it is impossible to notice it in @samp{CC=bizarre-cc
+./configure}, which, unfortunately, is what most users do.
+
+@item
+@var{variable} is checked for consistency between two
+@command{configure} runs.  For instance:
+
+@example
+$ ./configure --silent --config-cache
+$ CC=cc ./configure --silent --config-cache
+configure: error: `CC' was not set in the previous run
+configure: error: changes in the environment can compromise \
+the build
+configure: error: run `make distclean' and/or \
+`rm config.cache' and start over
+@end example
+
+@noindent
+and similarly if the variable is unset, or if its content is changed.
+
+
+@item
+@var{variable} is kept during automatic reconfiguration
+(@pxref{config.status Invocation}) as if it had been passed as a command
+line argument, including when no cache is used:
+
+@example
+$ CC=/usr/bin/cc ./configure undeclared_var=raboof --silent
+$ ./config.status --recheck
+running /bin/sh ./configure undeclared_var=raboof --silent \
+  CC=/usr/bin/cc  --no-create --no-recursion
+@end example
+@end itemize
+@end defmac
+
+
+@node Caching Results, Printing Messages, Setting Output Variables, Results
+@section Caching Results
+@cindex Cache
+
+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.
+
+@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.
+
+The @var{commands-to-set-it} @emph{must have no side effects} except for
+setting the variable @var{cache-id}, see below.
+@end defmac
+
+@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}.
+
+The @var{commands-to-set-it} @emph{must have no side effects} except for
+setting the variable @var{cache-id}, see below.
+@end defmac
+
+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
+@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
+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:
+
+@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
+
+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.
+
+@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
+
+@node Cache Variable Names, Cache Files, Caching Results, Caching Results
+@subsection Cache Variable Names
+@cindex Cache variable
+
+The names of cache variables should have the following format:
+
+@example
+@var{package-prefix}_cv_@var{value-type}_@var{specific-value}_@ovar{additional-options}
+@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}.
+
+@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 @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}.
+
+@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 @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
+
+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
+
+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.
+
+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.
+
+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.
+
+@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}).
+
+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.
+
+@node Cache Checkpointing,  , Cache Files, Caching Results
+@subsection Cache Checkpointing
+
+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.
+
+@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
+
+For instance:
+
+@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
+
+@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{}}
+@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.
+
+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.
+
+To diagnose static issues, i.e., when @code{autoconf} is run, see
+@ref{Reporting Messages}.
+
+@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}.
+
+This macro prints nothing if @code{configure} is run with the
+@option{--quiet} or @option{--silent} option.
+@end defmac
+
+@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}.
+
+This macro prints nothing if @code{configure} is run with the
+@option{--quiet} or @option{--silent} option.
+@end defmac
+
+@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
+AC_MSG_NOTICE([checking if stack overflow is detectable])
+@end example
+
+This macro prints nothing if @code{configure} is run with the
+@option{--quiet} or @option{--silent} option.
+@end defmac
+
+@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
+
+@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
+
+
+
+@c ====================================================== Programming in M4.
+
+@node Programming in M4, Writing Autoconf Macros, Results, Top
+@chapter Programming in M4
+
+Autoconf is written on top of two layers: @dfn{M4sugar}, which provides
+convenient macros for pure M4 programming, and @dfn{M4sh}, which
+provides macros dedicated to shell script generation.
+
+As of this version of Autoconf, these two layers are still experimental,
+and their interface might change in the future.  As a matter of fact,
+@emph{anything that is not documented must not be used}.
+
+@menu
+* M4 Quotation::                Protecting macros from unwanted expansion
+* Programming in M4sugar::      Convenient pure M4 macros
+@end menu
+
+@node M4 Quotation, Programming in M4sugar, Programming in M4, Programming in M4
+@section M4 Quotation
+@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{}
+
+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.
+
+@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
+* Quadrigraphs::                Another way to escape special characters
+* Quotation Rule Of Thumb::     One parenthesis, one quote
+@end menu
+
+@node Active Characters, One Macro Call, M4 Quotation, M4 Quotation
+@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).
+
+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.
+
+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
+
+Each time there can be a macro expansion, there is a quotation
+expansion; i.e., one level of quotes is stripped:
+
+@example
+int tab[10];
+@result{}int tab10;
+[int tab[10];]
+@result{}int tab[10];
+@end example
+
+Without this in mind, the reader will try hopelessly to use her macro
+@code{array}:
+
+@example
+define([array], [int tab[10];])
+array
+@result{}int tab10;
+[array]
+@result{}array
+@end example
+
+@noindent
+How can you correctly output the intended results@footnote{Using
+@code{defn}.}?
+
+
+@node One Macro Call, Quotation and Nested Macros, Active Characters, M4 Quotation
+@subsection One Macro Call
+
+Let's proceed on the interaction between active characters and macros
+with this small macro, which just returns its first argument:
+
+@example
+define([car], [$1])
+@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:
+
+@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.
+
+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
+
+Let's pay attention to the special characters:
+
+@example
+car(#)
+@error{}EOF in argument list
+@end example
+
+The closing parenthesis is hidden in the comment; with a hypothetical
+quoting, the top level understood it this way:
+
+@example
+car([#)]
+@end example
+
+@noindent
+Proper quotation, of course, fixes the problem:
+
+@example
+car([#])
+@result{}#
+@end example
+
+The reader will easily understand the following examples:
+
+@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
+
+With this in mind, we can explore the cases where macros invoke
+macros@dots{}
+
+
+@node Quotation and Nested Macros, Quadrigraphs, One Macro Call, M4 Quotation
+@subsection Quotation and Nested Macros
+
+The examples below use the following macros:
+
+@example
+define([car], [$1])
+define([active], [ACT, IVE])
+define([array], [int tab[10]])
+@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:
+
+@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:
+
+@example
+active
+@result{}ACT, IVE
+@end example
+
+@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
+[active]
+@result{}active
+@end example
+
+@noindent
+exactly as we already saw above.
+
+The example above, applied to a more realistic example, gives:
+
+@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.
+
+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
+define([qar], [[$1]])
+@end example
+
+@noindent
+and check that @code{qar} is properly fixed:
+
+@example
+qar([int tab[10];])
+@result{}int tab[10];
+@end example
+
+@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
+qar(active)
+@result{}ACT
+@end example
+
+@noindent
+where she wanted to reproduce what she used to do with @code{car}:
+
+@example
+car([active])
+@result{}ACT, IVE
+@end example
+
+@noindent
+Worse yet: she wants to use a macro that produces a set of @code{cpp}
+macros:
+
+@example
+define([my_includes], [#include <stdio.h>])
+car([my_includes])
+@result{}#include <stdio.h>
+qar(my_includes)
+@error{}EOF in argument list
+@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 Quadrigraphs, Quotation Rule Of Thumb, Quotation and Nested Macros, M4 Quotation
+@subsection Quadrigraphs
+@cindex quadrigraphs
+@cindex @samp{@@<:@@}
+@cindex @samp{@@:>@@}
+@cindex @samp{@@S|@@}
+@cindex @samp{@@%:@@}
+
+When writing an autoconf macro you may occasionally need to generate
+special characters that are difficult to express with the standard
+autoconf quoting rules.  For example, you may need to output the regular
+expression @samp{[^[]}, which matches any character other than @samp{[}.
+This expression contains unbalanced brackets so it cannot be put easily
+into an M4 macro.
+
+You can work around this problem by using one of the following
+@dfn{quadrigraphs}:
+
+@table @samp
+@item @@<:@@
+@samp{[}
+@item @@:>@@
+@samp{]}
+@item @@S|@@
+@samp{$}
+@item @@%:@@
+@samp{#}
+@end table
+
+Quadrigraphs are replaced at a late stage of the translation process,
+after @command{m4} is run, so they do not get in the way of M4 quoting.
+For example, the string @samp{[^@@<:@@]}, if properly quoted, will
+appear as @samp{[^[]} in the @code{configure} script.
+
+
+@node Quotation Rule Of Thumb,  , Quadrigraphs, M4 Quotation
+@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
+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
+which is incredibly useless since @code{AC_TRY_LINK} is @emph{already}
+double quoting, so you just need:
+
+@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])
+@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!
+
+Simplified, the example above is just doing this:
+
+@example
+changequote(<<, >>)dnl
+<<[]>>
+changequote([, ])dnl
+@end example
+
+@noindent
+instead of simply:
+
+@example
+[[]]
+@end example
+
+
+With macros that do not double quote their arguments (which is the
+rule), double-quote the (risky) literals:
+
+@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
+
+See @xref{Quadrigraphs}, for what to do if you run into a hopeless case
+where quoting does not suffice.
+
+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}.
+
+
+@node Programming in M4sugar,  , M4 Quotation, Programming in M4
+@section Programming in M4sugar
+
+@cindex M4sugar
+M4 by itself provides only a small, but sufficient, set of all-purpose
+macros.  M4sugar introduces additional generic macros.  Its name was
+coined by Lars J. Aas: ``Readability And Greater Understanding Stands 4
+M4sugar''.
+
+@menu
+* Redefined M4 Macros::         M4 builtins changed in M4sugar
+* Forbidden Patterns::          Catching unexpanded macros
+@end menu
+
+@node Redefined M4 Macros, Forbidden Patterns, Programming in M4sugar, Programming in M4sugar
+@subsection Redefined M4 Macros
+
+All the M4 native macros are moved in the @samp{m4_} pseudo-namespace,
+e.g., M4sugar renames @code{define} as @code{m4_define} etc.  There is
+one exception: @code{dnl} kept its original name, and no @code{m4_dnl}
+is defined.
+
+M4sugar redefines some M4 macros, and made them slightly incompatible
+with their native equivalent.
+
+@defmac m4_defn (@var{macro})
+@msindex defn
+Contrary to the M4 builtin, this macro fails if @var{macro} is not
+defined.  See @code{m4_undefine}.
+@end defmac
+
+@defmac m4_undefine (@var{macro})
+@msindex undefine
+Contrary to the M4 builtin, this macro fails if @var{macro} is not
+defined.  Use
+
+@example
+m4_ifdef([@var{macro}], [m4_undefine([@var{macro}])])
+@end example
+
+@noindent
+to recover the behavior of the builtin.
+@end defmac
+
+@defmac m4_popdef (@var{macro})
+@msindex defn
+Contrary to the M4 builtin, this macro fails if @var{macro} is not
+defined.  See @code{m4_undefine}.
+@end defmac
+
+@node Forbidden Patterns,  , Redefined M4 Macros, Programming in M4sugar
+@subsection Forbidden Patterns
+
+M4sugar provides a means to define suspicious patterns, patterns
+describing tokens which should not be found in the output.  For
+instance, if an Autoconf @file{configure} script includes tokens such as
+@samp{AC_DEFINE}, or @samp{dnl}, then most probably something went
+wrong (typically a macro was not evaluated because of over quotation).
+
+M4sugar forbids all the tokens matching @samp{^m4_} and @samp{^dnl$}.
+
+@defmac m4_pattern_forbid (@var{pattern})
+@msindex pattern_forbid
+Declare no token matching @var{pattern} must be found in the output.
+Comments are not checked; this can be a problem if, for instance, you
+have some macro left unexpanded after an @samp{#include}.  No consensus
+is currently found in the Autoconf community, as some people consider it
+should be valid to name macros in comments (which doesn't makes sense to
+the author of this documentation, as @samp{#}-comments should document
+the output, not the input, documented vy @samp{dnl}-comments).
+@end defmac
+
+Of course, you might encounter exceptions to these generic rules, for
+instance you might have to refer to @samp{$m4_flags}.
+
+@defmac m4_pattern_allow (@var{pattern})
+@msindex pattern_allow
+Any token matching @var{pattern} is allowed, including if it matches an
+@code{m4_pattern_forbid} pattern.
+@end defmac
+
+@c=================================================== Writing Autoconf Macros.
+
+@node Writing Autoconf Macros, Portable Shell, Programming in M4, Top
+@chapter Writing Autoconf Macros
+
+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.
+
+@menu
+* Macro Definitions::           Basic format of an Autoconf macro
+* Macro Names::                 What to call your new macros
+* 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 Autoconf Macros, Writing Autoconf 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:
+
+@example
+AC_DEFUN(@var{macro-name}, @var{macro-body})
+@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.
+
+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.
+
+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
+# AC_MSG_ERROR(ERROR, [EXIT-STATUS = 1])
+# --------------------------------------
+define([AC_MSG_ERROR],
+[@{ _AC_ECHO([configure: error: $1], 2); exit m4_default([$2], 1); @}])
+@end example
+
+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.
+
+@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 Macro Names, Reporting Messages, Macro Definitions, Writing Autoconf Macros
+@section Macro Names
+
+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.
+
+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.
+
+@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.
+
+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}.
+
+@node Reporting Messages, Dependencies Between Macros, Macro Names, Writing Autoconf 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}.
+
+@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 cross
+related to cross compilation issues.
+
+@item obsolete
+use of an obsolete construct.
+
+@item syntax
+dubious syntactic constructs, incorrectly ordered macro calls.
+@end table
+@end defmac
+
+@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
+
+@defmac AC_FATAL (@var{message})
+@maindex FATAL
+Report a severe error @var{message}, and have @code{autoconf} die.
+@end defmac
+
+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}.
+
+@node Dependencies Between Macros, Obsoleting Macros, Reporting Messages, Writing Autoconf Macros
+@section Dependencies Between Macros
+
+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
+
+@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}.
+
+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.
+
+@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
+@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
+@end example
+
+@noindent
+with this @file{configure.ac}
+
+@example
+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
+will not leave you with a better chance to meet a kindred soul at
+other times than Saturday night since it expands into:
+
+@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
+
+
+fi
+@end group
+@end example
+
+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
+@group
+if @dots{}; then
+  AC_REQUIRE([SOME_CHECK])
+fi
+@dots{}
+SOME_CHECK
+@end group
+@end example
+
+
+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.
+
+@node Suggested Ordering,  , Prerequisite Macros, Dependencies Between Macros
+@subsection Suggested Ordering
+
+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.
+
+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}.
+
+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
+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.
+
+@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 Autoconf Macros
+@section Obsoleting Macros
+
+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.
+
+@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
+
+@node Coding Style,  , Obsoleting Macros, Writing Autoconf Macros
+@section Coding Style
+
+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.
+
+The first requirement is to pay great attention to the quotation, for
+more details, see @ref{Autoconf Language}, and @ref{M4 Quotation}.
+
+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
+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
+write
+
+@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
+
+@noindent
+or even
+
+@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}).
+
+Feel free to use various tricks to prevent auxiliary tools, such as
+syntax-highlighting editors, from behaving improperly.  For instance,
+instead of:
+
+@example
+patsubst([$1], [$"])
+@end example
+
+@noindent
+use
+
+@example
+patsubst([$1], [$""])
+@end example
+
+@noindent
+so that Emacsen do not open a endless ``string'' at the first quote.
+For the same reasons, avoid:
+
+@example
+test $[#] != 0
+@end example
+
+@noindent
+and use:
+
+@example
+test $[@@%:@@] != 0
+@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{,}.
+
+@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
+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
+you would write:
+
+@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
+
+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.
+
+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
+
+@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 ============================================= Portable Shell Programming
+
+@node Portable Shell, Manual Configuration, Writing Autoconf 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
+#! /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.
+
+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.
+
+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
+
+@node Shellology, Here-Documents, Portable Shell, Portable Shell
+@section Shellology
+
+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.
+
+@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.
+
+To be compatible with Ash 0.2:
+
+@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
+don't use command substitution within variable expansion:
+
+@example
+cat $@{FOO=`bar`@}
+@end example
+
+@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:
+
+@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
+existent 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:
+
+@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}
+
+@example
+@group
+$ cat <<EOF
+> \" \\
+> EOF
+" \
+@end group
+@end example
+
+@noindent
+and with Bash:
+
+@example
+@group
+bash-2.04$ cat <<EOF
+> \" \\
+> EOF
+\" \
+@end group
+@end example
+
+
+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
+
+Some file descriptors shall not be used, since some systems, admittedly
+arcane, use them for special purpose:
+
+@table @asis
+@item 3
+some systems may open it to @samp{/dev/tty}.
+
+@item 4
+used on the Kubota Titan.
+@end table
+
+Don't redirect several times the same file descriptor, as you are doomed
+to failure under Ultrix.
+
+@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.
+@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:
+
+@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
+@end example
+
+@noindent
+You'll appreciate the various levels of detail@dots{}
+
+One workaround is to grep out uninteresting lines, hoping not to remove
+good ones@dots{}
+
+@node File System Conventions, Shell Substitutions, File Descriptors, Portable Shell
+@section File System Conventions
+
+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
+For example, the following code:
+
+@example
+case $foo_dir in
+  /*) # Absolute
+     ;;
+  *)
+     foo_dir=$dots$foo_dir ;;
+esac
+@end example
+
+@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:
+
+@example
+case $foo_dir in
+  [\\/]* | ?:[\\/]* ) # Absolute
+     ;;
+  *)
+     foo_dir=$dots$foo_dir ;;
+esac
+@end example
+
+@noindent
+Make sure you quote the brackets if appropriate and keep the backslash as
+first character (@pxref{Limitations of Builtins}).
+
+Also, because the colon is used as part of a drivespec, these systems don't
+use it as path separator.  When creating or accessing paths, 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.
+
+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.
+
+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.
+
+@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 is perfectly OK on Unices:
+
+@example
+AC_CONFIG_HEADER(config.h)
+AC_CONFIG_FILES([source.c foo.bar])
+AC_OUTPUT
+@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
+
+@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}.
+
+@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 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}.
+
+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 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
+
+@node Shell Substitutions, Assignments, File System Conventions, Portable Shell
+@section Shell Substitutions
+
+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
+: $@{var='Some words'@}
+@end example
+
+@noindent
+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
+$ 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.
+
+@item $@{@var{var}=@var{expanded-value}@}
+@cindex $@{@var{var}=@var{expanded-value}@}
+On Ultrix,
+running
+
+@example
+default="yu,yaa"
+: $@{var="$default"@}
+@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:
+
+@example
+$ cat -v <<EOF
+$var
+EOF
+@end example
+
+@noindent
+and
+
+@example
+$ set | grep '^var=' | cat -v
+@end example
+
+One classic incarnation of this bug is:
+
+@example
+default="a b c"
+: $@{list="$default"@}
+for c in $list; do
+  echo $c
+done
+@end example
+
+@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!!!
+
+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}!
+
+The portable way out consists in using a double assignment, to switch
+the 8th bit twice on Ultrix:
+
+@example
+list=$@{list="$default"@}
+@end example
+
+@noindent
+@dots{}but beware of the @samp{@}} bug from Solaris (see above).  For safety,
+use:
+
+@example
+test "$@{var+set@}" = set || var=@var{@{value@}}
+@end example
+
+
+@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.
+
+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.
+
+
+@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:
+
+@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
+$ uname -a
+IRIX firebird-image 6.5 07151432 IP22
+$ echo $(echo blah)
+$(echo blah)
+@end example
+@end table
+
+
+@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
+
+@noindent
+and to make things even worse, @sc{qnx 4.25} just sets the exit status
+to 0 in any case:
+
+@example
+$ foo=`exit 1`; echo $?
+0
+@end example
+
+To assign default values, follow this algorithm:
+
+@enumerate
+@item
+If the default value is a literal and does not contain any closing
+brace, use:
+
+@example
+: $@{var='my literal'@}
+@end example
+
+@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:
+
+@example
+: $@{var="$default"@}
+@end example
+
+@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
+var=$@{var="$default"@}
+@end example
+
+@item
+If the default value contains a closing brace, then use:
+
+@example
+test "$@{var+set@}" = set || var='$@{indirection@}'
+@end example
+@end enumerate
+
+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 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 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.
+
+@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:
+
+@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
+
+@noindent
+(of course we could just @code{unset} @code{CDPATH}, since it also
+behaves properly if set to the empty string).
+
+Life wouldn't be so much fun if @command{bash} and @command{zsh} had the
+same behavior:
+
+@example
+bash-2.02 % (CDPATH=:. cd foo)
+bash-2.02 % (CDPATH=.: cd foo)
+/tmp/foo
+@end example
+
+Therefore, a portable solution to neutralize @samp{CDPATH} is
+
+@example
+CDPATH=$@{ZSH_VERSION+.@}:
+@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{;}.
+
+@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 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! :)
+
+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.
+
+@table @asis
+@item @command{!}
+@cindex @command{!}
+You can't use @command{!}, you'll have to rewrite your code.
+
+
+@item @command{break}
+@c ------------------
+@cindex @command{break}
+The use of @samp{break 2}, etcetera, is safe.
+
+
+@item @command{case}
+@c -----------------
+@cindex @command{case}
+You don't need to quote the argument; no splitting is performed.
+
+You don't need the final @samp{;;}, but you should use it.
+
+Because of a bug in its @code{fnmatch}, @command{bash} fails to properly
+handle backslashes in character classes:
+
+@example
+bash-2.02$ case /tmp in [/\\]*) echo OK;; esac
+bash-2.02$
+@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:
+
+@example
+bash-2.02$ case '\TMP' in [\\/]*) echo OK;; esac
+OK
+bash-2.02$ case /tmp in [\\/]*) echo OK;; esac
+OK
+@end example
+
+
+@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}.
+
+Don't expect any option.  @xref{Preset Output Variables}, @code{ECHO_N}
+etc. for a means to simulate @option{-c}.
+
+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
+cat <<EOF
+$foo
+EOF
+@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}.
+
+@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$
+@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.
+
+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.
+
+
+@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.
+
+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
+#! /bin/sh
+echo $FOO
+FOO=bar
+echo $FOO
+exec /bin/sh $0
+@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.
+
+
+@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
+for arg
+do
+  echo "$arg"
+done
+@end example
+
+@noindent
+You may @emph{not} leave the @code{do} on the same line as @code{for},
+since some shells improperly grok:
+
+@example
+for arg; do
+  echo "$arg"
+done
+@end example
+
+If you want to explicitly refer to the positional arguments, given the
+@samp{$@@} bug (@pxref{Shell Substitutions}), use:
+
+@example
+for arg in $@{1+"$@@"@}; do
+  echo "$arg"
+done
+@end example
+
+@item @command{if}
+@c ---------------
+@cindex @command{if}
+Using @samp{!} is not portable.  Instead of:
+
+@example
+if ! cmp -s file file.new; then
+  mv file.new file
+fi
+@end example
+
+@noindent
+use:
+
+@example
+if cmp -s file file.new; then :; else
+  mv file.new file
+fi
+@end example
+
+There are shells that do not reset the exit status from an @command{if}:
+
+@example
+$ if (exit 42); then true; fi; echo $?
+42
+@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:
+
+@example
+if test -f "$file"; then
+  install "$file" "$dest"
+else
+  :
+fi
+@end example
+
+
+@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
+set x $my_list; shift
+@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.
+
+@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.
+
+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}.
+
+@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.
+
+@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
+$ 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.
+
+It is frequent to find variations of the following idiom:
+
+@example
+test -n "`echo $ac_feature | sed 's/[-a-zA-Z0-9_]//g'`" &&
+  @var{action}
+@end example
+
+@noindent
+to take an action when a token matches a given pattern.  Such constructs
+should always be avoided by using:
+
+@example
+echo "$ac_feature" | grep '[^-a-zA-Z0-9_]' >/dev/null 2>&1 &&
+  @var{action}
+@end example
+
+@noindent
+Use @code{case} where possible since it is faster, being a shell builtin:
+
+
+@example
+case $ac_feature in
+  *[!-a-zA-Z0-9_]*) @var{action};;
+esac
+@end example
+
+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
+expr "$ac_feature" : '.*[^-a-zA-Z0-9_]' >/dev/null &&
+  @var{action}
+@end example
+
+@noindent
+or better yet
+
+@example
+expr "x$ac_feature" : '.*[^-a-zA-Z0-9_]' >/dev/null &&
+  @var{action}
+@end example
+
+@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.
+
+
+@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).
+
+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?''
+
+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
+$ cat trap.sh
+trap 'echo $?' 0
+(exit 42); exit 0
+$ zsh trap.sh
+42
+$ bash trap.sh
+0
+@end example
+
+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
+$ trap 'false
+
+echo $?' 0
+$ exit
+0
+@end example
+
+@noindent
+Fortunately, this bug only affects @command{trap}.
+
+@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
+if (unset FOO) >/dev/null 2>&1; then
+  unset=unset
+else
+  unset=false
+fi
+$unset CDPATH || CDPATH=:
+@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
+
+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
+
+If you want your program to be deterministic, don't depend on @code{for}
+on arrays:
+
+@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
+@end example
+
+Some AWK, such as HPUX 11.0's native one, have regex engines fragile to
+inner anchors:
+
+@example
+$ echo xfoo | $AWK '/foo|^bar/ @{ print @}'
+$ echo bar | $AWK '/foo|^bar/ @{ print @}'
+bar
+$ echo xfoo | $AWK '/^bar|foo/ @{ print @}'
+xfoo
+$ echo bar | $AWK '/^bar|foo/ @{ print @}'
+bar
+@end example
+
+@noindent
+Either do not depend on such patterns (i.e., use @samp{/^(.*foo|bar)/},
+or use a simple test to reject such AWK.
+
+
+@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.
+
+
+@item @command{cc}
+@c ---------------
+When a compilation such as @samp{cc foo.c -o foo} fails, some compilers
+(such as @sc{cds} on Reliant @sc{unix}) leave a @file{foo.o}.
+
+
+@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.
+
+
+@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???
+
+
+@item @command{diff}
+@c -----------------
+@cindex @command{diff}
+Option @option{-u} is nonportable.
+
+Some implementations, such as Tru64's, fail when comparing to
+@file{/dev/null}.  Use an empty file instead.
+
+@item @command{dirname}
+@c --------------------
+@cindex @command{dirname}
+Not all hosts have @command{dirname}, but it is reasonably easy to
+emulate, e.g.:
+
+@example
+dir=`expr "x$file" : 'x\(.*\)/[^/]*' \|
+          '.'      : '.'
+@end example
+
+@noindent
+But there are a few subtilities, e.g., under UN*X, should @samp{//1}
+give @samp{/}?  Paul Eggert answers:
+
+@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.
+
+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.
+
+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
+
+
+@item @command{egrep}
+@c ------------------
+@cindex @command{egrep}
+The empty alternative is not portable, use @samp{?} instead. For
+instance with Digital Unix v5.0:
+
+@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
+
+@command{egrep} also suffers the limitations of @command{grep}.
+
+
+@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}.
+
+Don't use @code{length}, @code{substr}, @code{match} and @code{index}.
+
+@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
+expr '' \| ''
+@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:
+
+@example
+expr bar : foo \| foo : bar
+@end example
+
+@noindent
+Avoid this portability problem by avoiding the empty string.
+
+
+@item @command{expr} (@samp{:})
+@c ----------------------------
+@cindex @command{expr}
+Don't use @samp{\?}, @samp{\+} and @samp{\|} in patterns, they are
+not supported on Solaris.
+
+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}.
+
+You may believe that one means to get a uniform behavior would be to use
+the empty string as a default value:
+
+@example
+expr a : b \| ''
+@end example
+
+@noindent
+unfortunately this behaves exactly as the original expression, see the
+@samp{@command{expr} (@samp{:})} entry for more information.
+
+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.
+
+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
+
+@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
+$ expr 'a' : '\(a\)' || echo 'a' | sed 's/^\(a\)$/\1/'
+@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.
+
+
+@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.
+
+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}.
+
+
+@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.
+
+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}.
+
+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.
+
+Moving directories across mount points is not portable, use @command{cp}
+and @command{rm}.
+
+
+@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,[^/]*$,,}.
+
+Sed scripts should not use branch labels longer than 8 characters and
+should not contain comments.
+
+Don't include extra @samp{;}, as some @command{sed}, such as NetBSD
+1.4.2's, try to interpret the second as a command:
+
+@example
+$ echo a | sed 's/x/x/;;s/x/x/'
+sed: 1: "s/x/x/;;s/x/x/": invalid command code ;
+@end example
+
+Input should have reasonably long lines, since some @command{sed} have
+an input buffer limited to 4000 bytes.
+
+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.
+
+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.
+
+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
+sed -e @var{instruction-1} \
+    -e @var{instruction-2}
+@end example
+
+@noindent
+as opposed to
+
+@example
+sed @var{instruction-1};@var{instruction-2}
+@end example
+
+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''.
+
+
+@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
+s/keep me/kept/g  # a
+t end             # b
+s/.*/deleted/g    # c
+: end             # d
+@end example
+
+@noindent
+on
+
+@example
+delete me         # 1
+delete me         # 2
+keep me           # 3
+delete me         # 4
+@end example
+
+@noindent
+you get
+
+@example
+deleted
+delete me
+kept
+deleted
+@end example
+
+@noindent
+instead of
+
+@example
+deleted
+deleted
+kept
+deleted
+@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.
+
+One portable implementation of the script above is:
+
+@example
+t clear
+: clear
+s/keep me/kept/g
+t end
+s/.*/deleted/g
+: end
+@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
+
+
+@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 Leading underscore in macro names
+Some Make don't support leading underscores in macro names, such as on
+NEWS-OS 4.2R.
+
+@example
+$ cat Makefile
+_am_include = #
+_am_quote =
+all:; @@echo this is test
+
+% make
+Make: Must be a separator on rules line 2.  Stop.
+
+$ cat Makefile2
+am_include = #
+am_quote =
+all:; @@echo this is test
+
+$ make -f Makefile2
+this is test
+@end example
+
+@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 ================================================== Manual Configuration
+
+@node Manual Configuration, Site Configuration, Portable Shell, Top
+@chapter Manual Configuration
+
+A few kinds of features can't be guessed automatically by running test
+programs.  For example, the details of the object-file format, or
+special options that need to be passed to the compiler or linker.  You
+can check for such features using ad-hoc means, such as having
+@code{configure} check the output of the @code{uname} program, or
+looking for libraries that are unique to particular systems.  However,
+Autoconf provides a uniform method for handling unguessable features.
+
+@menu
+* Specifying Names::            Specifying the system type
+* Canonicalizing::              Getting the canonical system type
+* Using System Type::           What to do with the system type
+@end menu
+
+@node Specifying Names, Canonicalizing, Manual Configuration, Manual Configuration
+@section Specifying the System Type
+
+Like other @sc{gnu} @code{configure} scripts, Autoconf-generated
+@code{configure} scripts can make decisions based on a canonical name
+for the system type, which has the form:
+@samp{@var{cpu}-@var{vendor}-@var{os}}, where @var{os} can be
+@samp{@var{system}} or @samp{@var{kernel}-@var{system}}
+
+@code{configure} can usually guess the canonical name for the type of
+system it's running on.  To do so it runs a script called
+@code{config.guess}, which infers the name using the @code{uname}
+command or symbols predefined by the C preprocessor.
+
+Alternately, the user can specify the system type with command line
+arguments to @code{configure}.  Doing so is necessary when
+cross-compiling.  In the most complex case of cross-compiling, three
+system types are involved.  The options to specify them are@footnote{For
+backward compatibility, @code{configure} will accept a system type as an
+option by itself.  Such an option will override the defaults for build,
+host and target system types.  The following configure statement will
+configure a cross toolchain that will run on NetBSD/alpha but generate
+code for GNU Hurd/sparc, which is also the build platform.
+
+@example
+./configure --host=alpha-netbsd sparc-gnu
+@end example
+}:
+
+@table @option
+@item --build=@var{build-type}
+the type of system on which the package is being configured and
+compiled.
+
+@item --host=@var{host-type}
+@ovindex cross_compiling
+the type of system on which the package will run.
+
+@item --target=@var{target-type}
+the type of system for which any compiler tools in the package will
+produce code (rarely needed).  By default, it is the same as host.
+@end table
+
+They all default to the result of running @code{config.guess}, unless
+you specify either @option{--build} or @option{--host}.  In this case, the
+default becomes the system type you specified.  If you specify both, and
+they're different, @code{configure} will enter cross compilation mode,
+so it won't run any tests that require execution.
+
+Hint: if you mean to override the result of @code{config.guess}, prefer
+@option{--build} over @option{--host}.  In the future, @option{--host} will
+not override the name of the build system type.  Also, if you specify
+@option{--host}, but not @option{--build}, when @code{configure} performs
+the first compiler test it will try to run an executable produced by the
+compiler.  If the execution fails, it will enter cross-compilation mode.
+Note, however, that it won't guess the build-system type, since this may
+require running test programs.  Moreover, by the time the compiler test
+is performed, it may be too late to modify the build-system type: other
+tests may have already been performed.  Therefore, whenever you specify
+@code{--host}, be sure to specify @code{--build} too.
+
+@example
+./configure --build=i686-pc-linux-gnu --host=m68k-coff
+@end example
+
+@noindent
+will enter cross-compilation mode, but @code{configure} will fail if it
+can't run the code generated by the specified compiler if you configure
+as follows:
+
+@example
+./configure CC=m68k-coff-gcc
+@end example
+
+@code{configure} recognizes short aliases for many system types; for
+example, @samp{decstation} can be used instead of
+@samp{mips-dec-ultrix4.2}.  @code{configure} runs a script called
+@code{config.sub} to canonicalize system type aliases.
+
+
+
+@node Canonicalizing, Using System Type, Specifying Names, Manual Configuration
+@section Getting the Canonical System Type
+
+The following macros make the system type available to @code{configure}
+scripts.
+
+@ovindex build_alias
+@ovindex host_alias
+@ovindex target_alias
+
+The variables @samp{build_alias}, @samp{host_alias}, and
+@samp{target_alias} are always exactly the arguments of @option{--build},
+@option{--host}, and @option{--target}; in particular, they are left empty
+if the user did not use them, even if the corresponding
+@code{AC_CANONICAL} macro was run.  Any configure script may use these
+variables anywhere.  These are the variables that should be used when in
+interaction with the user.
+
+If you need to recognize some special environments based on their system
+type, run the following macros to get canonical system names.  These
+variables are not set before the macro call.
+
+If you use these macros, you must distribute @code{config.guess} and
+@code{config.sub} along with your source code.  @xref{Output}, for
+information about the @code{AC_CONFIG_AUX_DIR} macro which you can use
+to control in which directory @code{configure} looks for those scripts.
+
+
+@defmac AC_CANONICAL_BUILD
+@maindex CANONICAL_BUILD
+@ovindex build
+@ovindex build_cpu
+@ovindex build_vendor
+@ovindex build_os
+Compute the canonical build-system type variable, @code{build}, and its
+three individual parts @code{build_cpu}, @code{build_vendor}, and
+@code{build_os}.
+
+If @option{--build} was specified, then @code{build} is the
+canonicalization of @code{build_alias} by @command{config.sub},
+otherwise it is determined by the shell script @code{config.guess}.
+@end defmac
+
+@defmac AC_CANONICAL_HOST
+@maindex CANONICAL_HOST
+@ovindex host
+@ovindex host_cpu
+@ovindex host_vendor
+@ovindex host_os
+Compute the canonical host-system type variable, @code{host}, and its
+three individual parts @code{host_cpu}, @code{host_vendor}, and
+@code{host_os}.
+
+If @option{--host} was specified, then @code{host} is the
+canonicalization of @code{host_alias} by @command{config.sub},
+otherwise it defaults to @code{build}.
+
+For temporary backward-compatibility, when @option{--host} is specified
+by @option{--build} isn't, the build system will be assumed to be the
+same as @option{--host}, and @samp{build_alias} will be set to that
+value.  Eventually, this historically incorrect behavior will go away.
+
+@end defmac
+
+@defmac AC_CANONICAL_TARGET
+@maindex CANONICAL_TARGET
+@ovindex target
+@ovindex target_cpu
+@ovindex target_vendor
+@ovindex target_os
+Compute the canonical target-system type variable, @code{target}, and its
+three individual parts @code{target_cpu}, @code{target_vendor}, and
+@code{target_os}.
+
+If @option{--target} was specified, then @code{target} is the
+canonicalization of @code{target_alias} by @command{config.sub},
+otherwise it defaults to @code{host}.
+@end defmac
+
+
+@node Using System Type,  , Canonicalizing, Manual Configuration
+@section Using the System Type
+
+How do you use a canonical system type?  Usually, you use it in one or
+more @code{case} statements in @file{configure.ac} to select
+system-specific C files.  Then, using @code{AC_CONFIG_LINKS}, link those
+files which have names based on the system name, to generic names, such
+as @file{host.h} or @file{target.c} (@pxref{Configuration Links}).  The
+@code{case} statement patterns can use shell wild cards to group several
+cases together, like in this fragment:
+
+@example
+case "$target" in
+i386-*-mach* | i386-*-gnu*)
+             obj_format=aout emulation=mach bfd_gas=yes ;;
+i960-*-bout) obj_format=bout ;;
+esac
+@end example
+
+@noindent
+and in @file{configure.ac}, use:
+
+@example
+AC_CONFIG_LINKS(host.h:config/$machine.h
+                object.h:config/$obj_format.h)
+@end example
+
+You can also use the host system type to find cross-compilation tools.
+@xref{Generic Programs}, for information about the @code{AC_CHECK_TOOL}
+macro which does that.
+
+
+@c ===================================================== Site Configuration.
+
+@node Site Configuration, Running configure scripts, Manual Configuration, Top
+@chapter Site Configuration
+
+@code{configure} scripts support several kinds of local configuration
+decisions.  There are ways for users to specify where external software
+packages are, include or exclude optional features, install programs
+under modified names, and set default values for @code{configure}
+options.
+
+@menu
+* External Software::           Working with other optional software
+* Package Options::             Selecting optional features
+* Pretty Help Strings::         Formatting help string
+* Site Details::                Configuring site details
+* Transforming Names::          Changing program names when installing
+* Site Defaults::               Giving @code{configure} local defaults
+@end menu
+
+@node External Software, Package Options, Site Configuration, Site Configuration
+@section Working With External Software
+
+Some packages require, or can optionally use, other software packages
+that are already installed.  The user can give @code{configure}
+command line options to specify which such external software to use.
+The options have one of these forms:
+
+@example
+--with-@var{package}=@ovar{arg}
+--without-@var{package}
+@end example
+
+For example, @option{--with-gnu-ld} means work with the @sc{gnu} linker
+instead of some other linker.  @option{--with-x} means work with The X
+Window System.
+
+The user can give an argument by following the package name with
+@samp{=} and the argument.  Giving an argument of @samp{no} is for
+packages that are used by default; it says to @emph{not} use the
+package.  An argument that is neither @samp{yes} nor @samp{no} could
+include a name or number of a version of the other package, to specify
+more precisely which other package this program is supposed to work
+with.  If no argument is given, it defaults to @samp{yes}.
+@option{--without-@var{package}} is equivalent to
+@option{--with-@var{package}=no}.
+
+@code{configure} scripts do not complain about
+@option{--with-@var{package}} options that they do not support.  This
+behavior permits configuring a source tree containing multiple packages
+with a top-level @code{configure} script when the packages support
+different options, without spurious error messages about options that
+some of the packages support.  An unfortunate side effect is that option
+spelling errors are not diagnosed.  No better approach to this problem
+has been suggested so far.
+
+For each external software package that may be used, @file{configure.ac}
+should call @code{AC_ARG_WITH} to detect whether the @code{configure}
+user asked to use it.  Whether each package is used or not by default,
+and which arguments are valid, is up to you.
+
+@defmac AC_ARG_WITH (@var{package}, @var{help-string}, @ovar{action-if-given}, @ovar{action-if-not-given})
+@maindex ARG_WITH
+If the user gave @code{configure} the option @option{--with-@var{package}}
+or @option{--without-@var{package}}, run shell commands
+@var{action-if-given}.  If neither option was given, run shell commands
+@var{action-if-not-given}.  The name @var{package} indicates another
+software package that this program should work with.  It should consist
+only of alphanumeric characters and dashes.
+
+The option's argument is available to the shell commands
+@var{action-if-given} in the shell variable @code{withval}, which is
+actually just the value of the shell variable @code{with_@var{package}},
+with any @option{-} characters changed into @samp{_}.  You may use that
+variable instead, if you wish.
+
+The argument @var{help-string} is a description of the option that
+looks like this:
+@example
+  --with-readline         support fancy command line editing
+@end example
+
+@noindent
+@var{help-string} may be more than one line long, if more detail is
+needed.  Just make sure the columns line up in @samp{configure --help}.
+Avoid tabs in the help string.  You'll need to enclose it in @samp{[}
+and @samp{]} in order to produce the leading spaces.
+
+You should format your @var{help-string} with the macro
+@code{AC_HELP_STRING} (@pxref{Pretty Help Strings}).
+@end defmac
+
+@defmac AC_WITH (@var{package}, @var{action-if-given}, @ovar{action-if-not-given})
+@maindex WITH
+This is an obsolete version of @code{AC_ARG_WITH} that does not
+support providing a help string.
+@end defmac
+
+@node Package Options, Pretty Help Strings, External Software, Site Configuration
+@section Choosing Package Options
+
+If a software package has optional compile-time features, the user can
+give @code{configure} command line options to specify whether to
+compile them.  The options have one of these forms:
+
+@example
+--enable-@var{feature}=@ovar{arg}
+--disable-@var{feature}
+@end example
+
+These options allow users to choose which optional features to build and
+install.  @option{--enable-@var{feature}} options should never make a
+feature behave differently or cause one feature to replace another.
+They should only cause parts of the program to be built rather than left
+out.
+
+The user can give an argument by following the feature name with
+@samp{=} and the argument.  Giving an argument of @samp{no} requests
+that the feature @emph{not} be made available.  A feature with an
+argument looks like @option{--enable-debug=stabs}.  If no argument is
+given, it defaults to @samp{yes}.  @option{--disable-@var{feature}} is
+equivalent to @option{--enable-@var{feature}=no}.
+
+@code{configure} scripts do not complain about
+@option{--enable-@var{feature}} options that they do not support.
+This behavior permits configuring a source tree containing multiple
+packages with a top-level @code{configure} script when the packages
+support different options, without spurious error messages about options
+that some of the packages support.
+An unfortunate side effect is that option spelling errors are not diagnosed.
+No better approach to this problem has been suggested so far.
+
+For each optional feature, @file{configure.ac} should call
+@code{AC_ARG_ENABLE} to detect whether the @code{configure} user asked
+to include it.  Whether each feature is included or not by default, and
+which arguments are valid, is up to you.
+
+@defmac AC_ARG_ENABLE (@var{feature}, @var{help-string}, @ovar{action-if-given}, @ovar{action-if-not-given})
+@maindex ARG_ENABLE
+If the user gave @code{configure} the option
+@option{--enable-@var{feature}} or @option{--disable-@var{feature}}, run
+shell commands @var{action-if-given}.  If neither option was given, run
+shell commands @var{action-if-not-given}.  The name @var{feature}
+indicates an optional user-level facility.  It should consist only of
+alphanumeric characters and dashes.
+
+The option's argument is available to the shell commands
+@var{action-if-given} in the shell variable @code{enableval}, which is
+actually just the value of the shell variable
+@code{enable_@var{feature}}, with any @option{-} characters changed into
+@samp{_}.  You may use that variable instead, if you wish.  The
+@var{help-string} argument is like that of @code{AC_ARG_WITH}
+(@pxref{External Software}).
+
+You should format your @var{help-string} with the macro
+@code{AC_HELP_STRING} (@pxref{Pretty Help Strings}).
+@end defmac
+
+@defmac AC_ENABLE (@var{feature}, @var{action-if-given}, @ovar{action-if-not-given})
+@maindex ENABLE
+This is an obsolete version of @code{AC_ARG_ENABLE} that does not
+support providing a help string.
+@end defmac
+
+
+@node Pretty Help Strings, Site Details, Package Options, Site Configuration
+@section Making Your Help Strings Look Pretty
+
+Properly formatting the @samp{help strings} which are used in
+@code{AC_ARG_WITH} (@pxref{External Software}) and @code{AC_ARG_ENABLE}
+(@pxref{Package Options}) can be challenging.  Specifically, you want
+your own @samp{help strings} to line up in the appropriate columns of
+@samp{configure --help} just like the standard Autoconf @samp{help
+strings} do.  This is the purpose of the @code{AC_HELP_STRING} macro.
+
+@defmac AC_HELP_STRING (@var{left-hand-side}, @var{right-hand-side})
+@maindex HELP_STRING
+
+Expands into an help string that looks pretty when the user executes
+@samp{configure --help}.  It is typically used in @code{AC_ARG_WITH}
+(@pxref{External Software}) or @code{AC_ARG_ENABLE} (@pxref{Package
+Options}).  The following example will make this clearer.
+
+@example
+AC_DEFUN(TEST_MACRO,
+[AC_ARG_WITH(foo,
+             AC_HELP_STRING([--with-foo],
+                            [use foo (default is NO)]),
+             ac_cv_use_foo=$withval, ac_cv_use_foo=no),
+AC_CACHE_CHECK(whether to use foo,
+               ac_cv_use_foo, ac_cv_use_foo=no)])
+@end example
+
+Please note that the call to @code{AC_HELP_STRING} is @strong{unquoted}.
+Then the last few lines of @samp{configure --help} will appear like
+this:
+
+@example
+--enable and --with options recognized:
+  --with-foo              use foo (default is NO)
+@end example
+
+The @code{AC_HELP_STRING} macro is particularly helpful when the
+@var{left-hand-side} and/or @var{right-hand-side} are composed of macro
+arguments, as shown in the following example.
+
+@example
+AC_DEFUN(MY_ARG_WITH,
+[AC_ARG_WITH([$1],
+             AC_HELP_STRING([--with-$1], [use $1 (default is $2)]),
+             ac_cv_use_$1=$withval, ac_cv_use_$1=no),
+AC_CACHE_CHECK(whether to use $1, ac_cv_use_$1, ac_cv_use_$1=$2)])
+@end example
+@end defmac
+
+
+@node Site Details, Transforming Names, Pretty Help Strings, Site Configuration
+@section Configuring Site Details
+
+Some software packages require complex site-specific information.  Some
+examples are host names to use for certain services, company names, and
+email addresses to contact.  Since some configuration scripts generated
+by Metaconfig ask for such information interactively, people sometimes
+wonder how to get that information in Autoconf-generated configuration
+scripts, which aren't interactive.
+
+Such site configuration information should be put in a file that is
+edited @emph{only by users}, not by programs.  The location of the file
+can either be based on the @code{prefix} variable, or be a standard
+location such as the user's home directory.  It could even be specified
+by an environment variable.  The programs should examine that file at
+run time, rather than at compile time.  Run time configuration is more
+convenient for users and makes the configuration process simpler than
+getting the information while configuring.  @xref{Directory Variables,,
+Variables for Installation Directories, standards, GNU Coding
+Standards}, for more information on where to put data files.
+
+@node Transforming Names, Site Defaults, Site Details, Site Configuration
+@section Transforming Program Names When Installing
+
+Autoconf supports changing the names of programs when installing them.
+In order to use these transformations, @file{configure.ac} must call the
+macro @code{AC_ARG_PROGRAM}.
+
+@defmac AC_ARG_PROGRAM
+@maindex ARG_PROGRAM
+@ovindex program_transform_name
+Place in output variable @code{program_transform_name} a sequence of
+@code{sed} commands for changing the names of installed programs.
+
+If any of the options described below are given to @code{configure},
+program names are transformed accordingly.  Otherwise, if
+@code{AC_CANONICAL_TARGET} has been called and a @option{--target} value
+is given that differs from the host type (specified with @option{--host}),
+the target type followed by a dash is used as a prefix.  Otherwise, no
+program name transformation is done.
+@end defmac
+
+@menu
+* Transformation Options::      @code{configure} options to transform names
+* Transformation Examples::     Sample uses of transforming names
+* Transformation Rules::        @file{Makefile} uses of transforming names
+@end menu
+
+@node Transformation Options, Transformation Examples, Transforming Names, Transforming Names
+@subsection Transformation Options
+
+You can specify name transformations by giving @code{configure} these
+command line options:
+
+@table @option
+@item --program-prefix=@var{prefix}
+prepend @var{prefix} to the names;
+
+@item --program-suffix=@var{suffix}
+append @var{suffix} to the names;
+
+@item --program-transform-name=@var{expression}
+perform @code{sed} substitution @var{expression} on the names.
+@end table
+
+@node Transformation Examples, Transformation Rules, Transformation Options, Transforming Names
+@subsection Transformation Examples
+
+These transformations are useful with programs that can be part of a
+cross-compilation development environment.  For example, a
+cross-assembler running on a Sun 4 configured with
+@option{--target=i960-vxworks} is normally installed as
+@file{i960-vxworks-as}, rather than @file{as}, which could be confused
+with a native Sun 4 assembler.
+
+You can force a program name to begin with @file{g}, if you don't want
+@sc{gnu} programs installed on your system to shadow other programs with
+the same name.  For example, if you configure @sc{gnu} @code{diff} with
+@option{--program-prefix=g}, then when you run @samp{make install} it is
+installed as @file{/usr/local/bin/gdiff}.
+
+As a more sophisticated example, you could use
+
+@example
+--program-transform-name='s/^/g/; s/^gg/g/; s/^gless/less/'
+@end example
+@noindent
+
+to prepend @samp{g} to most of the program names in a source tree,
+excepting those like @code{gdb} that already have one and those like
+@code{less} and @code{lesskey} that aren't @sc{gnu} programs.  (That is
+assuming that you have a source tree containing those programs that is
+set up to use this feature.)
+
+One way to install multiple versions of some programs simultaneously is
+to append a version number to the name of one or both.  For example, if
+you want to keep Autoconf version 1 around for awhile, you can configure
+Autoconf version 2 using @option{--program-suffix=2} to install the
+programs as @file{/usr/local/bin/autoconf2},
+@file{/usr/local/bin/autoheader2}, etc.  Nevertheless, pay attention
+that only the binaries are renamed, therefore you'd have problems with
+the library files which might overlap.
+
+@node Transformation Rules,  , Transformation Examples, Transforming Names
+@subsection Transformation Rules
+
+Here is how to use the variable @code{program_transform_name} in a
+@file{Makefile.in}:
+
+@example
+transform = @@program_transform_name@@
+install: all
+        $(INSTALL_PROGRAM) myprog $(bindir)/`echo myprog | \
+                                               sed '$(transform)'`
+
+uninstall:
+        rm -f $(bindir)/`echo myprog | sed '$(transform)'`
+@end example
+
+@noindent
+If you have more than one program to install, you can do it in a loop:
+
+@example
+PROGRAMS = cp ls rm
+install:
+        for p in $(PROGRAMS); do \
+          $(INSTALL_PROGRAM) $$p $(bindir)/`echo $$p | \
+                                              sed '$(transform)'`; \
+        done
+
+uninstall:
+        for p in $(PROGRAMS); do \
+          rm -f $(bindir)/`echo $$p | sed '$(transform)'`; \
+        done
+@end example
+
+It is guaranteed that @code{program_transform_name} is never empty, and
+that there are no useless separators.  Therefore you may safely embed
+@code{program_transform_name} within a sed program using @samp{;}:
+
+@example
+transform = @@program_transform_name@@
+transform_exe = s/$(EXEEXT)$$//;$(transform);s/$$/$(EXEEXT)/
+@end example
+
+Whether to do the transformations on documentation files (Texinfo or
+@code{man}) is a tricky question; there seems to be no perfect answer,
+due to the several reasons for name transforming.  Documentation is not
+usually particular to a specific architecture, and Texinfo files do not
+conflict with system documentation.  But they might conflict with
+earlier versions of the same files, and @code{man} pages sometimes do
+conflict with system documentation.  As a compromise, it is probably
+best to do name transformations on @code{man} pages but not on Texinfo
+manuals.
+
+@node Site Defaults,  , Transforming Names, Site Configuration
+@section Setting Site Defaults
+
+Autoconf-generated @code{configure} scripts allow your site to provide
+default values for some configuration values.  You do this by creating
+site- and system-wide initialization files.
+
+@evindex CONFIG_SITE
+If the environment variable @code{CONFIG_SITE} is set, @code{configure}
+uses its value as the name of a shell script to read.  Otherwise, it
+reads the shell script @file{@var{prefix}/share/config.site} if it exists,
+then @file{@var{prefix}/etc/config.site} if it exists.  Thus,
+settings in machine-specific files override those in machine-independent
+ones in case of conflict.
+
+Site files can be arbitrary shell scripts, but only certain kinds of
+code are really appropriate to be in them.  Because @code{configure}
+reads any cache file after it has read any site files, a site file can
+define a default cache file to be shared between all Autoconf-generated
+@code{configure} scripts run on that system (@pxref{Cache Files}).  If
+you set a default cache file in a site file, it is a good idea to also
+set the output variable @code{CC} in that site file, because the cache
+file is only valid for a particular compiler, but many systems have
+several available.
+
+You can examine or override the value set by a command line option to
+@code{configure} in a site file; options set shell variables that have
+the same names as the options, with any dashes turned into underscores.
+The exceptions are that @option{--without-} and @option{--disable-} options
+are like giving the corresponding @option{--with-} or @option{--enable-}
+option and the value @samp{no}.  Thus, @option{--cache-file=localcache}
+sets the variable @code{cache_file} to the value @samp{localcache};
+@option{--enable-warnings=no} or @option{--disable-warnings} sets the variable
+@code{enable_warnings} to the value @samp{no}; @option{--prefix=/usr} sets the
+variable @code{prefix} to the value @samp{/usr}; etc.
+
+Site files are also good places to set default values for other output
+variables, such as @code{CFLAGS}, if you need to give them non-default
+values: anything you would normally do, repetitively, on the command
+line.  If you use non-default values for @var{prefix} or
+@var{exec_prefix} (wherever you locate the site file), you can set them
+in the site file if you specify it with the @code{CONFIG_SITE}
+environment variable.
+
+You can set some cache values in the site file itself.  Doing this is
+useful if you are cross-compiling, so it is impossible to check features
+that require running a test program.  You could ``prime the cache'' by
+setting those values correctly for that system in
+@file{@var{prefix}/etc/config.site}.  To find out the names of the cache
+variables you need to set, look for shell variables with @samp{_cv_} in
+their names in the affected @code{configure} scripts, or in the Autoconf
+M4 source code for those macros.
+
+The cache file is careful to not override any variables set in the site
+files.  Similarly, you should not override command-line options in the
+site files.  Your code should check that variables such as @code{prefix}
+and @code{cache_file} have their default values (as set near the top of
+@code{configure}) before changing them.
+
+Here is a sample file @file{/usr/share/local/gnu/share/config.site}.  The
+command @samp{configure --prefix=/usr/share/local/gnu} would read this
+file (if @code{CONFIG_SITE} is not set to a different file).
+
+@example
+# config.site for configure
+#
+# Change some defaults.
+test "$prefix" = NONE && prefix=/usr/share/local/gnu
+test "$exec_prefix" = NONE && exec_prefix=/usr/local/gnu
+test "$sharedstatedir" = '$prefix/com' && sharedstatedir=/var
+test "$localstatedir" = '$prefix/var' && localstatedir=/var
+
+# Give Autoconf 2.x generated configure scripts a shared default
+# cache file for feature test results, architecture-specific.
+if test "$cache_file" = /dev/null; then
+  cache_file="$prefix/var/config.cache"
+  # A cache file is only valid for one C compiler.
+  CC=gcc
+fi
+@end example
+
+
+@c ============================================== Running configure Scripts.
+
+@node Running configure scripts, config.status Invocation, Site Configuration, Top
+@chapter Running @code{configure} Scripts
+@cindex @code{configure}
+
+Below are instructions on how to configure a package that uses a
+@code{configure} script, suitable for inclusion as an @file{INSTALL}
+file in the package.  A plain-text version of @file{INSTALL} which you
+may use comes with Autoconf.
+
+@menu
+* Basic Installation::          Instructions for typical cases
+* Compilers and Options::       Selecting compilers and optimization
+* Multiple Architectures::      Compiling for multiple architectures at once
+* Installation Names::          Installing in different directories
+* Optional Features::           Selecting optional features
+* System Type::                 Specifying the system type
+* Sharing Defaults::            Setting site-wide defaults for @code{configure}
+* Environment Variables::       Defining environment variables.
+* configure Invocation::        Changing how @code{configure} runs
+@end menu
+
+@include install.texi
+
+
+@c ============================================== Recreating a Configuration
+
+@node config.status Invocation, Obsolete Constructs, Running configure scripts, Top
+@chapter Recreating a Configuration
+@cindex @code{config.status}
+
+The @code{configure} script creates a file named @file{config.status},
+which actually configures, @dfn{instantiates}, the template files.  It
+also records the configuration options that were specified when the
+package was last configured in case reconfiguring is needed.
+
+Synopsis:
+@example
+./config.status @var{option}@dots{} [@var{file}@dots{}]
+@end example
+
+It configures the @var{files}, if none are specified, all the templates
+are instantiated.  The files must be specified without their
+dependencies, as in
+
+@example
+./config.status foobar
+@end example
+
+@noindent
+not
+
+@example
+./config.status foobar:foo.in:bar.in
+@end example
+
+The supported @var{option}s are:
+
+@table @option
+@item --help
+@itemx -h
+Print a summary of the command line options, the list of the template
+files and exit.
+
+@item --version
+@itemx -V
+Print the version number of Autoconf and exit.
+
+@item --debug
+@itemx -d
+Don't remove the temporary files.
+
+@item --file=@var{file}[:@var{template}]
+Require that @var{file} be instantiated as if
+@samp{AC_CONFIG_FILES(@var{file}:@var{template})} was used.  Both
+@var{file} and @var{template} may be @samp{-} in which case the standard
+output and/or standard input, respectively, is used.  If a
+@var{template} filename is relative, it is first looked for in the build
+tree, and then in the source tree. @xref{Configuration Actions}, for
+more details.
+
+This option and the following ones provide one way for separately
+distributed packages to share the values computed by @code{configure}.
+Doing so can be useful if some of the packages need a superset of the
+features that one of them, perhaps a common library, does.  These
+options allow a @file{config.status} file to create files other than the
+ones that its @file{configure.ac} specifies, so it can be used for a
+different package.
+
+@item --header=@var{file}[:@var{template}]
+Same as @option{--file} above, but with @samp{AC_CONFIG_HEADERS}.
+
+@item --recheck
+Ask @file{config.status} to update itself and exit (no instantiation).
+This option is useful if you change @code{configure}, so that the
+results of some tests might be different from the previous run.  The
+@option{--recheck} option re-runs @code{configure} with the same arguments
+you used before, plus the @option{--no-create} option, which prevents
+@code{configure} from running @file{config.status} and creating
+@file{Makefile} and other files, and the @option{--no-recursion} option,
+which prevents @code{configure} from running other @code{configure}
+scripts in subdirectories.  (This is so other @file{Makefile} rules can
+run @file{config.status} when it changes; @pxref{Automatic Remaking},
+for an example).
+@end table
+
+@file{config.status} checks several optional environment variables that
+can alter its behavior:
+
+@defvar CONFIG_SHELL
+@evindex CONFIG_SHELL
+The shell with which to run @code{configure} for the @option{--recheck}
+option.  It must be Bourne-compatible.  The default is @file{/bin/sh}.
+@end defvar
+
+@defvar CONFIG_STATUS
+@evindex CONFIG_STATUS
+The file name to use for the shell script that records the
+configuration.  The default is @file{./config.status}.  This variable is
+useful when one package uses parts of another and the @code{configure}
+scripts shouldn't be merged because they are maintained separately.
+@end defvar
+
+You can use @file{./config.status} in your Makefiles.  For example, in
+the dependencies given above (@pxref{Automatic Remaking}),
+@file{config.status} is run twice when @file{configure.ac} has changed.
+If that bothers you, you can make each run only regenerate the files for
+that rule:
+@example
+@group
+config.h: stamp-h
+stamp-h: config.h.in config.status
+        ./config.status config.h
+        echo > stamp-h
+
+Makefile: Makefile.in config.status
+        ./config.status Makefile
+@end group
+@end example
+
+The calling convention of @file{config.status} has changed, see
+@ref{Obsolete config.status Use}, for details.
+
+
+@c =================================================== Obsolete Constructs
+
+@node Obsolete Constructs, Questions, config.status Invocation, Top
+@chapter Obsolete Constructs
+
+Autoconf changes, and throughout the years some constructs are obsoleted.
+Most of the changes involve the macros, but the tools themselves, or
+even some concepts, are now considered obsolete.
+
+You may completely skip this chapter if you are new to Autoconf, its
+intention is mainly to help maintainers updating their packages by
+understanding how to move to more modern constructs.
+
+@menu
+* Obsolete config.status Use::  Different calling convention
+* acconfig.h::                  Additional entries in @file{config.h.in}
+* autoupdate Invocation::       Automatic update of @file{configure.ac}
+* Obsolete Macros::             Backward compatibility macros
+* Autoconf 1::                  Tips for upgrading your files
+* Autoconf 2.13::               Some fresher tips
+@end menu
+
+@node Obsolete config.status Use, acconfig.h, Obsolete Constructs, Obsolete Constructs
+@section Obsolete @file{config.status} Invocation
+
+@file{config.status} now supports arguments to specify the files to
+instantiate, see @ref{config.status Invocation}, for more details.
+Before, environment variables had to be used.
+
+@defvar CONFIG_COMMANDS
+@evindex CONFIG_COMMANDS
+The tags of the commands to execute.  The default is the arguments given
+to @code{AC_OUTPUT} and @code{AC_CONFIG_COMMANDS} in
+@file{configure.ac}.
+@end defvar
+
+@defvar CONFIG_FILES
+@evindex CONFIG_FILES
+The files in which to perform @samp{@@@var{variable}@@} substitutions.
+The default is the arguments given to @code{AC_OUTPUT} and
+@code{AC_CONFIG_FILES} in @file{configure.ac}.
+@end defvar
+
+@defvar CONFIG_HEADERS
+@evindex CONFIG_HEADERS
+The files in which to substitute C @code{#define} statements.  The
+default is the arguments given to @code{AC_CONFIG_HEADERS}; if that
+macro was not called, @file{config.status} ignores this variable.
+@end defvar
+
+@defvar CONFIG_LINKS
+@evindex CONFIG_LINKS
+The symbolic links to establish.  The default is the arguments given to
+@code{AC_CONFIG_LINKS}; if that macro was not called,
+@file{config.status} ignores this variable.
+@end defvar
+
+In @ref{config.status Invocation}, using this old interface, the example
+would be:
+
+@example
+@group
+config.h: stamp-h
+stamp-h: config.h.in config.status
+        CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_FILES= \
+          CONFIG_HEADERS=config.h ./config.status
+        echo > stamp-h
+
+Makefile: Makefile.in config.status
+        CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_HEADERS= \
+          CONFIG_FILES=Makefile ./config.status
+@end group
+@end example
+
+@noindent
+(If @file{configure.ac} does not call @code{AC_CONFIG_HEADERS}, there is
+no need to set @code{CONFIG_HEADERS} in the @code{make} rules, equally
+for @code{CONFIG_COMMANDS} etc.)
+
+
+@node acconfig.h, autoupdate Invocation, Obsolete config.status Use, Obsolete Constructs
+@section @file{acconfig.h}
+
+@cindex @file{acconfig.h}
+@cindex @file{config.h.top}
+@cindex @file{config.h.bot}
+
+In order to produce @file{config.h.in}, @command{autoheader} needs to
+build or to find templates for each symbol.  Modern releases of Autoconf
+use @code{AH_VERBATIM} and @code{AH_TEMPLATE} (@pxref{Autoheader
+Macros}), but in older releases a file, @file{acconfig.h}, contained the
+list of needed templates.  @code{autoheader} copies comments and
+@code{#define} and @code{#undef} statements from @file{acconfig.h} in
+the current directory, if present.  This file used to be mandatory if
+you @code{AC_DEFINE} any additional symbols.
+
+Modern releases of Autoconf also provide @code{AH_TOP} and
+@code{AH_BOTTOM} if you need to prepend/append some information to
+@file{config.h.in}.  Ancient versions of Autoconf had a similar feature:
+if @file{./acconfig.h} contains the string @samp{@@TOP@@},
+@code{autoheader} copies the lines before the line containing
+@samp{@@TOP@@} into the top of the file that it generates.  Similarly,
+if @file{./acconfig.h} contains the string @samp{@@BOTTOM@@},
+@code{autoheader} copies the lines after that line to the end of the
+file it generates.  Either or both of those strings may be omitted.  An
+even older alternate way to produce the same effect in jurasik versions
+of Autoconf is to create the files @file{@var{file}.top} (typically
+@file{config.h.top}) and/or @file{@var{file}.bot} in the current
+directory.  If they exist, @code{autoheader} copies them to the
+beginning and end, respectively, of its output.
+
+In former versions of Autoconf, the files used in preparing a software
+package for distribution were:
+@example
+@group
+configure.ac --.   .------> autoconf* -----> configure
+               +---+
+[aclocal.m4] --+   `---.
+[acsite.m4] ---'       |
+                       +--> [autoheader*] -> [config.h.in]
+[acconfig.h] ----.     |
+                 +-----'
+[config.h.top] --+
+[config.h.bot] --'
+@end group
+@end example
+
+Use only the @code{AH_} macros, @file{configure.ac} should be
+self-contained, and should not depend upon @file{acconfig.h} etc.
+
+
+@node autoupdate Invocation, Obsolete Macros, acconfig.h, Obsolete Constructs
+@section Using @code{autoupdate} to Modernize @file{configure.ac}
+@cindex @code{autoupdate}
+
+The @code{autoupdate} program updates a @file{configure.ac} file that
+calls Autoconf macros by their old names to use the current macro names.
+In version 2 of Autoconf, most of the macros were renamed to use a more
+uniform and descriptive naming scheme.  @xref{Macro Names}, for a
+description of the new scheme.  Although the old names still work
+(@pxref{Obsolete Macros}, for a list of the old macros and the corresponding
+new names), you can make your @file{configure.ac} files more readable
+and make it easier to use the current Autoconf documentation if you
+update them to use the new macro names.
+
+@evindex SIMPLE_BACKUP_SUFFIX
+If given no arguments, @code{autoupdate} updates @file{configure.ac},
+backing up the original version with the suffix @file{~} (or the value
+of the environment variable @code{SIMPLE_BACKUP_SUFFIX}, if that is
+set).  If you give @code{autoupdate} an argument, it reads that file
+instead of @file{configure.ac} and writes the updated file to the
+standard output.
+
+@noindent
+@code{autoupdate} accepts the following options:
+
+@table @option
+@item --help
+@itemx -h
+Print a summary of the command line options and exit.
+
+@item --version
+@itemx -V
+Print the version number of Autoconf and exit.
+
+@item --verbose
+@itemx -v
+Report processing steps.
+
+@item --debug
+@itemx -d
+Don't remove the temporary files.
+
+@item --autoconf-dir=@var{dir}
+@itemx -A @var{dir}
+@evindex AC_MACRODIR
+Override the location where the installed Autoconf data files are looked
+for.  You can also set the @code{AC_MACRODIR} environment variable to a
+directory; this option overrides the environment variable.
+
+This option is rarely needed and dangerous; it is only used when one
+plays with different versions of Autoconf simultaneously.
+
+@item --localdir=@var{dir}
+@itemx -l @var{dir}
+Look for the package file @file{aclocal.m4} in directory @var{dir}
+instead of in the current directory.
+@end table
+
+@node Obsolete Macros, Autoconf 1, autoupdate Invocation, Obsolete Constructs
+@section Obsolete Macros
+
+Several macros are obsoleted in Autoconf, for various reasons (typically
+they failed to quote properly, couldn't be extended for more recent
+issues etc.).  They are still supported, but deprecated: their use
+should be avoided.
+
+During the jump from Autoconf version 1 to version 2, most of the
+macros were renamed to use a more uniform and descriptive naming scheme,
+but their signature did not change.  @xref{Macro Names}, for a
+description of the new naming scheme.  Below, there is just the mapping
+from old names to new names for these macros, the reader is invited to
+refer to the definition of the new macro for the signature and the
+description.
+
+@defmac AC_ALLOCA
+@maindex ALLOCA
+@code{AC_FUNC_ALLOCA}
+@end defmac
+
+@defmac AC_ARG_ARRAY
+@maindex ARG_ARRAY
+removed because of limited usefulness
+@end defmac
+
+@defmac AC_C_CROSS
+@maindex C_CROSS
+This macro is obsolete; it does nothing.
+@end defmac
+
+@defmac AC_CANONICAL_SYSTEM
+@maindex CANONICAL_SYSTEM
+Determine the system type and set output variables to the names of the
+canonical system types.  @xref{Canonicalizing}, for details about the
+variables this macro sets.
+
+The user is encouraged to use either @code{AC_CANONICAL_BUILD}, or
+@code{AC_CANONICAL_HOST}, or @code{AC_CANONICAL_TARGET}, depending on
+the needs.  Using @code{AC_CANONICAL_TARGET} is enough to run the two
+other macros.
+@end defmac
+
+@defmac AC_CHAR_UNSIGNED
+@maindex CHAR_UNSIGNED
+@code{AC_C_CHAR_UNSIGNED}
+@end defmac
+
+@defmac AC_CHECK_TYPE (@var{type}, @var{default})
+@maindex CHECK_TYPE
+Autoconf, up to 2.13, used to provide this version of
+@code{AC_CHECK_TYPE}, deprecated because of its flaws.  Firstly, although
+it is a member of the @code{CHECK} clan, singular sub-family, it does
+more than just checking.  Second, missing types are not
+@code{typedef}'d, they are @code{#define}'d, which can lead to
+incompatible code in the case of pointer types.
+
+This use of @code{AC_CHECK_TYPE} is obsolete and discouraged, see
+@ref{Generic Types}, for the description of the current macro.
+
+If the type @var{type} is not defined, define it to be the C (or C++)
+builtin type @var{default}; e.g., @samp{short} or @samp{unsigned}.
+
+This macro is equivalent to:
+
+@example
+AC_CHECK_TYPE([@var{type}],
+              [AC_DEFINE([@var{type}], [@var{default}],
+                         [Define to `@var{default}' if <sys/types.h>
+                          does not define.])])
+@end example
+
+In order to keep backward compatibility, the two versions of
+@code{AC_CHECK_TYPE} are implemented, selected by a simple heuristics:
+
+@enumerate
+@item
+If there are three or four arguments, the modern version is used.
+
+@item
+If the second argument appears to be a C or C++ type, then the
+obsolete version is used.  This happens if the argument is a C or C++
+@emph{builtin} type or a C identifier ending in @samp{_t}, optionally
+followed by one of @samp{[(* } and then by a string of zero or more
+characters taken from the set @samp{[]()* _a-zA-Z0-9}.
+
+@item
+If the second argument is spelled with the alphabet of valid C and C++
+types, the user is warned and the modern version is used.
+
+@item
+Otherwise, the modern version is used.
+@end enumerate
+
+@noindent
+You are encouraged either to use a valid builtin type, or to use the
+equivalent modern code (see above), or better yet, to use
+@code{AC_CHECK_TYPES} together with
+
+@example
+#if !HAVE_LOFF_T
+typedef loff_t off_t;
+#endif
+@end example
+@end defmac
+@c end of AC_CHECK_TYPE
+
+@defmac AC_CHECKING (@var{feature-description})
+@maindex CHECKING
+Same as @samp{AC_MSG_NOTICE([checking @var{feature-description}@dots{}]}.
+@end defmac
+
+@defmac AC_COMPILE_CHECK (@var{echo-text}, @var{includes}, @var{function-body}, @var{action-if-found}, @ovar{action-if-not-found})
+@maindex COMPILE_CHECK
+This is an obsolete version of @code{AC_TRY_LINK} (@pxref{Examining
+Libraries}), with the addition that it prints @samp{checking for
+@var{echo-text}} to the standard output first, if @var{echo-text} is
+non-empty.  Use @code{AC_MSG_CHECKING} and @code{AC_MSG_RESULT} instead
+to print messages (@pxref{Printing Messages}).
+@end defmac
+
+@defmac AC_CONST
+@maindex CONST
+@code{AC_C_CONST}
+@end defmac
+
+@defmac AC_CROSS_CHECK
+@maindex CROSS_CHECK
+Same as @code{AC_C_CROSS}, which is obsolete too, and does nothing
+@code{:-)}.
+@end defmac
+
+@defmac AC_CYGWIN
+@maindex CYGWIN
+Check for the Cygwin environment in which case the shell variable
+@code{CYGWIN} is set to @samp{yes}.  Don't use this macro, the dignified
+means to check the nature of the host is using
+@code{AC_CANONICAL_HOST}.  As a matter of fact this macro is defined as:
+
+@example
+AC_REQUIRE([AC_CANONICAL_HOST])[]dnl
+case $host_os in
+  *cygwin* ) CYGWIN=yes;;
+         * ) CYGWIN=no;;
+esac
+@end example
+
+Beware that the variable @code{CYGWIN} has a very special meaning when
+running CygWin32, and should not be changed.  That's yet another reason
+not to use this macro.
+@end defmac
+
+@defmac AC_DECL_YYTEXT
+@maindex DECL_YYTEXT
+Does nothing, now integrated in @code{AC_PROG_LEX}.
+@end defmac
+
+@defmac AC_DIR_HEADER
+@maindex DIR_HEADER
+@cvindex DIRENT
+@cvindex SYSNDIR
+@cvindex SYSDIR
+@cvindex NDIR
+Like calling @code{AC_FUNC_CLOSEDIR_VOID} and@code{AC_HEADER_DIRENT},
+but defines a different set of C preprocessor macros to indicate which
+header file is found:
+
+@multitable {@file{sys/ndir.h}} {Old Symbol} {@code{HAVE_SYS_NDIR_H}}
+@item Header            @tab Old Symbol     @tab New Symbol
+@item @file{dirent.h}   @tab @code{DIRENT}  @tab @code{HAVE_DIRENT_H}
+@item @file{sys/ndir.h} @tab @code{SYSNDIR} @tab @code{HAVE_SYS_NDIR_H}
+@item @file{sys/dir.h}  @tab @code{SYSDIR}  @tab @code{HAVE_SYS_DIR_H}
+@item @file{ndir.h}     @tab @code{NDIR}    @tab @code{HAVE_NDIR_H}
+@end multitable
+@end defmac
+
+@defmac AC_DYNIX_SEQ
+@maindex DYNIX_SEQ
+If on Dynix/PTX (Sequent @sc{unix}), add @option{-lseq} to output variable
+@code{LIBS}.  This macro used to be defined as
+
+@example
+AC_CHECK_LIB(seq, getmntent, LIBS="-lseq $LIBS")
+@end example
+
+@noindent
+now it is just @code{AC_FUNC_GETMNTENT}.
+@end defmac
+
+@defmac AC_EXEEXT
+@maindex EXEEXT
+@ovindex EXEEXT
+Defined the output variable @code{EXEEXT} based on the output of the
+compiler, which is now done automatically.  Typically set to empty
+string if Unix and @samp{.exe} if Win32 or OS/2.
+@end defmac
+
+@defmac AC_EMXOS2
+@maindex EMXOS2
+Similar to @code{AC_CYGWIN} but checks for the EMX environment on OS/2
+and sets @code{EMXOS2}.
+@end defmac
+
+@defmac AC_ERROR
+@maindex ERROR
+@code{AC_MSG_ERROR}
+@end defmac
+
+@defmac AC_FIND_X
+@maindex FIND_X
+@code{AC_PATH_X}
+@end defmac
+
+@defmac AC_FIND_XTRA
+@maindex FIND_XTRA
+@code{AC_PATH_XTRA}
+@end defmac
+
+@defmac AC_FUNC_CHECK
+@maindex FUNC_CHECK
+@code{AC_CHECK_FUNC}
+@end defmac
+
+@defmac AC_FUNC_WAIT3
+@maindex FUNC_WAIT3
+@cvindex HAVE_WAIT3
+If @code{wait3} is found and fills in the contents of its third argument
+(a @samp{struct rusage *}), which HP-UX does not do, define
+@code{HAVE_WAIT3}.
+
+These days portable programs should use @code{waitpid}, not
+@code{wait3}, as @code{wait3} is being removed from the Open Group
+standards, and will not appear in the next revision of POSIX.
+@end defmac
+
+@defmac AC_GCC_TRADITIONAL
+@maindex GCC_TRADITIONAL
+@code{AC_PROG_GCC_TRADITIONAL}
+@end defmac
+
+@defmac AC_GETGROUPS_T
+@maindex GETGROUPS_T
+@code{AC_TYPE_GETGROUPS}
+@end defmac
+
+@defmac AC_GETLOADAVG
+@maindex GETLOADAVG
+@code{AC_FUNC_GETLOADAVG}
+@end defmac
+
+@defmac AC_HAVE_FUNCS
+@maindex HAVE_FUNCS
+@code{AC_CHECK_FUNCS}
+@end defmac
+
+@defmac AC_HAVE_HEADERS
+@maindex HAVE_HEADERS
+@code{AC_CHECK_HEADERS}
+@end defmac
+
+@defmac AC_HAVE_LIBRARY (@var{library}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})
+@maindex HAVE_LIBRARY
+This macro is equivalent to calling @code{AC_CHECK_LIB} with a
+@var{function} argument of @code{main}.  In addition, @var{library} can
+be written as any of @samp{foo}, @option{-lfoo}, or @samp{libfoo.a}.  In
+all of those cases, the compiler is passed @option{-lfoo}.  However,
+@var{library} cannot be a shell variable; it must be a literal name.
+@end defmac
+
+@defmac AC_HAVE_POUNDBANG
+@maindex HAVE_POUNDBANG
+@code{AC_SYS_INTERPRETER} (different calling convention)
+@end defmac
+
+@defmac AC_HEADER_CHECK
+@maindex HEADER_CHECK
+@code{AC_CHECK_HEADER}
+@end defmac
+
+@defmac AC_HEADER_EGREP
+@maindex HEADER_EGREP
+@code{AC_EGREP_HEADER}
+@end defmac
+
+@defmac AC_INIT (@var{unique-file-in-source-dir})
+@maindex INIT
+Formerly @code{AC_INIT} used to have a single argument, and was
+equivalent to:
+
+@example
+AC_INIT
+AC_CONFIG_SRCDIR(@var{unique-file-in-source-dir})
+@end example
+@end defmac
+
+@defmac AC_INLINE
+@maindex INLINE
+@code{AC_C_INLINE}
+@end defmac
+
+@defmac AC_INT_16_BITS
+@maindex INT_16_BITS
+@cvindex INT_16_BITS
+If the C type @code{int} is 16 bits wide, define @code{INT_16_BITS}.
+Use @samp{AC_CHECK_SIZEOF(int)} instead.
+@end defmac
+
+@defmac AC_IRIX_SUN
+@maindex IRIX_SUN
+If on IRIX (Silicon Graphics @sc{unix}), add @option{-lsun} to output
+@code{LIBS}.  If you were using it to get @code{getmntent}, use
+@code{AC_FUNC_GETMNTENT} instead.  If you used it for the NIS versions
+of the password and group functions, use @samp{AC_CHECK_LIB(sun,
+getpwnam)}.  Up to Autoconf 2.13, it used to be
+
+@example
+AC_CHECK_LIB(sun, getmntent, LIBS="-lsun $LIBS")
+@end example
+
+@noindent
+now it is defined as
+
+@example
+AC_FUNC_GETMNTENT
+AC_CHECK_LIB(sun, getpwnam)
+@end example
+@end defmac
+
+@defmac AC_LANG_C
+@maindex LANG_C
+Same as @samp{AC_LANG(C)}.
+@end defmac
+
+@defmac AC_LANG_CPLUSPLUS
+@maindex LANG_CPLUSPLUS
+Same as @samp{AC_LANG(C++)}.
+@end defmac
+
+@defmac AC_LANG_FORTRAN77
+@maindex LANG_FORTRAN77
+Same as @samp{AC_LANG(Fortran 77)}.
+@end defmac
+
+@defmac AC_LANG_RESTORE
+@maindex LANG_RESTORE
+Select the @var{language} that is saved on the top of the stack, as set
+by @code{AC_LANG_SAVE}, remove it from the stack, and call
+@code{AC_LANG(@var{language})}.
+@end defmac
+
+@defmac AC_LANG_SAVE
+@maindex LANG_SAVE
+Remember the current language (as set by @code{AC_LANG}) on a stack.
+The current language does not change.  @code{AC_LANG_PUSH} is preferred.
+@end defmac
+
+@defmac AC_LINK_FILES (@var{source}@dots{}, @var{dest}@dots{})
+@maindex LINK_FILES
+This is an obsolete version of @code{AC_CONFIG_LINKS}.  An updated
+version of:
+
+@example
+AC_LINK_FILES(config/$machine.h config/$obj_format.h,
+              host.h            object.h)
+@end example
+
+@noindent
+is:
+
+@example
+AC_CONFIG_LINKS(host.h:config/$machine.h
+                object.h:config/$obj_format.h)
+@end example
+@end defmac
+
+@defmac AC_LN_S
+@maindex LN_S
+@code{AC_PROG_LN_S}
+@end defmac
+
+@defmac AC_LONG_64_BITS
+@maindex LONG_64_BITS
+@cvindex LONG_64_BITS
+Define @code{LONG_64_BITS} if the C type @code{long int} is 64 bits wide.
+Use the generic macro @samp{AC_CHECK_SIZEOF([long int])} instead.
+@end defmac
+
+@defmac AC_LONG_DOUBLE
+@maindex LONG_DOUBLE
+@code{AC_C_LONG_DOUBLE}
+@end defmac
+
+@defmac AC_LONG_FILE_NAMES
+@maindex LONG_FILE_NAMES
+@code{AC_SYS_LONG_FILE_NAMES}
+@end defmac
+
+@defmac AC_MAJOR_HEADER
+@maindex MAJOR_HEADER
+@code{AC_HEADER_MAJOR}
+@end defmac
+
+@defmac AC_MEMORY_H
+@maindex MEMORY_H
+@cvindex NEED_MEMORY_H
+Used to define @code{NEED_MEMORY_H} if the @code{mem} functions were
+defined in @file{memory.h}.  Today it is equivalent to
+@samp{AC_CHECK_HEADERS(memory.h)}.  Adjust your code to depend upon
+@code{HAVE_MEMORY_H}, not @code{NEED_MEMORY_H}, see @xref{Standard
+Symbols}.
+@end defmac
+
+@defmac AC_MINGW32
+@maindex MINGW32
+Similar to @code{AC_CYGWIN} but checks for the MingW32 compiler
+environment and sets @code{MINGW32}.
+@end defmac
+
+@defmac AC_MINUS_C_MINUS_O
+@maindex MINUS_C_MINUS_O
+@code{AC_PROG_CC_C_O}
+@end defmac
+
+@defmac AC_MMAP
+@maindex MMAP
+@code{AC_FUNC_MMAP}
+@end defmac
+
+@defmac AC_MODE_T
+@maindex MODE_T
+@code{AC_TYPE_MODE_T}
+@end defmac
+
+@defmac AC_OBJEXT
+@maindex OBJEXT
+@ovindex OBJEXT
+Defined the output variable @code{OBJEXT} based on the output of the
+compiler, after .c files have been excluded.  Typically set to @samp{o}
+if Unix, @samp{obj} if Win32.  Now the compiler checking macros handle
+this automatically.
+@end defmac
+
+@defmac AC_OBSOLETE (@var{this-macro-name}, @ovar{suggestion})
+@maindex OBSOLETE
+Make @code{m4} print a message to the standard error output warning that
+@var{this-macro-name} is obsolete, and giving the file and line number
+where it was called.  @var{this-macro-name} should be the name of the
+macro that is calling @code{AC_OBSOLETE}.  If @var{suggestion} is given,
+it is printed at the end of the warning message; for example, it can be
+a suggestion for what to use instead of @var{this-macro-name}.
+
+For instance
+
+@example
+AC_OBSOLETE([$0], [; use AC_CHECK_HEADERS(unistd.h) instead])dnl
+@end example
+
+You are encouraged to use @code{AU_DEFUN} instead, since it gives better
+services to the user.
+@end defmac
+
+@defmac AC_OFF_T
+@maindex OFF_T
+@code{AC_TYPE_OFF_T}
+@end defmac
+
+@defmac AC_OUTPUT (@ovar{file}@dots{}, @ovar{extra-cmds}, @ovar{init-cmds}, @ovar{save-defs})
+@maindex OUTPUT
+The use of @code{AC_OUTPUT} with argument is deprecated, this obsoleted
+interface is equivalent to:
+
+@example
+@group
+AC_CONFIG_FILES(@var{file}@dots{})
+AC_CONFIG_COMMANDS([default],
+                   @var{extra-cmds}, @var{init-cmds})
+AC_SETUP_DEFS(@var{save-defs})
+AC_OUTPUT
+@end group
+@end example
+
+If you specify @var{save-defs}, autoconf will save the @samp{#define}s in a
+different form, for use in the files specified in @code{AC_CONFIG_HEADERS}.
+In this case, autoconf substitutes the C-style @samp{#define}s where it finds
+@samp{@@DEFS@@}.
+This runs faster, and is simpler to maintain
+than building a file of @samp{#undef}s,
+since autoconf will automatically generate a @samp{#define} for each
+@code{AC_DEFINE} that you execute in the @code{configure} script.
+The value for @var{save-defs} should be
+either @code{cat}, or @code{sort};
+this value is used to filter the list of @samp{#define}s before editing.
+Sorted lists are easier to read,
+but you may wish to see the definitions in the order that they were
+processed.
+@end defmac
+
+@defmac AC_OUTPUT_COMMANDS (@var{extra-cmds}, @ovar{init-cmds})
+@maindex OUTPUT_COMMANDS
+Specify additional shell commands to run at the end of
+@file{config.status}, and shell commands to initialize any variables
+from @code{configure}.  This macro may be called multiple times.  It is
+obsolete, replaced by @code{AC_CONFIG_COMMANDS}.
+
+Here is an unrealistic example:
+
+@example
+fubar=27
+AC_OUTPUT_COMMANDS([echo this is extra $fubar, and so on.],
+                   fubar=$fubar)
+AC_OUTPUT_COMMANDS([echo this is another, extra, bit],
+                   [echo init bit])
+@end example
+
+Aside from the fact that @code{AC_CONFIG_COMMANDS} requires an
+additional key, an important difference is that
+@code{AC_OUTPUT_COMMANDS} is quoting its arguments twice, while
+@code{AC_CONFIG_COMMANDS}.  This means that @code{AC_CONFIG_COMMANDS}
+can safely be given macro calls as arguments:
+
+@example
+AC_CONFIG_COMMANDS(foo, [my_FOO()])
+@end example
+
+@noindent
+conversely, where one level of quoting was enough for literal strings
+with @code{AC_OUTPUT_COMMANDS}, you need two with
+@code{AC_CONFIG_COMMANDS}.  The following lines are equivalent:
+
+@example
+@group
+AC_OUTPUT_COMMANDS([echo "Square brackets: []"])
+AC_CONFIG_COMMANDS(default, [[echo "Square brackets: []"]])
+@end group
+@end example
+@end defmac
+
+@defmac AC_PID_T
+@maindex PID_T
+@code{AC_TYPE_PID_T}
+@end defmac
+
+@defmac AC_PREFIX
+@maindex PREFIX
+@code{AC_PREFIX_PROGRAM}
+@end defmac
+
+@defmac AC_PROGRAMS_CHECK
+@maindex PROGRAMS_CHECK
+@code{AC_CHECK_PROGS}
+@end defmac
+
+@defmac AC_PROGRAMS_PATH
+@maindex PROGRAMS_PATH
+@code{AC_PATH_PROGS}
+@end defmac
+
+@defmac AC_PROGRAM_CHECK
+@maindex PROGRAM_CHECK
+@code{AC_CHECK_PROG}
+@end defmac
+
+@defmac AC_PROGRAM_EGREP
+@maindex PROGRAM_EGREP
+@code{AC_EGREP_CPP}
+@end defmac
+
+@defmac AC_PROGRAM_PATH
+@maindex PROGRAM_PATH
+@code{AC_PATH_PROG}
+@end defmac
+
+@defmac AC_REMOTE_TAPE
+@maindex REMOTE_TAPE
+removed because of limited usefulness
+@end defmac
+
+@defmac AC_RESTARTABLE_SYSCALLS
+@maindex RESTARTABLE_SYSCALLS
+@code{AC_SYS_RESTARTABLE_SYSCALLS}
+@end defmac
+
+@defmac AC_RETSIGTYPE
+@maindex RETSIGTYPE
+@code{AC_TYPE_SIGNAL}
+@end defmac
+
+@defmac AC_RSH
+@maindex RSH
+Removed because of limited usefulness.
+@end defmac
+
+@defmac AC_SCO_INTL
+@maindex SCO_INTL
+@ovindex LIBS
+If on SCO UNIX, add @option{-lintl} to output variable @code{LIBS}.  This
+macro used to
+
+@example
+AC_CHECK_LIB(intl, strftime, LIBS="-lintl $LIBS")
+@end example
+
+@noindent
+now it just calls @code{AC_FUNC_STRFTIME} instead.
+@end defmac
+
+@defmac AC_SETVBUF_REVERSED
+@maindex SETVBUF_REVERSED
+@code{AC_FUNC_SETVBUF_REVERSED}
+@end defmac
+
+@defmac AC_SET_MAKE
+@maindex SET_MAKE
+@code{AC_PROG_MAKE_SET}
+@end defmac
+
+@defmac AC_SIZEOF_TYPE
+@maindex SIZEOF_TYPE
+@code{AC_CHECK_SIZEOF}
+@end defmac
+
+@defmac AC_SIZE_T
+@maindex SIZE_T
+@code{AC_TYPE_SIZE_T}
+@end defmac
+
+@defmac AC_STAT_MACROS_BROKEN
+@maindex STAT_MACROS_BROKEN
+@code{AC_HEADER_STAT}
+@end defmac
+
+@defmac AC_STDC_HEADERS
+@maindex STDC_HEADERS
+@code{AC_HEADER_STDC}
+@end defmac
+
+@defmac AC_STRCOLL
+@maindex STRCOLL
+@code{AC_FUNC_STRCOLL}
+@end defmac
+
+@defmac AC_ST_BLKSIZE
+@maindex ST_BLKSIZE
+@code{AC_STRUCT_ST_BLKSIZE}
+@end defmac
+
+@defmac AC_ST_BLOCKS
+@maindex ST_BLOCKS
+@code{AC_STRUCT_ST_BLOCKS}
+@end defmac
+
+@defmac AC_ST_RDEV
+@maindex ST_RDEV
+@code{AC_STRUCT_ST_RDEV}
+@end defmac
+
+@defmac AC_SYS_RESTARTABLE_SYSCALLS
+@maindex SYS_RESTARTABLE_SYSCALLS
+@cvindex HAVE_RESTARTABLE_SYSCALLS
+If the system automatically restarts a system call that is interrupted
+by a signal, define @code{HAVE_RESTARTABLE_SYSCALLS}. This macro does
+not check if system calls are restarted in general--it tests whether a
+signal handler installed with @code{signal} (but not @code{sigaction})
+causes system calls to be restarted. It does not test if system calls
+can be restarted when interrupted by signals that have no handler.
+
+These days portable programs should use @code{sigaction} with
+@code{SA_RESTART} if they want restartable system calls.  They should
+not rely on @code{HAVE_RESTARTABLE_SYSCALLS}, since nowadays whether a
+system call is restartable is a dynamic issue, not a configuration-time
+issue.
+@end defmac
+
+@defmac AC_SYS_SIGLIST_DECLARED
+@maindex SYS_SIGLIST_DECLARED
+@code{AC_DECL_SYS_SIGLIST}
+@end defmac
+
+@defmac AC_TEST_CPP
+@maindex TEST_CPP
+@code{AC_TRY_CPP}
+@end defmac
+
+@defmac AC_TEST_PROGRAM
+@maindex TEST_PROGRAM
+@code{AC_TRY_RUN}
+@end defmac
+
+@defmac AC_TIMEZONE
+@maindex TIMEZONE
+@code{AC_STRUCT_TIMEZONE}
+@end defmac
+
+@defmac AC_TIME_WITH_SYS_TIME
+@maindex TIME_WITH_SYS_TIME
+@code{AC_HEADER_TIME}
+@end defmac
+
+@defmac AC_UID_T
+@maindex UID_T
+@code{AC_TYPE_UID_T}
+@end defmac
+
+@defmac AC_UNISTD_H
+@maindex UNISTD_H
+Same as @samp{AC_CHECK_HEADERS(unistd.h)}.
+@end defmac
+
+@defmac AC_USG
+@maindex USG
+@cvindex USG
+Define @code{USG} if the @sc{bsd} string functions are defined in
+@file{strings.h}.  You should no longer depend upon @code{USG}, but on
+@code{HAVE_STRING_H}, see @xref{Standard Symbols}.
+@end defmac
+
+@defmac AC_UTIME_NULL
+@maindex UTIME_NULL
+@code{AC_FUNC_UTIME_NULL}
+@end defmac
+
+@defmac AC_VALIDATE_CACHED_SYSTEM_TUPLE (@ovar{cmd})
+@maindex VALIDATE_CACHED_SYSTEM_TUPLE
+If the cache file is inconsistent with the current host, target and
+build system types, it used to execute @var{cmd} or print a default
+error message.
+
+This is now handled by default.
+@end defmac
+
+@defmac AC_VERBOSE (@var{result-description})
+@maindex VERBOSE
+@code{AC_MSG_RESULT}.
+@end defmac
+
+@defmac AC_VFORK
+@maindex VFORK
+@code{AC_FUNC_VFORK}
+@end defmac
+
+@defmac AC_VPRINTF
+@maindex VPRINTF
+@code{AC_FUNC_VPRINTF}
+@end defmac
+
+@defmac AC_WAIT3
+@maindex WAIT3
+@code{AC_FUNC_WAIT3}
+@end defmac
+
+@defmac AC_WARN
+@maindex WARN
+@code{AC_MSG_WARN}
+@end defmac
+
+@defmac AC_WORDS_BIGENDIAN
+@maindex WORDS_BIGENDIAN
+@code{AC_C_BIGENDIAN}
+@end defmac
+
+@defmac AC_XENIX_DIR
+@maindex XENIX_DIR
+@ovindex LIBS
+This macro used to add @option{-lx} to output variable @code{LIBS} if on
+Xenix.  Also, if @file{dirent.h} is being checked for, added
+@option{-ldir} to @code{LIBS}.  Now it is merely an alias of
+@code{AC_HEADER_DIRENT} instead, plus some code to detect whether
+running @sc{xenix} on which you should not depend:
+
+@example
+AC_MSG_CHECKING([for Xenix])
+AC_EGREP_CPP(yes,
+[#if defined M_XENIX && !defined M_UNIX
+  yes
+#endif],
+             [AC_MSG_RESULT([yes]); XENIX=yes],
+             [AC_MSG_RESULT([no]); XENIX=])
+@end example
+@end defmac
+
+@defmac AC_YYTEXT_POINTER
+@maindex YYTEXT_POINTER
+@code{AC_DECL_YYTEXT}
+@end defmac
+
+@node Autoconf 1, Autoconf 2.13, Obsolete Macros, Obsolete Constructs
+@section Upgrading From Version 1
+
+Autoconf version 2 is mostly backward compatible with version 1.
+However, it introduces better ways to do some things, and doesn't
+support some of the ugly things in version 1.  So, depending on how
+sophisticated your @file{configure.ac} files are, you might have to do
+some manual work in order to upgrade to version 2.  This chapter points
+out some problems to watch for when upgrading.  Also, perhaps your
+@code{configure} scripts could benefit from some of the new features in
+version 2; the changes are summarized in the file @file{NEWS} in the
+Autoconf distribution.
+
+@menu
+* Changed File Names::          Files you might rename
+* Changed Makefiles::           New things to put in @file{Makefile.in}
+* Changed Macros::              Macro calls you might replace
+* Changed Results::             Changes in how to check test results
+* Changed Macro Writing::       Better ways to write your own macros
+@end menu
+
+@node Changed File Names, Changed Makefiles, Autoconf 1, Autoconf 1
+@subsection Changed File Names
+
+If you have an @file{aclocal.m4} installed with Autoconf (as opposed to
+in a particular package's source directory), you must rename it to
+@file{acsite.m4}.  @xref{autoconf Invocation}.
+
+If you distribute @file{install.sh} with your package, rename it to
+@file{install-sh} so @code{make} builtin rules won't inadvertently
+create a file called @file{install} from it.  @code{AC_PROG_INSTALL}
+looks for the script under both names, but it is best to use the new name.
+
+If you were using @file{config.h.top}, @file{config.h.bot}, or
+@file{acconfig.h}, you still can, but you will have less clutter if you
+use the @code{AH_} macros.  @xref{Autoheader Macros}.
+
+@node Changed Makefiles, Changed Macros, Changed File Names, Autoconf 1
+@subsection Changed Makefiles
+
+Add @samp{@@CFLAGS@@}, @samp{@@CPPFLAGS@@}, and @samp{@@LDFLAGS@@} in
+your @file{Makefile.in} files, so they can take advantage of the values
+of those variables in the environment when @code{configure} is run.
+Doing this isn't necessary, but it's a convenience for users.
+
+Also add @samp{@@configure_input@@} in a comment to each input file for
+@code{AC_OUTPUT}, so that the output files will contain a comment saying
+they were produced by @code{configure}.  Automatically selecting the
+right comment syntax for all the kinds of files that people call
+@code{AC_OUTPUT} on became too much work.
+
+Add @file{config.log} and @file{config.cache} to the list of files you
+remove in @code{distclean} targets.
+
+If you have the following in @file{Makefile.in}:
+
+@example
+prefix = /usr/local
+exec_prefix = $(prefix)
+@end example
+
+@noindent
+you must change it to:
+
+@example
+prefix = @@prefix@@
+exec_prefix = @@exec_prefix@@
+@end example
+
+@noindent
+The old behavior of replacing those variables without @samp{@@}
+characters around them has been removed.
+
+@node Changed Macros, Changed Results, Changed Makefiles, Autoconf 1
+@subsection Changed Macros
+
+Many of the macros were renamed in Autoconf version 2.  You can still
+use the old names, but the new ones are clearer, and it's easier to find
+the documentation for them.  @xref{Obsolete Macros}, for a table showing the
+new names for the old macros.  Use the @code{autoupdate} program to
+convert your @file{configure.ac} to using the new macro names.
+@xref{autoupdate Invocation}.
+
+Some macros have been superseded by similar ones that do the job better,
+but are not call-compatible.  If you get warnings about calling obsolete
+macros while running @code{autoconf}, you may safely ignore them, but
+your @code{configure} script will generally work better if you follow
+the advice it prints about what to replace the obsolete macros with.  In
+particular, the mechanism for reporting the results of tests has
+changed.  If you were using @code{echo} or @code{AC_VERBOSE} (perhaps
+via @code{AC_COMPILE_CHECK}), your @code{configure} script's output will
+look better if you switch to @code{AC_MSG_CHECKING} and
+@code{AC_MSG_RESULT}.  @xref{Printing Messages}.  Those macros work best
+in conjunction with cache variables.  @xref{Caching Results}.
+
+
+
+@node Changed Results, Changed Macro Writing, Changed Macros, Autoconf 1
+@subsection Changed Results
+
+If you were checking the results of previous tests by examining the
+shell variable @code{DEFS}, you need to switch to checking the values of
+the cache variables for those tests.  @code{DEFS} no longer exists while
+@code{configure} is running; it is only created when generating output
+files.  This difference from version 1 is because properly quoting the
+contents of that variable turned out to be too cumbersome and
+inefficient to do every time @code{AC_DEFINE} is called.  @xref{Cache
+Variable Names}.
+
+For example, here is a @file{configure.ac} fragment written for Autoconf
+version 1:
+
+@example
+AC_HAVE_FUNCS(syslog)
+case "$DEFS" in
+*-DHAVE_SYSLOG*) ;;
+*) # syslog is not in the default libraries.  See if it's in some other.
+  saved_LIBS="$LIBS"
+  for lib in bsd socket inet; do
+    AC_CHECKING(for syslog in -l$lib)
+    LIBS="$saved_LIBS -l$lib"
+    AC_HAVE_FUNCS(syslog)
+    case "$DEFS" in
+    *-DHAVE_SYSLOG*) break ;;
+    *) ;;
+    esac
+    LIBS="$saved_LIBS"
+  done ;;
+esac
+@end example
+
+Here is a way to write it for version 2:
+
+@example
+AC_CHECK_FUNCS(syslog)
+if test $ac_cv_func_syslog = no; then
+  # syslog is not in the default libraries.  See if it's in some other.
+  for lib in bsd socket inet; do
+    AC_CHECK_LIB($lib, syslog, [AC_DEFINE(HAVE_SYSLOG)
+      LIBS="$LIBS -l$lib"; break])
+  done
+fi
+@end example
+
+If you were working around bugs in @code{AC_DEFINE_UNQUOTED} by adding
+backslashes before quotes, you need to remove them.  It now works
+predictably, and does not treat quotes (except back quotes) specially.
+@xref{Setting Output Variables}.
+
+All of the boolean shell variables set by Autoconf macros now use
+@samp{yes} for the true value.  Most of them use @samp{no} for false,
+though for backward compatibility some use the empty string instead.  If
+you were relying on a shell variable being set to something like 1 or
+@samp{t} for true, you need to change your tests.
+
+@node Changed Macro Writing,  , Changed Results, Autoconf 1
+@subsection Changed Macro Writing
+
+When defining your own macros, you should now use @code{AC_DEFUN}
+instead of @code{define}.  @code{AC_DEFUN} automatically calls
+@code{AC_PROVIDE} and ensures that macros called via @code{AC_REQUIRE}
+do not interrupt other macros, to prevent nested @samp{checking@dots{}}
+messages on the screen.  There's no actual harm in continuing to use the
+older way, but it's less convenient and attractive.  @xref{Macro
+Definitions}.
+
+You probably looked at the macros that came with Autoconf as a guide for
+how to do things.  It would be a good idea to take a look at the new
+versions of them, as the style is somewhat improved and they take
+advantage of some new features.
+
+If you were doing tricky things with undocumented Autoconf internals
+(macros, variables, diversions), check whether you need to change
+anything to account for changes that have been made.  Perhaps you can
+even use an officially supported technique in version 2 instead of
+kludging.  Or perhaps not.
+
+To speed up your locally written feature tests, add caching to them.
+See whether any of your tests are of general enough usefulness to
+encapsulate into macros that you can share.
+
+
+@node Autoconf 2.13,  , Autoconf 1, Obsolete Constructs
+@section Upgrading From Version 2.13
+
+The introduction of the previous section (@pxref{Autoconf 1}) perfectly
+suits this section...
+
+@quotation
+Autoconf version 2.50 is mostly backward compatible with version 2.13.
+However, it introduces better ways to do some things, and doesn't
+support some of the ugly things in version 2.13.  So, depending on how
+sophisticated your @file{configure.ac} files are, you might have to do
+some manual work in order to upgrade to version 2.50.  This chapter
+points out some problems to watch for when upgrading.  Also, perhaps
+your @code{configure} scripts could benefit from some of the new
+features in version 2.50; the changes are summarized in the file
+@file{NEWS} in the Autoconf distribution.
+@end quotation
+
+@menu
+* Changed Quotation::           Broken code which used to work
+* New Macros::                  Interaction with foreign macros
+@end menu
+
+@node Changed Quotation, New Macros, Autoconf 2.13, Autoconf 2.13
+@subsection Changed Quotation
+
+The most important changes are invisible to you: the implementation of
+most macros have completely changed.  This allowed more factorization of
+the code, better error messages, a higher uniformity of the user's
+interface etc.  Unfortunately, as a side effect, some construct which
+used to (miraculously) work might break starting with Autoconf 2.50.
+The most common culprit is bad quotation.
+
+For instance, in the following example, the message is not properly
+quoted:
+
+@example
+AC_INIT
+AC_CHECK_HEADERS(foo.h,,
+AC_MSG_ERROR(cannot find foo.h, bailing out))
+AC_OUTPUT
+@end example
+
+@noindent
+Autoconf 2.13 simply ignores it:
+
+@example
+$ autoconf-2.13; ./configure --silent
+creating cache ./config.cache
+configure: error: cannot find foo.h
+$
+@end example
+
+@noindent
+while Autoconf 2.50 will produce a broken @file{configure}:
+
+@example
+$ autoconf-2.50; ./configure --silent
+configure: error: cannot find foo.h
+./configure: exit: bad non-numeric arg `bailing'
+./configure: exit: bad non-numeric arg `bailing'
+$
+@end example
+
+The message needs to be quoted, and the @code{AC_MSG_ERROR} invocation
+too!
+
+@example
+AC_INIT
+AC_CHECK_HEADERS(foo.h,,
+                 [AC_MSG_ERROR([cannot find foo.h, bailing out])])
+AC_OUTPUT
+@end example
+
+Many many (and many more) Autoconf macros were lacking proper quotation,
+including no less than... @code{AC_DEFUN} itself!
+
+@example
+$ cat configure.in
+AC_DEFUN([AC_PROG_INSTALL],
+[# My own much better version
+])
+AC_INIT
+AC_PROG_INSTALL
+AC_OUTPUT
+$ autoconf-2.13
+autoconf: Undefined macros:
+***BUG in Autoconf--please report*** AC_FD_MSG
+***BUG in Autoconf--please report*** AC_EPI
+configure.in:1:AC_DEFUN([AC_PROG_INSTALL],
+configure.in:5:AC_PROG_INSTALL
+$ autoconf-2.50
+$
+@end example
+
+
+@node New Macros,  , Changed Quotation, Autoconf 2.13
+@subsection New Macros
+
+@cindex @code{undefined macro: _m4_divert_diversion}
+
+Because Autoconf has been dormant for years, Automake provided
+Autoconf-like macros for a while.  Autoconf 2.50 now provides better
+versions of these macros, integrated in the @code{AC_} namespace,
+instead of @code{AM_}.  But in order to ease the upgrading via
+@command{autoupdate}, bindings to such @code{AM_} macros are provided.
+
+Unfortunately Automake did not quote the name of these macros!
+Therefore, when @command{m4} find in @file{aclocal.m4} something like
+@samp{AC_DEFUN(AM_TYPE_PTRDIFF_T, ...)}, @code{AM_TYPE_PTRDIFF_T} is
+expanded, replaced with its Autoconf definition.
+
+Fortunately Autoconf catches pre-@code{AC_INIT} expansions, and will
+complain, in its own words:
+
+@example
+$ cat configure.in
+AC_INIT
+AM_TYPE_PTRDIFF_T
+$ aclocal-1.4
+$ autoconf
+./aclocal.m4:17: error: m4_defn: undefined macro: _m4_divert_diversion
+actypes.m4:289: AM_TYPE_PTRDIFF_T is expanded from...
+./aclocal.m4:17: the top level
+$
+@end example
+
+Future versions of Automake will simply no longer define most of these
+macros, and will properly quote the names of the remaining macros.
+But you don't have to wait for it to happen to do the right thing right
+now: do not depend upon macros from Automake as it is simply not its job
+to provide macros (but the one it requires by itself):
+
+@example
+$ cat configure.in
+AC_INIT
+AM_TYPE_PTRDIFF_T
+$ rm aclocal.m4
+$ autoupdate
+autoupdate: `configure.in' is updated
+$ cat configure.in
+AC_INIT
+AC_CHECK_TYPES([ptrdiff_t])
+$ aclocal-1.4
+$ autoconf
+$
+@end example
+
+@c ================================================ Questions About Autoconf.
+
+@node Questions, History, Obsolete Constructs, Top
+@chapter Questions About Autoconf
+
+Several questions about Autoconf come up occasionally.  Here some of them
+are addressed.
+
+@menu
+* Distributing::                Distributing @code{configure} scripts
+* Why GNU m4::                  Why not use the standard M4?
+* Bootstrapping::               Autoconf and GNU M4 require each other?
+* Why Not Imake::               Why GNU uses @code{configure} instead of Imake
+@end menu
+
+@node Distributing, Why GNU m4, Questions, Questions
+@section Distributing @code{configure} Scripts
+
+@display
+What are the restrictions on distributing @code{configure}
+scripts that Autoconf generates?  How does that affect my
+programs that use them?
+@end display
+
+There are no restrictions on how the configuration scripts that Autoconf
+produces may be distributed or used.  In Autoconf version 1, they were
+covered by the @sc{gnu} General Public License.  We still encourage
+software authors to distribute their work under terms like those of the
+GPL, but doing so is not required to use Autoconf.
+
+Of the other files that might be used with @code{configure},
+@file{config.h.in} is under whatever copyright you use for your
+@file{configure.ac}.  @file{config.sub} and @file{config.guess} have an
+exception to the GPL when they are used with an Autoconf-generated
+@code{configure} script, which permits you to distribute them under the
+same terms as the rest of your package.  @file{install-sh} is from the X
+Consortium and is not copyrighted.
+
+@node Why GNU m4, Bootstrapping, Distributing, Questions
+@section Why Require GNU M4?
+
+@display
+Why does Autoconf require @sc{gnu} M4?
+@end display
+
+Many M4 implementations have hard-coded limitations on the size and
+number of macros that Autoconf exceeds.  They also lack several
+builtin macros that it would be difficult to get along without in a
+sophisticated application like Autoconf, including:
+
+@example
+builtin
+indir
+patsubst
+__file__
+__line__
+@end example
+
+Autoconf requires version 1.4 or above of @sc{gnu} M4 because it uses
+frozen state files.
+
+Since only software maintainers need to use Autoconf, and since @sc{gnu}
+M4 is simple to configure and install, it seems reasonable to require
+@sc{gnu} M4 to be installed also.  Many maintainers of @sc{gnu} and
+other free software already have most of the @sc{gnu} utilities
+installed, since they prefer them.
+
+@node Bootstrapping, Why Not Imake, Why GNU m4, Questions
+@section How Can I Bootstrap?
+
+@display
+If Autoconf requires @sc{gnu} M4 and @sc{gnu} M4 has an Autoconf
+@code{configure} script, how do I bootstrap?  It seems like a chicken
+and egg problem!
+@end display
+
+This is a misunderstanding.  Although @sc{gnu} M4 does come with a
+@code{configure} script produced by Autoconf, Autoconf is not required
+in order to run the script and install @sc{gnu} M4.  Autoconf is only
+required if you want to change the M4 @code{configure} script, which few
+people have to do (mainly its maintainer).
+
+@node Why Not Imake,  , Bootstrapping, Questions
+@section Why Not Imake?
+
+@display
+Why not use Imake instead of @code{configure} scripts?
+@end display
+
+Several people have written addressing this question, so I include
+adaptations of their explanations here.
+
+The following answer is based on one written by Richard Pixley:
+
+@quotation
+Autoconf generated scripts frequently work on machines that it has
+never been set up to handle before.  That is, it does a good job of
+inferring a configuration for a new system.  Imake cannot do this.
+
+Imake uses a common database of host specific data.  For X11, this makes
+sense because the distribution is made as a collection of tools, by one
+central authority who has control over the database.
+
+@sc{gnu} tools are not released this way.  Each @sc{gnu} tool has a
+maintainer; these maintainers are scattered across the world.  Using a
+common database would be a maintenance nightmare.  Autoconf may appear
+to be this kind of database, but in fact it is not.  Instead of listing
+host dependencies, it lists program requirements.
+
+If you view the @sc{gnu} suite as a collection of native tools, then the
+problems are similar.  But the @sc{gnu} development tools can be
+configured as cross tools in almost any host+target permutation.  All of
+these configurations can be installed concurrently.  They can even be
+configured to share host independent files across hosts.  Imake doesn't
+address these issues.
+
+Imake templates are a form of standardization.  The @sc{gnu} coding
+standards address the same issues without necessarily imposing the same
+restrictions.
+@end quotation
+
+
+Here is some further explanation, written by Per Bothner:
+
+@quotation
+One of the advantages of Imake is that it easy to generate large
+Makefiles using @code{cpp}'s @samp{#include} and macro mechanisms.
+However, @code{cpp} is not programmable: it has limited conditional
+facilities, and no looping.  And @code{cpp} cannot inspect its
+environment.
+
+All of these problems are solved by using @code{sh} instead of
+@code{cpp}.  The shell is fully programmable, has macro substitution,
+can execute (or source) other shell scripts, and can inspect its
+environment.
+@end quotation
+
+
+Paul Eggert elaborates more:
+
+@quotation
+With Autoconf, installers need not assume that Imake itself is already
+installed and working well.  This may not seem like much of an advantage
+to people who are accustomed to Imake.  But on many hosts Imake is not
+installed or the default installation is not working well, and requiring
+Imake to install a package hinders the acceptance of that package on
+those hosts.  For example, the Imake template and configuration files
+might not be installed properly on a host, or the Imake build procedure
+might wrongly assume that all source files are in one big directory
+tree, or the Imake configuration might assume one compiler whereas the
+package or the installer needs to use another, or there might be a
+version mismatch between the Imake expected by the package and the Imake
+supported by the host.  These problems are much rarer with Autoconf,
+where each package comes with its own independent configuration
+processor.
+
+Also, Imake often suffers from unexpected interactions between
+@code{make} and the installer's C preprocessor.  The fundamental problem
+here is that the C preprocessor was designed to preprocess C programs,
+not @file{Makefile}s.  This is much less of a problem with Autoconf,
+which uses the general-purpose preprocessor @code{m4}, and where the
+package's author (rather than the installer) does the preprocessing in a
+standard way.
+@end quotation
+
+
+Finally, Mark Eichin notes:
+
+@quotation
+Imake isn't all that extensible, either.  In order to add new features to
+Imake, you need to provide your own project template, and duplicate most
+of the features of the existing one.  This means that for a sophisticated
+project, using the vendor-provided Imake templates fails to provide any
+leverage---since they don't cover anything that your own project needs
+(unless it is an X11 program).
+
+On the other side, though:
+
+The one advantage that Imake has over @code{configure}:
+@file{Imakefile}s tend to be much shorter (likewise, less redundant)
+than @file{Makefile.in}s.  There is a fix to this, however---at least
+for the Kerberos V5 tree, we've modified things to call in common
+@file{post.in} and @file{pre.in} @file{Makefile} fragments for the
+entire tree.  This means that a lot of common things don't have to be
+duplicated, even though they normally are in @code{configure} setups.
+@end quotation
+
+
+
+
+@c ===================================================== History of Autoconf.
+
+@node History, Environment Variable Index, Questions, Top
+@chapter History of Autoconf
+
+You may be wondering, Why was Autoconf originally written?  How did it
+get into its present form?  (Why does it look like gorilla spit?)  If
+you're not wondering, then this chapter contains no information useful
+to you, and you might as well skip it.  If you @emph{are} wondering,
+then let there be light@dots{}
+
+@menu
+* Genesis::                     Prehistory and naming of @code{configure}
+* Exodus::                      The plagues of M4 and Perl
+* Leviticus::                   The priestly code of portability arrives
+* Numbers::                     Growth and contributors
+* Deuteronomy::                 Approaching the promises of easy configuration
+@end menu
+
+@node Genesis, Exodus, History, History
+@section Genesis
+
+In June 1991 I was maintaining many of the @sc{gnu} utilities for the
+Free Software Foundation.  As they were ported to more platforms and
+more programs were added, the number of @option{-D} options that users
+had to select in the @file{Makefile} (around 20) became burdensome.
+Especially for me---I had to test each new release on a bunch of
+different systems.  So I wrote a little shell script to guess some of
+the correct settings for the fileutils package, and released it as part
+of fileutils 2.0.  That @code{configure} script worked well enough that
+the next month I adapted it (by hand) to create similar @code{configure}
+scripts for several other @sc{gnu} utilities packages.  Brian Berliner
+also adapted one of my scripts for his @sc{cvs} revision control system.
+
+Later that summer, I learned that Richard Stallman and Richard Pixley
+were developing similar scripts to use in the @sc{gnu} compiler tools;
+so I adapted my @code{configure} scripts to support their evolving
+interface: using the file name @file{Makefile.in} as the templates;
+adding @samp{+srcdir}, the first option (of many); and creating
+@file{config.status} files.
+
+@node Exodus, Leviticus, Genesis, History
+@section Exodus
+
+As I got feedback from users, I incorporated many improvements, using
+Emacs to search and replace, cut and paste, similar changes in each of
+the scripts.  As I adapted more @sc{gnu} utilities packages to use
+@code{configure} scripts, updating them all by hand became impractical.
+Rich Murphey, the maintainer of the @sc{gnu} graphics utilities, sent me
+mail saying that the @code{configure} scripts were great, and asking if
+I had a tool for generating them that I could send him.  No, I thought,
+but I should!  So I started to work out how to generate them.  And the
+journey from the slavery of hand-written @code{configure} scripts to the
+abundance and ease of Autoconf began.
+
+Cygnus @code{configure}, which was being developed at around that time,
+is table driven; it is meant to deal mainly with a discrete number of
+system types with a small number of mainly unguessable features (such as
+details of the object file format).  The automatic configuration system
+that Brian Fox had developed for Bash takes a similar approach.  For
+general use, it seems to me a hopeless cause to try to maintain an
+up-to-date database of which features each variant of each operating
+system has.  It's easier and more reliable to check for most features on
+the fly---especially on hybrid systems that people have hacked on
+locally or that have patches from vendors installed.
+
+I considered using an architecture similar to that of Cygnus
+@code{configure}, where there is a single @code{configure} script that
+reads pieces of @file{configure.in} when run.  But I didn't want to have
+to distribute all of the feature tests with every package, so I settled
+on having a different @code{configure} made from each
+@file{configure.in} by a preprocessor.  That approach also offered more
+control and flexibility.
+
+I looked briefly into using the Metaconfig package, by Larry Wall,
+Harlan Stenn, and Raphael Manfredi, but I decided not to for several
+reasons.  The @code{Configure} scripts it produces are interactive,
+which I find quite inconvenient; I didn't like the ways it checked for
+some features (such as library functions); I didn't know that it was
+still being maintained, and the @code{Configure} scripts I had
+seen didn't work on many modern systems (such as System V R4 and NeXT);
+it wasn't very flexible in what it could do in response to a feature's
+presence or absence; I found it confusing to learn; and it was too big
+and complex for my needs (I didn't realize then how much Autoconf would
+eventually have to grow).
+
+I considered using Perl to generate my style of @code{configure}
+scripts, but decided that M4 was better suited to the job of simple
+textual substitutions: it gets in the way less, because output is
+implicit.  Plus, everyone already has it.  (Initially I didn't rely on
+the @sc{gnu} extensions to M4.)  Also, some of my friends at the
+University of Maryland had recently been putting M4 front ends on
+several programs, including @code{tvtwm}, and I was interested in trying
+out a new language.
+
+@node Leviticus, Numbers, Exodus, History
+@section Leviticus
+
+Since my @code{configure} scripts determine the system's capabilities
+automatically, with no interactive user intervention, I decided to call
+the program that generates them Autoconfig.  But with a version number
+tacked on, that name would be too long for old @sc{unix} file systems,
+so I shortened it to Autoconf.
+
+In the fall of 1991 I called together a group of fellow questers after
+the Holy Grail of portability (er, that is, alpha testers) to give me
+feedback as I encapsulated pieces of my handwritten scripts in M4 macros
+and continued to add features and improve the techniques used in the
+checks.  Prominent among the testers were Fran@,cois Pinard, who came up
+with the idea of making an @file{autoconf} shell script to run @code{m4}
+and check for unresolved macro calls; Richard Pixley, who suggested
+running the compiler instead of searching the file system to find
+include files and symbols, for more accurate results; Karl Berry, who
+got Autoconf to configure @TeX{} and added the macro index to the
+documentation; and Ian Lance Taylor, who added support for creating a C
+header file as an alternative to putting @option{-D} options in a
+@file{Makefile}, so he could use Autoconf for his @sc{uucp} package.
+The alpha testers cheerfully adjusted their files again and again as the
+names and calling conventions of the Autoconf macros changed from
+release to release.  They all contributed many specific checks, great
+ideas, and bug fixes.
+
+@node Numbers, Deuteronomy, Leviticus, History
+@section Numbers
+
+In July 1992, after months of alpha testing, I released Autoconf 1.0,
+and converted many @sc{gnu} packages to use it.  I was surprised by how
+positive the reaction to it was.  More people started using it than I
+could keep track of, including people working on software that wasn't
+part of the @sc{gnu} Project (such as TCL, FSP, and Kerberos V5).
+Autoconf continued to improve rapidly, as many people using the
+@code{configure} scripts reported problems they encountered.
+
+Autoconf turned out to be a good torture test for M4 implementations.
+@sc{unix} @code{m4} started to dump core because of the length of the
+macros that Autoconf defined, and several bugs showed up in @sc{gnu}
+@code{m4} as well.  Eventually, we realized that we needed to use some
+features that only @sc{gnu} M4 has.  4.3@sc{bsd} @code{m4}, in
+particular, has an impoverished set of builtin macros; the System V
+version is better, but still doesn't provide everything we need.
+
+More development occurred as people put Autoconf under more stresses
+(and to uses I hadn't anticipated).  Karl Berry added checks for X11.
+david zuhn contributed C++ support.  Fran@,cois Pinard made it diagnose
+invalid arguments.  Jim Blandy bravely coerced it into configuring
+@sc{gnu} Emacs, laying the groundwork for several later improvements.
+Roland McGrath got it to configure the @sc{gnu} C Library, wrote the
+@code{autoheader} script to automate the creation of C header file
+templates, and added a @option{--verbose} option to @code{configure}.
+Noah Friedman added the @option{--autoconf-dir} option and
+@code{AC_MACRODIR} environment variable.  (He also coined the term
+@dfn{autoconfiscate} to mean ``adapt a software package to use
+Autoconf''.)  Roland and Noah improved the quoting protection in
+@code{AC_DEFINE} and fixed many bugs, especially when I got sick of
+dealing with portability problems from February through June, 1993.
+
+@node Deuteronomy,  , Numbers, History
+@section Deuteronomy
+
+A long wish list for major features had accumulated, and the effect of
+several years of patching by various people had left some residual
+cruft.  In April 1994, while working for Cygnus Support, I began a major
+revision of Autoconf.  I added most of the features of the Cygnus
+@code{configure} that Autoconf had lacked, largely by adapting the
+relevant parts of Cygnus @code{configure} with the help of david zuhn
+and Ken Raeburn.  These features include support for using
+@file{config.sub}, @file{config.guess}, @option{--host}, and
+@option{--target}; making links to files; and running @code{configure}
+scripts in subdirectories.  Adding these features enabled Ken to convert
+@sc{gnu} @code{as}, and Rob Savoye to convert DejaGNU, to using
+Autoconf.
+
+I added more features in response to other peoples' requests.  Many
+people had asked for @code{configure} scripts to share the results of
+the checks between runs, because (particularly when configuring a large
+source tree, like Cygnus does) they were frustratingly slow.  Mike
+Haertel suggested adding site-specific initialization scripts.  People
+distributing software that had to unpack on MS-DOS asked for a way to
+override the @file{.in} extension on the file names, which produced file
+names like @file{config.h.in} containing two dots.  Jim Avera did an
+extensive examination of the problems with quoting in @code{AC_DEFINE}
+and @code{AC_SUBST}; his insights led to significant improvements.
+Richard Stallman asked that compiler output be sent to @file{config.log}
+instead of @file{/dev/null}, to help people debug the Emacs
+@code{configure} script.
+
+I made some other changes because of my dissatisfaction with the quality
+of the program.  I made the messages showing results of the checks less
+ambiguous, always printing a result.  I regularized the names of the
+macros and cleaned up coding style inconsistencies.  I added some
+auxiliary utilities that I had developed to help convert source code
+packages to use Autoconf.  With the help of Fran@,cois Pinard, I made
+the macros not interrupt each others' messages.  (That feature revealed
+some performance bottlenecks in @sc{gnu} @code{m4}, which he hastily
+corrected!)  I reorganized the documentation around problems people want
+to solve.  And I began a test suite, because experience had shown that
+Autoconf has a pronounced tendency to regress when we change it.
+
+Again, several alpha testers gave invaluable feedback, especially
+Fran@,cois Pinard, Jim Meyering, Karl Berry, Rob Savoye, Ken Raeburn,
+and Mark Eichin.
+
+Finally, version 2.0 was ready.  And there was much rejoicing.  (And I
+have free time again.  I think.  Yeah, right.)
+
+
+@c ========================================================== Appendices
+
+@node Environment Variable Index, Output Variable Index, History, Top
+@unnumbered Environment Variable Index
+
+This is an alphabetical list of the environment variables that Autoconf
+checks.
+
+@printindex ev
+
+@node Output Variable Index, Preprocessor Symbol Index, Environment Variable Index, Top
+@unnumbered Output Variable Index
+
+This is an alphabetical list of the variables that Autoconf can
+substitute into files that it creates, typically one or more
+@file{Makefile}s.  @xref{Setting Output Variables}, for more information
+on how this is done.
+
+@printindex ov
+
+@node Preprocessor Symbol Index, Autoconf Macro Index, Output Variable Index, Top
+@unnumbered Preprocessor Symbol Index
+
+This is an alphabetical list of the C preprocessor symbols that the
+Autoconf macros define.  To work with Autoconf, C source code needs to
+use these names in @code{#if} directives.
+
+@printindex cv
+
+@node Autoconf Macro Index, M4 Macro Index, Preprocessor Symbol Index, Top
+@unnumbered Autoconf Macro Index
+
+This is an alphabetical list of the Autoconf macros.  To make the list
+easier to use, the macros are listed without their preceding @samp{AC_}.
+
+@printindex ma
+
+@node M4 Macro Index, Concept Index, Autoconf Macro Index, Top
+@unnumbered M4 Macro Index
+
+This is an alphabetical list of the M4, M4sugar, and M4sh macros.  To
+make the list easier to use, the macros are listed without their
+preceding @samp{m4_} or @samp{AS_}.
+
+@printindex ms
+
+@node Concept Index,  , M4 Macro Index, Top
+@unnumbered Concept Index
+
+This is an alphabetical list of the files, tools, and concepts
+introduced in this document.
+
+@printindex cp
+
+@contents
+@bye
+
+@c Local Variables:
+@c ispell-local-dictionary: "american"
+@c End: