/[autoconf]/autoconf/doc/autoconf.texi
ViewVC logotype

Diff of /autoconf/doc/autoconf.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.674 by eggert, Thu Sep 12 06:42:08 2002 UTC revision 1.675 by akim, Thu Sep 12 13:15:41 2002 UTC
# Line 148  Software Foundation raise funds for GNU Line 148  Software Foundation raise funds for GNU
148    
149  @menu  @menu
150  * Introduction::                Autoconf's purpose, strengths, and weaknesses  * Introduction::                Autoconf's purpose, strengths, and weaknesses
151  * The GNU build system::        A set of tools for portable software packages  * The GNU Build System::        A set of tools for portable software packages
152  * Making configure Scripts::    How to organize and produce Autoconf scripts  * Making configure Scripts::    How to organize and produce Autoconf scripts
153  * Setup::                       Initialization and output  * Setup::                       Initialization and output
154  * Existing Tests::              Macros that check for particular features  * Existing Tests::              Macros that check for particular features
# Line 159  Software Foundation raise funds for GNU Line 159  Software Foundation raise funds for GNU
159  * Portable Shell::              Shell script portability pitfalls  * Portable Shell::              Shell script portability pitfalls
160  * Manual Configuration::        Selecting features that can't be guessed  * Manual Configuration::        Selecting features that can't be guessed
161  * Site Configuration::          Local defaults for @command{configure}  * Site Configuration::          Local defaults for @command{configure}
162  * Running configure scripts::   How to use the Autoconf output  * Running configure Scripts::   How to use the Autoconf output
163  * config.status Invocation::    Recreating a configuration  * config.status Invocation::    Recreating a configuration
164  * Obsolete Constructs::         Kept for backward compatibility  * Obsolete Constructs::         Kept for backward compatibility
165  * Using Autotest::              Creating portable test suites  * Using Autotest::              Creating portable test suites
# Line 171  Software Foundation raise funds for GNU Line 171  Software Foundation raise funds for GNU
171  @detailmenu  @detailmenu
172   --- The Detailed Node Listing ---   --- The Detailed Node Listing ---
173    
174  The GNU build system  The GNU Build System
175    
176  * Automake::                    Escaping Makefile hell  * Automake::                    Escaping Makefile hell
177  * Libtool::                     Building libraries portably  * Libtool::                     Building libraries portably
# Line 202  Initialization and Output Files Line 202  Initialization and Output Files
202  * Makefile Substitutions::      Using output variables in @file{Makefile}s  * Makefile Substitutions::      Using output variables in @file{Makefile}s
203  * Configuration Headers::       Creating a configuration header file  * Configuration Headers::       Creating a configuration header file
204  * Configuration Commands::      Running arbitrary instantiation commands  * Configuration Commands::      Running arbitrary instantiation commands
205  * Configuration Links::         Links depending from the configuration  * Configuration Links::         Links depending on the configuration
206  * Subdirectories::              Configuring independent packages together  * Subdirectories::              Configuring independent packages together
207  * Default Prefix::              Changing the default installation prefix  * Default Prefix::              Changing the default installation prefix
208    
# Line 230  Existing Tests Line 230  Existing Tests
230  * Declarations::                Declarations that may be missing  * Declarations::                Declarations that may be missing
231  * Structures::                  Structures or members that might be missing  * Structures::                  Structures or members that might be missing
232  * Types::                       Types that might be missing  * Types::                       Types that might be missing
233  * Compilers and Preprocessors::  Checking for compiling programs  * Compilers and Preprocessors::  Checks for compiling programs
234  * System Services::             Operating system services  * System Services::             Operating system services
235  * UNIX Variants::               Special kludges for specific UNIX variants  * UNIX Variants::               Special kludges for specific UNIX variants
236    
# Line 289  Writing Tests Line 289  Writing Tests
289  * Multiple Cases::              Tests for several possible values  * Multiple Cases::              Tests for several possible values
290  * Language Choice::             Selecting which language to use for testing  * Language Choice::             Selecting which language to use for testing
291    
292  Checking Run Time Behavior  Checking Run-Time Behavior
293    
294  * Test Programs::               Running test programs  * Test Programs::               Running test programs
295  * Guidelines::                  General rules for writing test programs  * Guidelines::                  General rules for writing test programs
# Line 313  Programming in M4 Line 313  Programming in M4
313  * M4 Quotation::                Protecting macros from unwanted expansion  * M4 Quotation::                Protecting macros from unwanted expansion
314  * Invoking autom4te::           The Autoconf executables backbone  * Invoking autom4te::           The Autoconf executables backbone
315  * Programming in M4sugar::      Convenient pure M4 macros  * Programming in M4sugar::      Convenient pure M4 macros
316  * Programming in M4sh::         Common Shell Constructs  * Programming in M4sh::         Common shell constructs
317    
318  M4 Quotation  M4 Quotation
319    
# Line 518  packages---for a more complete solution, Line 518  packages---for a more complete solution,
518  with other GNU build tools like Automake and Libtool.  These other tools  with other GNU build tools like Automake and Libtool.  These other tools
519  take on jobs like the creation of a portable, recursive @file{Makefile}  take on jobs like the creation of a portable, recursive @file{Makefile}
520  with all of the standard targets, linking of shared libraries, and so  with all of the standard targets, linking of shared libraries, and so
521  on.  @xref{The GNU build system}, for more information.  on.  @xref{The GNU Build System}, for more information.
522    
523  Autoconf imposes some restrictions on the names of macros used with  Autoconf imposes some restrictions on the names of macros used with
524  @code{#if} in C programs (@pxref{Preprocessor Symbol Index}).  @code{#if} in C programs (@pxref{Preprocessor Symbol Index}).
# Line 562  Archive}, which is kindly run by @email{ Line 562  Archive}, which is kindly run by @email{
562  Peter Simons}.  Peter Simons}.
563    
564    
565  @c ================================================= The GNU build system  @c ================================================= The GNU Build System
566    
567  @node The GNU build system  @node The GNU Build System
568  @chapter The GNU build system  @chapter The GNU Build System
569    
570  Autoconf solves an important problem---reliable discovery of  Autoconf solves an important problem---reliable discovery of
571  system-specific build and runtime information---but this is only one  system-specific build and run-time information---but this is only one
572  piece of the puzzle for the development of portable software.  To this  piece of the puzzle for the development of portable software.  To this
573  end, the GNU project has developed a suite of integrated utilities to  end, the GNU project has developed a suite of integrated utilities to
574  finish the job Autoconf started: the GNU build system, whose most  finish the job Autoconf started: the GNU build system, whose most
# Line 638  and portability can be substantial.  And Line 638  and portability can be substantial.  And
638    
639  Very often, one wants to build not only programs, but libraries, so that  Very often, one wants to build not only programs, but libraries, so that
640  other programs can benefit from the fruits of your labor.  Ideally, one  other programs can benefit from the fruits of your labor.  Ideally, one
641  would like to produce @emph{shared} (dynamically-linked) libraries,  would like to produce @emph{shared} (dynamically linked) libraries,
642  which can be used by multiple programs without duplication on disk or in  which can be used by multiple programs without duplication on disk or in
643  memory and can be updated independently of the linked programs.  memory and can be updated independently of the linked programs.
644  Producing shared libraries portably, however, is the stuff of  Producing shared libraries portably, however, is the stuff of
# Line 651  Libtool handles all the requirements of Line 651  Libtool handles all the requirements of
651  you, and at this time seems to be the @emph{only} way to do so with any  you, and at this time seems to be the @emph{only} way to do so with any
652  portability.  It also handles many other headaches, such as: the  portability.  It also handles many other headaches, such as: the
653  interaction of @code{Makefile} rules with the variable suffixes of  interaction of @code{Makefile} rules with the variable suffixes of
654  shared libraries, linking reliably to shared libraries before they are  shared libraries, linking reliably with shared libraries before they are
655  installed by the superuser, and supplying a consistent versioning system  installed by the superuser, and supplying a consistent versioning system
656  (so that different versions of a library can be installed or upgraded  (so that different versions of a library can be installed or upgraded
657  without breaking binary compatibility).  Although Libtool, like  without breaking binary compatibility).  Although Libtool, like
# Line 720  values.  The files that @command{configu Line 720  values.  The files that @command{configu
720    
721  @itemize @minus  @itemize @minus
722  @item  @item
723  one or more @file{Makefile} files, one in each subdirectory of the  one or more @file{Makefile} files, usually one in each subdirectory of the
724  package (@pxref{Makefile Substitutions});  package (@pxref{Makefile Substitutions});
725    
726  @item  @item
# Line 811  hand-crafted shell commands; see @ref{Po Line 811  hand-crafted shell commands; see @ref{Po
811  @file{configure.ac} (@pxref{autoscan Invocation}, for more information).  @file{configure.ac} (@pxref{autoscan Invocation}, for more information).
812    
813  Previous versions of Autoconf promoted the name @file{configure.in},  Previous versions of Autoconf promoted the name @file{configure.in},
814  which is somewhat ambiguous (the tool needed to produce this file is not  which is somewhat ambiguous (the tool needed to process this file is not
815  described by its extension), and introduces a slight confusion with  described by its extension), and introduces a slight confusion with
816  @file{config.h.in} and so on (for which @samp{.in} means ``to be  @file{config.h.in} and so on (for which @samp{.in} means ``to be
817  processed by @command{configure}'').  Using @file{configure.ac} is now  processed by @command{configure}'').  Using @file{configure.ac} is now
# Line 1376  $ac_subst@{"ECHO_T"@} = "configure.ac:2" Line 1376  $ac_subst@{"ECHO_T"@} = "configure.ac:2"
1376    
1377  @noindent  @noindent
1378  A long @var{separator} can be used to improve the readability of complex  A long @var{separator} can be used to improve the readability of complex
1379  structures, and to ease its parsing (for instance when no single  structures, and to ease their parsing (for instance when no single
1380  character is suitable as a separator)):  character is suitable as a separator):
1381    
1382  @example  @example
1383  @group  @group
# Line 1401  system, or because some of the sources s Line 1401  system, or because some of the sources s
1401  been updated, or finally, simply in order to install the @sc{gnu} Build  been updated, or finally, simply in order to install the @sc{gnu} Build
1402  System in a fresh tree.  System in a fresh tree.
1403    
1404  It runs @command{autoconf}, @command{autoheader}, @command{aclocal},  @command{autoreconf} runs @command{autoconf}, @command{autoheader}, @command{aclocal},
1405  @command{automake}, @command{libtoolize}, and @command{autopoint} (when  @command{automake}, @command{libtoolize}, and @command{autopoint} (when
1406  appropriate) repeatedly to update the @sc{gnu} Build System in specified  appropriate) repeatedly to update the @sc{gnu} Build System in the specified
1407  directories, and their subdirectories (@pxref{Subdirectories}).  By  directories and their subdirectories (@pxref{Subdirectories}).  By
1408  default, it only remakes those files that are older than their sources.  default, it only remakes those files that are older than their sources.
1409    
1410  If you install a new version of some tools, you can make  If you install a new version of some tool, you can make
1411  @command{autoreconf} remake @emph{all} of the files by giving it the  @command{autoreconf} remake @emph{all} of the files by giving it the
1412  @option{--force} option.  @option{--force} option.
1413    
# Line 1468  Prepend @var{dir} to the include path. Line 1468  Prepend @var{dir} to the include path.
1468  @chapter Initialization and Output Files  @chapter Initialization and Output Files
1469    
1470  Autoconf-generated @command{configure} scripts need some information about  Autoconf-generated @command{configure} scripts need some information about
1471  how to initialize, such as how to find the package's source files; and  how to initialize, such as how to find the package's source files and
1472  about the output files to produce.  The following sections describe  about the output files to produce.  The following sections describe the
1473  initialization and the creation of output files.  initialization and the creation of output files.
1474    
1475  @menu  @menu
# Line 1482  initialization and the creation of outpu Line 1482  initialization and the creation of outpu
1482  * Makefile Substitutions::      Using output variables in @file{Makefile}s  * Makefile Substitutions::      Using output variables in @file{Makefile}s
1483  * Configuration Headers::       Creating a configuration header file  * Configuration Headers::       Creating a configuration header file
1484  * Configuration Commands::      Running arbitrary instantiation commands  * Configuration Commands::      Running arbitrary instantiation commands
1485  * Configuration Links::         Links depending from the configuration  * Configuration Links::         Links depending on the configuration
1486  * Subdirectories::              Configuring independent packages together  * Subdirectories::              Configuring independent packages together
1487  * Default Prefix::              Changing the default installation prefix  * Default Prefix::              Changing the default installation prefix
1488  @end menu  @end menu
# Line 1506  the email to which users should send bug Line 1506  the email to which users should send bug
1506  @var{tarname} differs from @var{package}: the latter designates the full  @var{tarname} differs from @var{package}: the latter designates the full
1507  package name (e.g., @samp{GNU Autoconf}), while the former is meant for  package name (e.g., @samp{GNU Autoconf}), while the former is meant for
1508  distribution tar ball names (e.g., @samp{autoconf}).  It defaults to  distribution tar ball names (e.g., @samp{autoconf}).  It defaults to
1509  @var{package} once @samp{GNU } strip, lower-cased, and all characters  @var{package} with @samp{GNU } stripped, lower-cased, and all characters
1510  other than alphanumerics and underscores are changed to @samp{-}.  other than alphanumerics and underscores are changed to @samp{-}.
1511    
1512  It is preferable that these arguments be static, i.e., there should not  It is preferable that the arguments of @code{AC_INIT} be static, i.e.,
1513  be any shell computation, but they can be computed by M4.  The following  there should not be any shell computation, but they can be computed by
1514  M4 macros (e.g., @code{AC_PACKAGE_NAME}), output variables (e.g.,  M4.
1515  @code{PACKAGE_NAME}), and preprocessor symbols (e.g.,  
1516  @code{PACKAGE_NAME}) are then defined:  The following M4 macros (e.g., @code{AC_PACKAGE_NAME}), output variables
1517    (e.g., @code{PACKAGE_NAME}), and preprocessor symbols (e.g.,
1518    @code{PACKAGE_NAME}) are defined by @code{AC_INIT}:
1519    
1520  @table @asis  @table @asis
1521  @item @code{AC_PACKAGE_NAME}, @code{PACKAGE_NAME}  @item @code{AC_PACKAGE_NAME}, @code{PACKAGE_NAME}
# Line 1676  name is obsolete because some @code{make Line 1678  name is obsolete because some @code{make
1678  @section Outputting Files  @section Outputting Files
1679    
1680  Every Autoconf script, e.g., @file{configure.ac}, should finish by  Every Autoconf script, e.g., @file{configure.ac}, should finish by
1681  calling @code{AC_OUTPUT}.  It is the macro that generates  calling @code{AC_OUTPUT}.  That is the macro that generates
1682  @file{config.status}, which will create the @file{Makefile}s and any  @file{config.status}, which will create the @file{Makefile}s and any
1683  other files resulting from configuration.  The only required macro is  other files resulting from configuration.  This is the only required macro besides
1684  @code{AC_INIT} (@pxref{Input}).  @code{AC_INIT} (@pxref{Input}).
1685    
1686  @defmac AC_OUTPUT  @defmac AC_OUTPUT
# Line 1687  other files resulting from configuration Line 1689  other files resulting from configuration
1689  Generate @file{config.status} and launch it.  Call this macro once, at  Generate @file{config.status} and launch it.  Call this macro once, at
1690  the end of @file{configure.ac}.  the end of @file{configure.ac}.
1691    
1692  @file{config.status} will take all the configuration actions: all the  @file{config.status} will perform all the configuration actions: all the
1693  output files (see @ref{Configuration Files}, macro  output files (see @ref{Configuration Files}, macro
1694  @code{AC_CONFIG_FILES}), header files (see @ref{Configuration Headers},  @code{AC_CONFIG_FILES}), header files (see @ref{Configuration Headers},
1695  macro @code{AC_CONFIG_HEADERS}), commands (see @ref{Configuration  macro @code{AC_CONFIG_HEADERS}), commands (see @ref{Configuration
# Line 1702  Historically, the usage of @code{AC_OUTP Line 1704  Historically, the usage of @code{AC_OUTP
1704  @code{AC_OUTPUT} used to support.  @code{AC_OUTPUT} used to support.
1705    
1706    
1707  If you run @command{make} on subdirectories, you should run it using the  If you run @command{make} in subdirectories, you should run it using the
1708  @code{make} variable @code{MAKE}.  Most versions of @command{make} set  @code{make} variable @code{MAKE}.  Most versions of @command{make} set
1709  @code{MAKE} to the name of the @command{make} program plus any options it  @code{MAKE} to the name of the @command{make} program plus any options it
1710  was given.  (But many do not include in it the values of any variables  was given.  (But many do not include in it the values of any variables
# Line 1718  variable @code{SET_MAKE} to be empty.  O Line 1720  variable @code{SET_MAKE} to be empty.  O
1720  to contain @samp{MAKE=make}.  Calls @code{AC_SUBST} for @code{SET_MAKE}.  to contain @samp{MAKE=make}.  Calls @code{AC_SUBST} for @code{SET_MAKE}.
1721  @end defmac  @end defmac
1722    
1723  To use this macro, place a line like this in each @file{Makefile.in}  If you use this macro, place a line like this in each @file{Makefile.in}
1724  that runs @code{MAKE} on other directories:  that runs @code{MAKE} on other directories:
1725    
1726  @example  @example
# Line 1728  that runs @code{MAKE} on other directori Line 1730  that runs @code{MAKE} on other directori
1730    
1731    
1732  @node Configuration Actions  @node Configuration Actions
1733  @section Taking Configuration Actions  @section Performing Configuration Actions
1734    
1735  @file{configure} is designed so that it appears to do everything itself,  @file{configure} is designed so that it appears to do everything itself,
1736  but there is actually a hidden slave: @file{config.status}.  but there is actually a hidden slave: @file{config.status}.
# Line 1799  tree. Line 1801  tree.
1801  Shell commands output literally into @file{config.status}, and  Shell commands output literally into @file{config.status}, and
1802  associated with a tag that the user can use to tell @file{config.status}  associated with a tag that the user can use to tell @file{config.status}
1803  which the commands to run.  The commands are run each time a @var{tag}  which the commands to run.  The commands are run each time a @var{tag}
1804  request is given to @file{config.status}; typically, each time the file  request is given to @file{config.status}, typically each time the file
1805  @file{@var{tag}} is created.  @file{@var{tag}} is created.
1806    
1807  The variable set during the execution of @command{configure} are  The variables set during the execution of @command{configure} are
1808  @emph{not} available here: you first need to set them via the  @emph{not} available here: you first need to set them via the
1809  @var{init-cmds}.  Nonetheless the following variables are precomputed:  @var{init-cmds}.  Nonetheless the following variables are precomputed:
1810    
# Line 1882  values. Line 1884  values.
1884  @c because it complicates the write of Makefiles:  @c because it complicates the write of Makefiles:
1885  @c If the file would be unchanged, it is left untouched, to preserve  @c If the file would be unchanged, it is left untouched, to preserve
1886  @c timestamp.  @c timestamp.
1887  This macro is one of the instantiating macros, see @ref{Configuration  This macro is one of the instantiating macros; see @ref{Configuration
1888  Actions}.  @xref{Makefile Substitutions}, for more information on using  Actions}.  @xref{Makefile Substitutions}, for more information on using
1889  output variables.  @xref{Setting Output Variables}, for more information  output variables.  @xref{Setting Output Variables}, for more information
1890  on creating them.  This macro creates the directory that the file is in  on creating them.  This macro creates the directory that the file is in
# Line 2080  Absolute path of @code{builddir}. Line 2082  Absolute path of @code{builddir}.
2082  @defvar top_builddir  @defvar top_builddir
2083  @ovindex top_builddir  @ovindex top_builddir
2084  The relative path to the top-level of the current build tree.  In the  The relative path to the top-level of the current build tree.  In the
2085  top-level directory, this is the same as @code{srcbuild}.  top-level directory, this is the same as @code{builddir}.
2086  @end defvar  @end defvar
2087    
2088  @defvar abs_top_builddir  @defvar abs_top_builddir
# Line 2170  The top-level directory for installing d Line 2172  The top-level directory for installing d
2172    
2173  @defvar oldincludedir  @defvar oldincludedir
2174  @ovindex oldincludedir  @ovindex oldincludedir
2175  The directory for installing C header files for non-gcc compilers.  The directory for installing C header files for non-GCC compilers.
2176  @end defvar  @end defvar
2177    
2178  @defvar prefix  @defvar prefix
# Line 2265  }!  Use th Line 2267  }!  Use th
2267  instead.  instead.
2268    
2269  @item ,  @item ,
2270  Don't use @samp{/} in the sed expression(s) since most probably the  Don't use @samp{/} in the sed expression(s) since most likely the
2271  variables you use, such as @samp{$(pkgdatadir)}, will contain  variables you use, such as @samp{$(pkgdatadir)}, will contain
2272  some.  some.
2273    
# Line 2312  Do not set @code{VPATH} to the value of Line 2314  Do not set @code{VPATH} to the value of
2314  @samp{VPATH = $(srcdir)}, because some versions of @command{make} do not do  @samp{VPATH = $(srcdir)}, because some versions of @command{make} do not do
2315  variable substitutions on the value of @code{VPATH}.  variable substitutions on the value of @code{VPATH}.
2316    
2317  @command{configure} substitutes in the correct value for @code{srcdir} when  @command{configure} substitutes the correct value for @code{srcdir} when
2318  it produces @file{Makefile}.  it produces @file{Makefile}.
2319    
2320  Do not use the @code{make} variable @code{$<}, which expands to the  Do not use the @code{make} variable @code{$<}, which expands to the
# Line 2393  configuration-related dependencies. Line 2395  configuration-related dependencies.
2395  @cindex Configuration Header  @cindex Configuration Header
2396  @cindex @file{config.h}  @cindex @file{config.h}
2397    
2398  When a package tests more than a few C preprocessor symbols, the command  When a package contains more than a few tests that define C preprocessor symbols, the command
2399  lines to pass @option{-D} options to the compiler can get quite long.  lines to pass @option{-D} options to the compiler can get quite long.
2400  This causes two problems.  One is that the @command{make} output is hard to  This causes two problems.  One is that the @command{make} output is hard to
2401  visually scan for errors.  More seriously, the command lines can exceed  visually scan for errors.  More seriously, the command lines can exceed
# Line 2416  directory. Line 2418  directory.
2418  @defmac AC_CONFIG_HEADERS (@var{header} @dots{}, @ovar{cmds}, @ovar{init-cmds})  @defmac AC_CONFIG_HEADERS (@var{header} @dots{}, @ovar{cmds}, @ovar{init-cmds})
2419  @acindex CONFIG_HEADERS  @acindex CONFIG_HEADERS
2420  @cvindex HAVE_CONFIG_H  @cvindex HAVE_CONFIG_H
2421  This macro is one of the instantiating macros, see @ref{Configuration  This macro is one of the instantiating macros; see @ref{Configuration
2422  Actions}.  Make @code{AC_OUTPUT} create the file(s) in the  Actions}.  Make @code{AC_OUTPUT} create the file(s) in the
2423  whitespace-separated list @var{header} containing C preprocessor  whitespace-separated list @var{header} containing C preprocessor
2424  @code{#define} statements, and replace @samp{@@DEFS@@} in generated  @code{#define} statements, and replace @samp{@@DEFS@@} in generated
# Line 2425  The usual name for @var{header} is @file Line 2427  The usual name for @var{header} is @file
2427    
2428  If @var{header} already exists and its contents are identical to what  If @var{header} already exists and its contents are identical to what
2429  @code{AC_OUTPUT} would put in it, it is left alone.  Doing this allows  @code{AC_OUTPUT} would put in it, it is left alone.  Doing this allows
2430  some changes in configuration without needlessly causing object files  making some changes in the configuration without needlessly causing object files
2431  that depend on the header file to be recompiled.  that depend on the header file to be recompiled.
2432    
2433  Usually the input file is named @file{@var{header}.in}; however, you can  Usually the input file is named @file{@var{header}.in}; however, you can
2434  override the input file name by appending to @var{header}, a  override the input file name by appending to @var{header} a
2435  colon-separated list of input files.  Examples:  colon-separated list of input files.  Examples:
2436    
2437  @example  @example
# Line 2513  arguments are given, the first one is us Line 2515  arguments are given, the first one is us
2515    
2516  In order to do its job, @command{autoheader} needs you to document all  In order to do its job, @command{autoheader} needs you to document all
2517  of the symbols that you might use; i.e., there must be at least one  of the symbols that you might use; i.e., there must be at least one
2518  @code{AC_DEFINE} or one @code{AC_DEFINE_UNQUOTED} using its third  @code{AC_DEFINE} or one @code{AC_DEFINE_UNQUOTED} call with a third
2519  argument for each symbol (@pxref{Defining Symbols}).  An additional  argument for each symbol (@pxref{Defining Symbols}).  An additional
2520  constraint is that the first argument of @code{AC_DEFINE} must be a  constraint is that the first argument of @code{AC_DEFINE} must be a
2521  literal.  Note that all symbols defined by Autoconf's built-in tests are  literal.  Note that all symbols defined by Autoconf's builtin tests are
2522  already documented properly; you only need to document those that you  already documented properly; you only need to document those that you
2523  define yourself.  define yourself.
2524    
# Line 2530  however, you'll be thankful for the exis Line 2532  however, you'll be thankful for the exis
2532    
2533  The fact that the symbols are documented is important in order to  The fact that the symbols are documented is important in order to
2534  @emph{check} that @file{config.h} makes sense.  The fact that there is a  @emph{check} that @file{config.h} makes sense.  The fact that there is a
2535  well defined list of symbols that should be @code{#define}'d (or not) is  well-defined list of symbols that should be @code{#define}'d (or not) is
2536  also important for people who are porting packages to environments where  also important for people who are porting packages to environments where
2537  @command{configure} cannot be run: they just have to @emph{fill in the  @command{configure} cannot be run: they just have to @emph{fill in the
2538  blanks}.  blanks}.
# Line 2621  the @var{description} argument to an @sa Line 2623  the @var{description} argument to an @sa
2623  Tell @command{autoheader} to include the @var{template} as-is in the header  Tell @command{autoheader} to include the @var{template} as-is in the header
2624  template file.  This @var{template} is associated with the @var{key},  template file.  This @var{template} is associated with the @var{key},
2625  which is used to sort all the different templates and guarantee their  which is used to sort all the different templates and guarantee their
2626  uniqueness.  It should be the symbol that can be @code{AC_DEFINE}'d.  uniqueness.  It should be a symbol that can be @code{AC_DEFINE}'d.
2627    
2628  For example:  For example:
2629    
# Line 2682  Include @var{text} at the bottom of the Line 2684  Include @var{text} at the bottom of the
2684  @node Configuration Commands  @node Configuration Commands
2685  @section Running Arbitrary Configuration Commands  @section Running Arbitrary Configuration Commands
2686    
2687  You execute arbitrary commands either before, during and after  You can execute arbitrary commands before, during, and after
2688  @file{config.status} is run.  The three following macros accumulate the  @file{config.status} is run.  The three following macros accumulate the
2689  commands to run when they are called multiple times.  commands to run when they are called multiple times.
2690  @code{AC_CONFIG_COMMANDS} replaces the obsolete macro  @code{AC_CONFIG_COMMANDS} replaces the obsolete macro
2691  @code{AC_OUTPUT_COMMANDS}, see @ref{Obsolete Macros}, for details.  @code{AC_OUTPUT_COMMANDS}; see @ref{Obsolete Macros}, for details.
2692    
2693  @defmac AC_CONFIG_COMMANDS (@var{tag}@dots{}, @ovar{cmds}, @ovar{init-cmds})  @defmac AC_CONFIG_COMMANDS (@var{tag}@dots{}, @ovar{cmds}, @ovar{init-cmds})
2694  @acindex CONFIG_COMMANDS  @acindex CONFIG_COMMANDS
2695  Specify additional shell commands to run at the end of  Specify additional shell commands to run at the end of
2696  @file{config.status}, and shell commands to initialize any variables  @file{config.status}, and shell commands to initialize any variables
2697  from @command{configure}.  Associate the commands to the @var{tag}.  Since  from @command{configure}.  Associate the commands with @var{tag}.  Since
2698  typically the @var{cmds} create a file, @var{tag} should naturally be  typically the @var{cmds} create a file, @var{tag} should naturally be
2699  the name of that file.  This macro is one of the instantiating macros,  the name of that file.  This macro is one of the instantiating macros;
2700  see @ref{Configuration Actions}.  see @ref{Configuration Actions}.
2701    
2702  Here is an unrealistic example:  Here is an unrealistic example:
# Line 2730  Execute the @var{cmds} right after creat Line 2732  Execute the @var{cmds} right after creat
2732  You may find it convenient to create links whose destinations depend upon  You may find it convenient to create links whose destinations depend upon
2733  results of tests.  One can use @code{AC_CONFIG_COMMANDS} but the  results of tests.  One can use @code{AC_CONFIG_COMMANDS} but the
2734  creation of relative symbolic links can be delicate when the package is  creation of relative symbolic links can be delicate when the package is
2735  built in another directory than its sources.  built in a directory different from the source directory.
2736    
2737  @defmac AC_CONFIG_LINKS (@var{dest}:@var{source}@dots{}, @ovar{cmds}, @ovar{init-cmds})  @defmac AC_CONFIG_LINKS (@var{dest}:@var{source}@dots{}, @ovar{cmds}, @ovar{init-cmds})
2738  @acindex CONFIG_LINKS  @acindex CONFIG_LINKS
# Line 2740  the corresponding link name @var{dest}. Line 2742  the corresponding link name @var{dest}.
2742  possible, otherwise a hard link if possible, otherwise a copy.  The  possible, otherwise a hard link if possible, otherwise a copy.  The
2743  @var{dest} and @var{source} names should be relative to the top level  @var{dest} and @var{source} names should be relative to the top level
2744  source or build directory.  This macro is one of the instantiating  source or build directory.  This macro is one of the instantiating
2745  macros, see @ref{Configuration Actions}.  macros; see @ref{Configuration Actions}.
2746    
2747  For example, this call:  For example, this call:
2748    
# Line 2831  adjusting a relative path for the source Line 2833  adjusting a relative path for the source
2833    
2834  @item  @item
2835  propagating the current value of @code{$prefix}, including if it was  propagating the current value of @code{$prefix}, including if it was
2836  defaulted, and if default values of the top level and of sub directory  defaulted, and if the default values of the top level and of the subdirectory
2837  @file{configure} differ.  @file{configure} differ.
2838  @end itemize  @end itemize
2839    
2840  This macro also sets the output variable @code{subdirs} to the list of  This macro also sets the output variable @code{subdirs} to the list of
2841  directories @samp{@var{dir} @dots{}}.  @file{Makefile} rules can use  directories @samp{@var{dir} @dots{}}.  @file{Makefile} rules can use
2842  this variable to determine which subdirectories to recurse into.  This  this variable to determine which subdirectories to recurse into.
2843  macro may be called multiple times.  
2844    This macro may be called multiple times.
2845  @end defmac  @end defmac
2846    
2847  @node Default Prefix  @node Default Prefix
# Line 2850  prefix using the @option{--prefix} and @ Line 2853  prefix using the @option{--prefix} and @
2853  There are two ways to change the default: when creating  There are two ways to change the default: when creating
2854  @command{configure}, and when running it.  @command{configure}, and when running it.
2855    
2856  Some software packages might want to install in a directory besides  Some software packages might want to install in a directory other than
2857  @file{/usr/local} by default.  To accomplish that, use the  @file{/usr/local} by default.  To accomplish that, use the
2858  @code{AC_PREFIX_DEFAULT} macro.  @code{AC_PREFIX_DEFAULT} macro.
2859    
# Line 2871  If the user did not specify an installat Line 2874  If the user did not specify an installat
2874  @option{--prefix} option), guess a value for it by looking for  @option{--prefix} option), guess a value for it by looking for
2875  @var{program} in @code{PATH}, the way the shell does.  If @var{program}  @var{program} in @code{PATH}, the way the shell does.  If @var{program}
2876  is found, set the prefix to the parent of the directory containing  is found, set the prefix to the parent of the directory containing
2877  @var{program}; otherwise leave the prefix specified in  @var{program}, else default the prefix as described above
2878  @file{Makefile.in} unchanged.  For example, if @var{program} is  (@file{/usr/local} or @code{AC_PREFIX_DEFAULT}).  For example, if
2879  @code{gcc} and the @code{PATH} contains @file{/usr/local/gnu/bin/gcc},  @var{program} is @code{gcc} and the @code{PATH} contains
2880  set the prefix to @file{/usr/local/gnu}.  @file{/usr/local/gnu/bin/gcc}, set the prefix to @file{/usr/local/gnu}.
2881  @end defmac  @end defmac
2882    
2883    
# Line 3151  distribution. Line 3154  distribution.
3154  To ensure backward compatibility, Automake's @code{AM_PROG_LEX} invokes  To ensure backward compatibility, Automake's @code{AM_PROG_LEX} invokes
3155  (indirectly) this macro twice, which will cause an annoying but benign  (indirectly) this macro twice, which will cause an annoying but benign
3156  ``@code{AC_PROG_LEX} invoked multiple times'' warning.  Future versions  ``@code{AC_PROG_LEX} invoked multiple times'' warning.  Future versions
3157  of Automake will fix this issue, meanwhile, just ignore this message.  of Automake will fix this issue; meanwhile, just ignore this message.
3158  @end defmac  @end defmac
3159    
3160  @defmac AC_PROG_LN_S  @defmac AC_PROG_LN_S
# Line 3160  of Automake will fix this issue, meanwhi Line 3163  of Automake will fix this issue, meanwhi
3163  If @samp{ln -s} works on the current file system (the operating system  If @samp{ln -s} works on the current file system (the operating system
3164  and file system support symbolic links), set the output variable  and file system support symbolic links), set the output variable
3165  @code{LN_S} to @samp{ln -s}; otherwise, if @samp{ln} works, set  @code{LN_S} to @samp{ln -s}; otherwise, if @samp{ln} works, set
3166  @code{LN_S} to @samp{ln} and otherwise set it to @samp{cp -p}.  @code{LN_S} to @samp{ln}, and otherwise set it to @samp{cp -p}.
3167    
3168  If you make a link a directory other than the current directory, its  If you make a link in a directory other than the current directory, its
3169  meaning depends on whether @samp{ln} or @samp{ln -s} is used.  To safely  meaning depends on whether @samp{ln} or @samp{ln -s} is used.  To safely
3170  create links using @samp{$(LN_S)}, either find out which form is used  create links using @samp{$(LN_S)}, either find out which form is used
3171  and adjust the arguments, or always invoke @code{ln} in the directory  and adjust the arguments, or always invoke @code{ln} in the directory
# Line 3230  that case, set @var{variable} using the Line 3233  that case, set @var{variable} using the
3233  @defmac AC_CHECK_PROGS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path})  @defmac AC_CHECK_PROGS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3234  @acindex CHECK_PROGS  @acindex CHECK_PROGS
3235  Check for each program in the whitespace-separated list  Check for each program in the whitespace-separated list
3236  @var{progs-to-check-for} exists on the @code{PATH}.  If it is found, set  @var{progs-to-check-for} existing in the @code{PATH}.  If one is found, set
3237  @var{variable} to the name of that program.  Otherwise, continue  @var{variable} to the name of that program.  Otherwise, continue
3238  checking the next program in the list.  If none of the programs in the  checking the next program in the list.  If none of the programs in the
3239  list are found, set @var{variable} to @var{value-if-not-found}; if  list are found, set @var{variable} to @var{value-if-not-found}; if
# Line 3292  path of the program if it is found. Line 3295  path of the program if it is found.
3295  @cindex File, checking  @cindex File, checking
3296    
3297  You might also need to check for the existence of files.  Before using  You might also need to check for the existence of files.  Before using
3298  these macros, ask yourself whether a run time test might not be a better  these macros, ask yourself whether a run-time test might not be a better
3299  solution.  Be aware that, like most Autoconf macros, they test a feature  solution.  Be aware that, like most Autoconf macros, they test a feature
3300  of the host machine, and therefore, they die when cross-compiling.  of the host machine, and therefore, they die when cross-compiling.
3301    
# Line 3315  for each file found. Line 3318  for each file found.
3318  @section Library Files  @section Library Files
3319  @cindex Library, checking  @cindex Library, checking
3320    
3321  The following macros check for the presence of certain C, C++ or Fortran  The following macros check for the presence of certain C, C++, or Fortran
3322  77 library archive files.  77 library archive files.
3323    
3324  @defmac AC_CHECK_LIB (@var{library}, @var{function}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})  @defmac AC_CHECK_LIB (@var{library}, @var{function}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})
# Line 3332  with the library succeeds; @var{action-i Line 3335  with the library succeeds; @var{action-i
3335  commands to run if the link fails.  If @var{action-if-found} is not  commands to run if the link fails.  If @var{action-if-found} is not
3336  specified, the default action will prepend @option{-l@var{library}} to  specified, the default action will prepend @option{-l@var{library}} to
3337  @code{LIBS} and define @samp{HAVE_LIB@var{library}} (in all  @code{LIBS} and define @samp{HAVE_LIB@var{library}} (in all
3338  capitals).  This macro is intended to support building of @code{LIBS} in  capitals). This macro is intended to support building @code{LIBS} in
3339  a right-to-left (least-dependent to most-dependent) fashion such that  a right-to-left (least-dependent to most-dependent) fashion such that
3340  library dependencies are satisfied as a natural side-effect of  library dependencies are satisfied as a natural side-effect of
3341  consecutive tests.  Some linkers are very sensitive to library ordering  consecutive tests.  Some linkers are very sensitive to library ordering
# Line 3592  If the @code{fnmatch} function conforms Line 3595  If the @code{fnmatch} function conforms
3595  the bugs in Solaris 2.4.  the bugs in Solaris 2.4.
3596    
3597  Note that for historical reasons, contrary to the other specific  Note that for historical reasons, contrary to the other specific
3598  @code{AC_FUNC} macros, @code{AC_FUNC_FNMATCH} does not replace  @code{AC_FUNC} macros, @code{AC_FUNC_FNMATCH} does not replace a
3599  broken/missing @code{fnmatch}.  See @code{AC_REPLACE_FNMATCH} below.  broken/missing @code{fnmatch}.  See @code{AC_REPLACE_FNMATCH} below.
3600  @end defmac  @end defmac
3601    
# Line 3679  needed to get that function.  This macro Line 3682  needed to get that function.  This macro
3682  @ovindex GETLOADAVG_LIBS  @ovindex GETLOADAVG_LIBS
3683  @c @fuindex getloadavg  @c @fuindex getloadavg
3684  @prindex @code{getloadavg}  @prindex @code{getloadavg}
3685  Check how to get the system load averages.  To perform it tests  Check how to get the system load averages.  To perform its tests
3686  properly, this macro needs the file @file{getloadavg.c}; therefore, be  properly, this macro needs the file @file{getloadavg.c}; therefore, be
3687  sure to set the @code{AC_LIBOBJ} replacement directory properly (see  sure to set the @code{AC_LIBOBJ} replacement directory properly (see
3688  @ref{Generic Functions}, @code{AC_CONFIG_LIBOBJ_DIR}).  @ref{Generic Functions}, @code{AC_CONFIG_LIBOBJ_DIR}).
# Line 3764  If @file{link} is a symbolic link, then Line 3767  If @file{link} is a symbolic link, then
3767    
3768  It is safe to assume that if @code{lstat} incorrectly ignores  It is safe to assume that if @code{lstat} incorrectly ignores
3769  trailing slashes, then other symbolic-link-aware functions like  trailing slashes, then other symbolic-link-aware functions like
3770  @code{unlink} and @code{unlink} also incorrectly ignore trailing slashes.  @code{unlink} also incorrectly ignore trailing slashes.
3771    
3772  If @code{lstat} behaves properly, define  If @code{lstat} behaves properly, define
3773  @code{LSTAT_FOLLOWS_SLASHED_SYMLINK}, otherwise require an  @code{LSTAT_FOLLOWS_SLASHED_SYMLINK}, otherwise require an
# Line 3777  If @code{lstat} behaves properly, define Line 3780  If @code{lstat} behaves properly, define
3780  @cvindex malloc  @cvindex malloc
3781  @c @fuindex malloc  @c @fuindex malloc
3782  @prindex @code{malloc}  @prindex @code{malloc}
3783  If the @code{malloc} works correctly (@samp{malloc (0)} returns a valid  If the @code{malloc} function works correctly (@samp{malloc (0)} returns a valid
3784  pointer), define @code{HAVE_MALLOC} to 1.  Otherwise define  pointer), define @code{HAVE_MALLOC} to 1.  Otherwise define
3785  @code{HAVE_MALLOC} to 0, ask for an @code{AC_LIBOBJ} replacement for  @code{HAVE_MALLOC} to 0, ask for an @code{AC_LIBOBJ} replacement for
3786  @samp{malloc}, and define @code{malloc} to @code{rpl_malloc} so that the  @samp{malloc}, and define @code{malloc} to @code{rpl_malloc} so that the
3787  native @code{malloc} is not used in the main project.  native @code{malloc} is not used in the main project.
3788    
3789  Typically, the replacement file @file{malloc.c} should look like (note  Typically, the replacement file @file{malloc.c} should look like (note
3790  the @samp{#undef malloc}:  the @samp{#undef malloc}):
3791    
3792  @verbatim  @verbatim
3793  #if HAVE_CONFIG_H  #if HAVE_CONFIG_H
# Line 3854  If the obstacks are found, define @code{ Line 3857  If the obstacks are found, define @code{
3857  @cvindex realloc  @cvindex realloc
3858  @c @fuindex realloc  @c @fuindex realloc
3859  @prindex @code{realloc}  @prindex @code{realloc}
3860  If the @code{realloc} works correctly (@samp{realloc (0, 0)} returns a  If the @code{realloc} function works correctly (@samp{realloc (0, 0)} returns a
3861  valid pointer), define @code{HAVE_REALLOC} to 1.  Otherwise define  valid pointer), define @code{HAVE_REALLOC} to 1.  Otherwise define
3862  @code{HAVE_REALLOC} to 0, ask for an @code{AC_LIBOBJ} replacement for  @code{HAVE_REALLOC} to 0, ask for an @code{AC_LIBOBJ} replacement for
3863  @samp{realloc}, and define @code{realloc} to @code{rpl_realloc} so that  @samp{realloc}, and define @code{realloc} to @code{rpl_realloc} so that
# Line 3900  first call @code{AC_CHECK_FUNC} for @cod Line 3903  first call @code{AC_CHECK_FUNC} for @cod
3903  @c @fuindex lstat  @c @fuindex lstat
3904  @prindex @code{lstat}  @prindex @code{lstat}
3905  Determine whether @code{stat} or @code{lstat} have the bug that it  Determine whether @code{stat} or @code{lstat} have the bug that it
3906  succeeds when given the zero-length file name argument.  The @code{stat}  succeeds when given the zero-length file name as argument.  The @code{stat}
3907  and @code{lstat} from SunOS 4.1.4 and the Hurd (as of 1998-11-01) do  and @code{lstat} from SunOS 4.1.4 and the Hurd (as of 1998-11-01) do
3908  this.  this.
3909    
# Line 4157  it, then you can use one of the general Line 4160  it, then you can use one of the general
4160  @subsection Portability of Headers  @subsection Portability of Headers
4161    
4162  This section tries to collect knowledge about common headers, and the  This section tries to collect knowledge about common headers, and the
4163  problem they cause.  By definition, this list will always require  problems they cause.  By definition, this list will always require
4164  additions.  Please help us keeping it as complete as possible.  additions.  Please help us keeping it as complete as possible.
4165    
4166  @table @asis  @table @asis
# Line 4268  header files. Line 4271  header files.
4271  On systems without @sc{ansi} C headers, there is so much variation that  On systems without @sc{ansi} C headers, there is so much variation that
4272  it is probably easier to declare the functions you use than to figure  it is probably easier to declare the functions you use than to figure
4273  out exactly what the system header files declare.  Some systems contain  out exactly what the system header files declare.  Some systems contain
4274  a mix of functions @sc{ansi} and @sc{bsd}; some are mostly @sc{ansi} but  a mix of functions from @sc{ansi} and @sc{bsd}; some are mostly @sc{ansi} but
4275  lack @samp{memmove}; some define the @sc{bsd} functions as macros in  lack @samp{memmove}; some define the @sc{bsd} functions as macros in
4276  @file{string.h} or @file{strings.h}; some have only the @sc{bsd}  @file{string.h} or @file{strings.h}; some have only the @sc{bsd}
4277  functions but @file{string.h}; some declare the memory functions in  functions but @file{string.h}; some declare the memory functions in
# Line 4283  AC_CHECK_FUNCS(strchr memcpy) Line 4286  AC_CHECK_FUNCS(strchr memcpy)
4286  @end example  @end example
4287    
4288  @noindent  @noindent
4289  then, in your code, you can put declarations like this:  then, in your code, you can use declarations like this:
4290    
4291  @example  @example
4292  @group  @group
# Line 4458  two headers are compatible. Line 4461  two headers are compatible.
4461  @end table  @end table
4462    
4463  You may pass any kind of dummy content for @var{includes}, such as a  You may pass any kind of dummy content for @var{includes}, such as a
4464  single space, a comment, to check whether @var{header-file} compiles  single space or a comment, to check whether @var{header-file} compiles
4465  with success.  with success.
4466  @end defmac  @end defmac
4467    
# Line 4577  the configuration.  In most cases the tr Line 4580  the configuration.  In most cases the tr
4580    
4581  The following macros check for the presence of certain members in C  The following macros check for the presence of certain members in C
4582  structures.  If there is no macro specifically defined to check for a  structures.  If there is no macro specifically defined to check for a
4583  member you need, then you can use the general structure-member macro  member you need, then you can use the general structure-member macros
4584  (@pxref{Generic Structures}) or, for more complex tests, you may use  (@pxref{Generic Structures}) or, for more complex tests, you may use
4585  @code{AC_TRY_COMPILE} (@pxref{Examining Syntax}).  @code{AC_TRY_COMPILE} (@pxref{Examining Syntax}).
4586    
# Line 4624  future. Line 4627  future.
4627  If @code{struct stat} contains an @code{st_rdev} member, define  If @code{struct stat} contains an @code{st_rdev} member, define
4628  @code{HAVE_STRUCT_STAT_ST_RDEV}.  The former name for this macro,  @code{HAVE_STRUCT_STAT_ST_RDEV}.  The former name for this macro,
4629  @code{HAVE_ST_RDEV}, is to be avoided as it will cease to be supported  @code{HAVE_ST_RDEV}, is to be avoided as it will cease to be supported
4630  in the future.  Actually, even the new macro is obsolete, and should be  in the future.  Actually, even the new macro is obsolete and should be
4631  replaced by:  replaced by:
4632  @example  @example
4633  AC_CHECK_MEMBERS([struct stat.st_rdev])  AC_CHECK_MEMBERS([struct stat.st_rdev])
# Line 4825  They also define the output variable @co Line 4828  They also define the output variable @co
4828  output of the compiler, after @file{.c} files have been excluded, typically  output of the compiler, after @file{.c} files have been excluded, typically
4829  to @samp{o} if Unix, @samp{obj} if Win32.  to @samp{o} if Unix, @samp{obj} if Win32.
4830    
4831  If the compiler being used does not produce executables, they fail.  If  If the compiler being used does not produce executables, the tests fail.  If
4832  the executables can't be run, and cross-compilation is not enabled, they  the executables can't be run, and cross-compilation is not enabled, they
4833  fail too.  @xref{Manual Configuration}, for more on support for cross  fail too.  @xref{Manual Configuration}, for more on support for cross
4834  compiling.  compiling.
# Line 4991  Define @samp{HAVE_C_BACKSLASH_A} to 1 if Line 4994  Define @samp{HAVE_C_BACKSLASH_A} to 1 if
4994  @cindex Endianness  @cindex Endianness
4995  If words are stored with the most significant byte first (like Motorola  If words are stored with the most significant byte first (like Motorola
4996  and SPARC CPUs), execute @var{action-if-true}.  If words are stored with  and SPARC CPUs), execute @var{action-if-true}.  If words are stored with
4997  the less significant byte first (like Intel and VAX CPUs), execute  the least significant byte first (like Intel and VAX CPUs), execute
4998  @var{action-if-false}.  @var{action-if-false}.
4999    
5000  This macro runs a test-case if endianness cannot be determined from the  This macro runs a test-case if endianness cannot be determined from the
5001  system header files.  When cross-compiling the test-case is not run but  system header files.  When cross-compiling, the test-case is not run but
5002  grep'ed for some magic values.  @var{action-if-unknown} is executed if  grep'ed for some magic values.  @var{action-if-unknown} is executed if
5003  the latter case fails to determine the byte sex of the host system.  the latter case fails to determine the byte sex of the host system.
5004    
# Line 5281  a user-provided entry function named (sa Line 5284  a user-provided entry function named (sa
5284  user's program.  The @code{AC_F77_DUMMY_MAIN} or @code{AC_F77_MAIN}  user's program.  The @code{AC_F77_DUMMY_MAIN} or @code{AC_F77_MAIN}
5285  macro figures out how to deal with this interaction.  macro figures out how to deal with this interaction.
5286    
5287  When using Fortran for purely numerical functions (no I/O, etcetera),  When using Fortran for purely numerical functions (no I/O, etc. often
5288  users often prefer to provide their own @code{main} and skip the Fortran  prefer to provide their own @code{main} and skip the Fortran library
5289  library initializations.  In this case, however, one may still need to  initializations.  In this case, however, one may still need to provide a
5290  provide a dummy @code{MAIN__} routine in order to prevent linking errors  dummy @code{MAIN__} routine in order to prevent linking errors on some
5291  on some systems.  @code{AC_F77_DUMMY_MAIN} detects whether any such  systems.  @code{AC_F77_DUMMY_MAIN} detects whether any such routine is
5292  routine is @emph{required} for linking, and what its name is; the shell  @emph{required} for linking, and what its name is; the shell variable
5293  variable @code{F77_DUMMY_MAIN} holds this name, @code{unknown} when no  @code{F77_DUMMY_MAIN} holds this name, @code{unknown} when no solution
5294  solution was found, and @code{none} when no such dummy main is needed.  was found, and @code{none} when no such dummy main is needed.
5295    
5296  By default, @var{action-if-found} defines @code{F77_DUMMY_MAIN} to the  By default, @var{action-if-found} defines @code{F77_DUMMY_MAIN} to the
5297  name of this routine (e.g., @code{MAIN__}) @emph{if} it is required.  name of this routine (e.g., @code{MAIN__}) @emph{if} it is required.
# Line 5401  Fortran 77 linker (see also @code{AC_F77 Line 5404  Fortran 77 linker (see also @code{AC_F77
5404  optional; if it is not supplied, the shell variable will be simply  optional; if it is not supplied, the shell variable will be simply
5405  @var{name}.  The purpose of this macro is to give the caller a way to  @var{name}.  The purpose of this macro is to give the caller a way to
5406  access the name-mangling information other than through the C  access the name-mangling information other than through the C
5407  preprocessor as above; for example, to call Fortran routines from some  preprocessor as above, for example, to call Fortran routines from some
5408  language other than C/C++.  language other than C/C++.
5409  @end defmac  @end defmac
5410    
# Line 5418  user gave the command line options @opti Line 5421  user gave the command line options @opti
5421  both were not given, get the missing values by running @code{xmkmf} on a  both were not given, get the missing values by running @code{xmkmf} on a
5422  trivial @file{Imakefile} and examining the @file{Makefile} that it  trivial @file{Imakefile} and examining the @file{Makefile} that it
5423  produces.  If that fails (such as if @code{xmkmf} is not present), look  produces.  If that fails (such as if @code{xmkmf} is not present), look
5424  for them in several directories where they often reside.  If either  for the files in several directories where they often reside.  If either
5425  method is successful, set the shell variables @code{x_includes} and  method is successful, set the shell variables @code{x_includes} and
5426  @code{x_libraries} to their locations, unless they are in directories  @code{x_libraries} to their locations, unless they are in directories
5427  the compiler searches by default.  the compiler searches by default.
# Line 5494  If the system supports file names longer Line 5497  If the system supports file names longer
5497  @acindex SYS_POSIX_TERMIOS  @acindex SYS_POSIX_TERMIOS
5498  @cindex POSIX termios headers  @cindex POSIX termios headers
5499  @cindex termios POSIX headers  @cindex termios POSIX headers
5500  Check to see if POSIX termios headers and functions are available on the  Check to see if the POSIX termios headers and functions are available on the
5501  system.  If so, set the shell variable @code{ac_cv_sys_posix_termios} to  system.  If so, set the shell variable @code{ac_cv_sys_posix_termios} to
5502  @samp{yes}.  If not, set the variable to @samp{no}.  @samp{yes}.  If not, set the variable to @samp{no}.
5503  @end defmac  @end defmac
# Line 5649  been called already. Line 5652  been called already.
5652  @node Examining Syntax  @node Examining Syntax
5653  @section Examining Syntax  @section Examining Syntax
5654    
5655  To check for a syntax feature of the C, C++ or Fortran 77 compiler, such  To check for a syntax feature of the C, C++, or Fortran 77 compiler, such
5656  as whether it recognizes a certain keyword, use @code{AC_TRY_COMPILE} to  as whether it recognizes a certain keyword, use @code{AC_TRY_COMPILE} to
5657  try to compile a small program that uses that feature.  You can also use  try to compile a small program that uses that feature.  You can also use
5658  it to check for structures and structure members that are not present on  it to check for structures and structure members that are not present on
# Line 5687  available.  Trying to link with the func Line 5690  available.  Trying to link with the func
5690  approach because it avoids dealing with the variations in the options  approach because it avoids dealing with the variations in the options
5691  and output formats of @code{nm} and @code{ar} and in the location of the  and output formats of @code{nm} and @code{ar} and in the location of the
5692  standard libraries.  It also allows configuring for cross-compilation or  standard libraries.  It also allows configuring for cross-compilation or
5693  checking a function's runtime behavior if needed.  On the other hand, it  checking a function's run-time behavior if needed.  On the other hand, it
5694  can be slower than scanning the libraries once.  can be slower than scanning the libraries once.
5695    
5696  A few systems have linkers that do not return a failure exit status when  A few systems have linkers that do not return a failure exit status when
# Line 5785  an error message and exits. Line 5788  an error message and exits.
5788    
5789  In the @var{action-if-false} section, the exit status of the program is  In the @var{action-if-false} section, the exit status of the program is
5790  available in the shell variable @samp{$?}, but be very careful to limit  available in the shell variable @samp{$?}, but be very careful to limit
5791  yourself to positive values smaller than 127; bigger values shall be  yourself to positive values smaller than 127; bigger values should be
5792  saved into a file by the @var{program}.  Note also that you have simply  saved into a file by the @var{program}.  Note also that you have simply
5793  no guarantee that this exit status is issued by the @var{program}, or by  no guarantee that this exit status is issued by the @var{program}, or by
5794  the failure of its compilation.  In other words, use this feature if  the failure of its compilation.  In other words, use this feature if
# Line 5899  contains a lot of interesting crossed in Line 5902  contains a lot of interesting crossed in
5902  @table @asis  @table @asis
5903  @item Darwin  @item Darwin
5904  @cindex Darwin  @cindex Darwin
5905  Darwin is also known as Mac OS X.  Beware that this system @emph{can} be  Darwin is also known as Mac OS X.  Beware that the file system @emph{can} be
5906  case-preserving, but case insensitive.  This can cause nasty problems,  case-preserving, but case insensitive.  This can cause nasty problems,
5907  since for instance the installation attempt for a package having an  since for instance the installation attempt for a package having an
5908  @file{INSTALL} file can result in @samp{make install} report that  @file{INSTALL} file can result in @samp{make install} report that
# Line 5918  tree on the UFS). Line 5921  tree on the UFS).
5921  @c it'd be great.  In particular, I can't understand the difference with  @c it'd be great.  In particular, I can't understand the difference with
5922  @c QNX Neutrino.  @c QNX Neutrino.
5923  @sc{qnx} is a realtime operating system running on Intel architecture  @sc{qnx} is a realtime operating system running on Intel architecture
5924  meant to be scalable from the small embedded systems to hundred  meant to be scalable from the small embedded systems to the hundred
5925  processor super-computer.  It claims to be @sc{posix} certified.  More  processor super-computer.  It claims to be @sc{posix} certified.  More
5926  information is available on the @href{www.qnx.com, @sc{qnx} home page},  information is available on the @href{www.qnx.com, @sc{qnx} home page},
5927  including the @href{http://support.qnx.com/support/docs/qnx4/, @sc{qnx}  including the @href{http://support.qnx.com/support/docs/qnx4/, @sc{qnx}
# Line 5985  which programming language is used in th Line 5988  which programming language is used in th
5988  @file{configure.ac}.  @file{configure.ac}.
5989    
5990  @defmac AC_LANG (@var{language})  @defmac AC_LANG (@var{language})
5991  Do compilation tests using the compiler, preprocessor and file  Do compilation tests using the compiler, preprocessor, and file
5992  extensions for the specified @var{language}.  extensions for the specified @var{language}.
5993    
5994  Supported languages are:  Supported languages are:
# Line 6126  AC_DEFINE_UNQUOTED($ac_tr_hdr) Line 6129  AC_DEFINE_UNQUOTED($ac_tr_hdr)
6129  @end example  @end example
6130  @end defmac  @end defmac
6131    
6132  Due to the syntactical bizarreness of the Bourne shell, do not use  Due to a syntactical bizarreness of the Bourne shell, do not use
6133  semicolons to separate @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED}  semicolons to separate @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED}
6134  calls from other macro calls or shell code; that can cause syntax errors  calls from other macro calls or shell code; that can cause syntax errors
6135  in the resulting @command{configure} script.  Use either spaces or  in the resulting @command{configure} script.  Use either spaces or
# Line 6171  value that the shell variable @var{varia Line 6174  value that the shell variable @var{varia
6174  is called.  This value of @var{variable} should not contain literal  is called.  This value of @var{variable} should not contain literal
6175  newlines.  newlines.
6176    
6177  If @var{value} is given, in addition assign it to @samp{variable}.  If @var{value} is given, in addition assign it to @var{variable}.
6178  @end defmac  @end defmac
6179    
6180  @defmac AC_SUBST_FILE (@var{variable})  @defmac AC_SUBST_FILE (@var{variable})
# Line 6205  and then a @file{Makefile.in} could cont Line 6208  and then a @file{Makefile.in} could cont
6208    
6209  @cindex Previous Variable  @cindex Previous Variable
6210  @cindex Variable, Precious  @cindex Variable, Precious
6211  Running @command{configure} in different environments can be extremely  Running @command{configure} in varying environments can be extremely
6212  dangerous.  If for instance the user runs @samp{CC=bizarre-cc  dangerous.  If for instance the user runs @samp{CC=bizarre-cc
6213  ./configure}, then the cache, @file{config.h} and many other output  ./configure}, then the cache, @file{config.h}, and many other output
6214  files will depend upon @command{bizarre-cc} being the C compiler.  If  files will depend upon @command{bizarre-cc} being the C compiler.  If
6215  for some reason the user runs @command{/configure} again, or if it is  for some reason the user runs @command{./configure} again, or if it is
6216  run via @samp{./config.status --recheck}, (@xref{Automatic Remaking},  run via @samp{./config.status --recheck}, (@xref{Automatic Remaking},
6217  and @pxref{config.status Invocation}), then the configuration can be  and @pxref{config.status Invocation}), then the configuration can be
6218  inconsistent, composed of results depending upon two different  inconsistent, composed of results depending upon two different
6219  compilers.  compilers.
6220    
6221  Such variables are named @dfn{precious variables}, and can be declared  Environment variables that affect this situation, such as @samp{CC}
6222  as such by @code{AC_ARG_VAR}.  above, are called @dfn{precious variables}, and can be declared as such
6223    by @code{AC_ARG_VAR}.
6224    
6225  @defmac AC_ARG_VAR (@var{variable}, @var{description})  @defmac AC_ARG_VAR (@var{variable}, @var{description})
6226  @acindex ARG_VAR  @acindex ARG_VAR
# Line 6410  be omitted if it does not apply. Line 6414  be omitted if it does not apply.
6414  @end table  @end table
6415    
6416  The values assigned to cache variables may not contain newlines.  The values assigned to cache variables may not contain newlines.
6417  Usually, their values will be boolean (@samp{yes} or @samp{no}) or the  Usually, their values will be Boolean (@samp{yes} or @samp{no}) or the
6418  names of files or functions; so this is not an important restriction.  names of files or functions; so this is not an important restriction.
6419    
6420  @node Cache Files  @node Cache Files
# Line 6605  and their interface might change in the Line 6609  and their interface might change in the
6609  * M4 Quotation::                Protecting macros from unwanted expansion  * M4 Quotation::                Protecting macros from unwanted expansion
6610  * Invoking autom4te::           The Autoconf executables backbone  * Invoking autom4te::           The Autoconf executables backbone
6611  * Programming in M4sugar::      Convenient pure M4 macros  * Programming in M4sugar::      Convenient pure M4 macros
6612  * Programming in M4sh::         Common Shell Constructs  * Programming in M4sh::         Common shell Constructs
6613  @end menu  @end menu
6614    
6615  @node M4 Quotation  @node M4 Quotation
# Line 6623  for Autoconf and then ends with a rule o Line 6627  for Autoconf and then ends with a rule o
6627  former helps one to follow the latter.  former helps one to follow the latter.
6628    
6629  @menu  @menu
6630  * Active Characters::           Characters that change the behavior of m4  * Active Characters::           Characters that change the behavior of M4
6631  * One Macro Call::              Quotation and one macro call  * One Macro Call::              Quotation and one macro call
6632  * Quotation and Nested Macros::  Macros calling macros  * Quotation and Nested Macros::  Macros calling macros
6633  * Changequote is Evil::         Worse than INTERCAL: M4 + changequote  * Changequote is Evil::         Worse than INTERCAL: M4 + changequote
# Line 6635  former helps one to follow the latter. Line 6639  former helps one to follow the latter.
6639  @subsection Active Characters  @subsection Active Characters
6640    
6641  To fully understand where proper quotation is important, you first need  To fully understand where proper quotation is important, you first need
6642  to know what are the special characters in Autoconf: @samp{#} introduces  to know what the special characters are in Autoconf: @samp{#} introduces
6643  a comment inside which no macro expansion is performed, @samp{,}  a comment inside which no macro expansion is performed, @samp{,}
6644  separates arguments, @samp{[} and @samp{]} are the quotes themselves,  separates arguments, @samp{[} and @samp{]} are the quotes themselves,
6645  and finally @samp{(} and @samp{)} (which @code{m4} tries to match by  and finally @samp{(} and @samp{)} (which @code{m4} tries to match by
# Line 6643  pairs). Line 6647  pairs).
6647    
6648  In order to understand the delicate case of macro calls, we first have  In order to understand the delicate case of macro calls, we first have
6649  to present some obvious failures.  Below they are ``obvious-ified'',  to present some obvious failures.  Below they are ``obvious-ified'',
6650  although you find them in real life, they are usually in disguise.  btu when you find them in real life, they are usually in disguise.
6651    
6652  Comments, introduced by a hash and running up to the newline, are opaque  Comments, introduced by a hash and running up to the newline, are opaque
6653  tokens to the top level: active characters are turned off, and there is  tokens to the top level: active characters are turned off, and there is
# Line 6655  no macro expansion: Line 6659  no macro expansion:
6659  @end example  @end example
6660    
6661  Each time there can be a macro expansion, there is a quotation  Each time there can be a macro expansion, there is a quotation
6662  expansion; i.e., one level of quotes is stripped:  expansion, i.e., one level of quotes is stripped:
6663    
6664  @example  @example
6665  int tab[10];  int tab[10];
# Line 6896  finally surrender to the dark side of th Line 6900  finally surrender to the dark side of th
6900  weapon: @code{changequote}.  weapon: @code{changequote}.
6901    
6902  The M4 builtin @code{changequote} belongs to a set of primitives that  The M4 builtin @code{changequote} belongs to a set of primitives that
6903  allow one to adjust the syntax of the language to adjust it to her  allow one to adjust the syntax of the language to adjust it to one's
6904  needs.  For instance, by default M4 uses @samp{`} and @samp{'} as  needs.  For instance, by default M4 uses @samp{`} and @samp{'} as
6905  quotes, but in the context of shell programming (and actually of most  quotes, but in the context of shell programming (and actually of most
6906  programming languages), it's about the worst choice one can make:  programming languages), that's about the worst choice one can make:
6907  because of strings and back quoted expression in shell (such as  because of strings and back-quoted expressions in shell code (such as
6908  @samp{'this'} and @samp{`that`}), because of literal characters in usual  @samp{'this'} and @samp{`that`}), because of literal characters in usual
6909  programming language (as in @samp{'0'}), there are many unbalanced  programming languages (as in @samp{'0'}), there are many unbalanced
6910  @samp{`} and @samp{'}.  Proper M4 quotation then becomes a nightmare, if  @samp{`} and @samp{'}.  Proper M4 quotation then becomes a nightmare, if
6911  not impossible.  In order to make M4 useful in such a context, its  not impossible.  In order to make M4 useful in such a context, its
6912  designers have equipped it with @code{changequote}, which makes it  designers have equipped it with @code{changequote}, which makes it
6913  possible to chose another pair of quotes.  M4sugar, M4sh, Autoconf, and  possible to choose another pair of quotes.  M4sugar, M4sh, Autoconf, and
6914  Autotest all have chosen to use @samp{[} and @samp{]}.  Not especially  Autotest all have chosen to use @samp{[} and @samp{]}.  Not especially
6915  because they are unlikely characters, but @emph{because they are  because they are unlikely characters, but @emph{because they are
6916  characters unlikely to be unbalanced}.  characters unlikely to be unbalanced}.
# Line 6930  There lies the problem@enddots{} Line 6934  There lies the problem@enddots{}
6934    
6935  The problem is that it is then tempting to use them in the middle of an  The problem is that it is then tempting to use them in the middle of an
6936  M4 script, as opposed to its initialization.  This, if not carefully  M4 script, as opposed to its initialization.  This, if not carefully
6937  thought, can lead to disastrous effects: @emph{you are changing the  thought out, can lead to disastrous effects: @emph{you are changing the
6938  language in the middle of the execution}.  Changing and restoring the  language in the middle of the execution}.  Changing and restoring the
6939  syntax is often not enough: if you happened to invoke macros in between,  syntax is often not enough: if you happened to invoke macros in between,
6940  these macros will be lost, as the current syntax will probably not be  these macros will be lost, as the current syntax will probably not be
# Line 6981  will appear as @samp{^[} in the output. Line 6985  will appear as @samp{^[} in the output.
6985  The empty quadrigraph can be used:  The empty quadrigraph can be used:
6986    
6987  @itemize @minus  @itemize @minus
6988  @item to mark explicitly trailing spaces  @item to mark trailing spaces explicitly
6989    
6990  Trailing spaces are smashed by @command{autom4te}.  This is a feature.  Trailing spaces are smashed by @command{autom4te}.  This is a feature.
6991    
# Line 6991  } produce Line 6995  } produce
6995    
6996  @item to escape @emph{occurrences} of forbidden patterns  @item to escape @emph{occurrences} of forbidden patterns
6997    
6998  For instance you might want to mention @code{AC_FOO} is a comment, while  For instance you might want to mention @code{AC_FOO} in a comment, while
6999  still being sure that @command{autom4te} will still catch unexpanded  still being sure that @command{autom4te} will still catch unexpanded
7000  @samp{AC_*}.  Then write @samp{AC@@&t@@_FOO}.  @samp{AC_*}.  Then write @samp{AC@@&t@@_FOO}.
7001  @end itemize  @end itemize
# Line 7109  by doing @samp{grep AC_ configure}. Line 7113  by doing @samp{grep AC_ configure}.
7113  @node Invoking autom4te  @node Invoking autom4te
7114  @section Invoking @command{autom4te}  @section Invoking @command{autom4te}
7115    
7116  The Autoconf suite, including M4sugar, M4sh, and Autotest in addition to  The Autoconf suite, including M4sugar, M4sh, and Autotest, in addition to
7117  Autoconf per se, heavily rely on M4.  All these different uses revealed  Autoconf per se, heavily rely on M4.  All these different uses revealed
7118  common needs factored into a layer over @command{m4}:  common needs factored into a layer over @command{m4}:
7119  @command{autom4te}@footnote{  @command{autom4te}@footnote{
7120  @c  @c
7121  Yet another great name for Lars J. Aas.  Yet another great name from Lars J. Aas.
7122  @c  @c
7123  }.  }.
7124    
# Line 7285  m4 --reload-state=4.m4f input.m4 Line 7289  m4 --reload-state=4.m4f input.m4
7289  @itemx -f  @itemx -f
7290  Produce a frozen state file.  @command{autom4te} freezing is stricter  Produce a frozen state file.  @command{autom4te} freezing is stricter
7291  than M4's: it must produce no warnings, and no output other than empty  than M4's: it must produce no warnings, and no output other than empty
7292  lines (a line with white spaces is @emph{not} empty) and comments  lines (a line with whitespace is @emph{not} empty) and comments
7293  (starting with @samp{#}).  Please, note that contrary to @command{m4},  (starting with @samp{#}).  Please, note that contrary to @command{m4},
7294  this options takes no argument:  this options takes no argument:
7295    
# Line 7302  m4 1.m4 2.m4 3.m4 --freeze-state=3.m4f Line 7306  m4 1.m4 2.m4 3.m4 --freeze-state=3.m4f
7306    
7307  @item --mode=@var{octal-mode}  @item --mode=@var{octal-mode}
7308  @itemx -m @var{octal-mode}  @itemx -m @var{octal-mode}
7309  Set the mode of the non traces output to @var{octal-mode}.  By default,  Set the mode of the non-traces output to @var{octal-mode}; by default
7310  @samp{0666}.  @samp{0666}.
7311  @end table  @end table
7312    
# Line 7336  M4, and helps exploiting the cache: Line 7340  M4, and helps exploiting the cache:
7340  @table @option  @table @option
7341  @item --trace=@var{macro}[:@var{format}]  @item --trace=@var{macro}[:@var{format}]
7342  @itemx -t @var{macro}[:@var{format}]  @itemx -t @var{macro}[:@var{format}]
7343  Trace the invocations to @var{macro} according to the @var{format}.  Trace the invocations of @var{macro} according to the @var{format}.
7344  Multiple @option{--trace} arguments can be used to list several macros.  Multiple @option{--trace} arguments can be used to list several macros.
7345  Multiple @option{--trace} arguments for a single macro are not  Multiple @option{--trace} arguments for a single macro are not
7346  cumulative; instead, you should just make @var{format} as long as  cumulative; instead, you should just make @var{format} as long as
# Line 7394  not. Line 7398  not.
7398  @item --preselect=@var{macro}  @item --preselect=@var{macro}
7399  @itemx -p @var{macro}  @itemx -p @var{macro}
7400  Cache the traces of @var{macro}, but do not enable traces.  This is  Cache the traces of @var{macro}, but do not enable traces.  This is
7401  especially important to save cpu cycles in the future.  For instance,  especially important to save CPU cycles in the future.  For instance,
7402  when invoked, @command{autoconf} preselects all the macros that  when invoked, @command{autoconf} preselects all the macros that
7403  @command{autoheader}, @command{automake}, @command{autoreconf} etc.@: will  @command{autoheader}, @command{automake}, @command{autoreconf} etc.@: will
7404  trace, so that running @command{m4} is not needed to trace them: the  trace, so that running @command{m4} is not needed to trace them: the
# Line 7439  As an example, if Autoconf is installed Line 7443  As an example, if Autoconf is installed
7443  @file{/usr/local}, running @samp{autom4te -l m4sugar foo.m4} is  @file{/usr/local}, running @samp{autom4te -l m4sugar foo.m4} is
7444  strictly equivalent to running @samp{autom4te --prepend-include  strictly equivalent to running @samp{autom4te --prepend-include
7445  /usr/local/share/autoconf m4sugar/m4sugar.m4f --warning syntax foo.m4}.  /usr/local/share/autoconf m4sugar/m4sugar.m4f --warning syntax foo.m4}.
7446  Recursive expansion applies: running @samp{autom4te -l m4sh foo.m4},  Recursive expansion applies: running @samp{autom4te -l m4sh foo.m4}
7447  is the same as @samp{autom4te --language M4sugar m4sugar/m4sh.m4f  is the same as @samp{autom4te --language M4sugar m4sugar/m4sh.m4f
7448  foo.m4}, i.e., @samp{autom4te --prepend-include /usr/local/share/autoconf  foo.m4}, i.e., @samp{autom4te --prepend-include /usr/local/share/autoconf
7449  m4sugar/m4sugar.m4f m4sugar/m4sh.m4f --mode 777 foo.m4}.  The definition  m4sugar/m4sugar.m4f m4sugar/m4sh.m4f --mode 777 foo.m4}.  The definition
# Line 7549  m4_wrap([foo]) Line 7553  m4_wrap([foo])
7553  @subsection Evaluation Macros  @subsection Evaluation Macros
7554    
7555  The following macros give some control over the order of the evaluation  The following macros give some control over the order of the evaluation
7556  by adding or removing levels of quotes.  They are meant for hard core M4  by adding or removing levels of quotes.  They are meant for hard-core M4
7557  programmers.  programmers.
7558    
7559  @defmac m4_dquote (@var{arg1}, @dots{})  @defmac m4_dquote (@var{arg1}, @dots{})
# Line 7569  using these macros, (ii), using @code{m4 Line 7573  using these macros, (ii), using @code{m4
7573    
7574  @example  @example
7575  $ @kbd{cat example.m4}  $ @kbd{cat example.m4}
7576  # Over quote, so that quotes are visible.  # Overquote, so that quotes are visible.
7577  m4_define([show], [$[]1 = [$1], $[]@@ = [$@@]])  m4_define([show], [$[]1 = [$1], $[]@@ = [$@@]])
7578  m4_divert(0)dnl  m4_divert(0)dnl
7579  show(a, b)  show(a, b)
# Line 7590  M4sugar provides a means to define suspi Line 7594  M4sugar provides a means to define suspi
7594  describing tokens which should not be found in the output.  For  describing tokens which should not be found in the output.  For
7595  instance, if an Autoconf @file{configure} script includes tokens such as  instance, if an Autoconf @file{configure} script includes tokens such as
7596  @samp{AC_DEFINE}, or @samp{dnl}, then most probably something went  @samp{AC_DEFINE}, or @samp{dnl}, then most probably something went
7597  wrong (typically a macro was not evaluated because of over quotation).  wrong (typically a macro was not evaluated because of overquotation).
7598    
7599  M4sugar forbids all the tokens matching @samp{^m4_} and @samp{^dnl$}.  M4sugar forbids all the tokens matching @samp{^m4_} and @samp{^dnl$}.
7600    
7601  @defmac m4_pattern_forbid (@var{pattern})  @defmac m4_pattern_forbid (@var{pattern})
7602  @msindex pattern_forbid  @msindex pattern_forbid
7603  Declare no token matching @var{pattern} must be found in the output.  Declare that no token matching @var{pattern} must be found in the output.
7604  Comments are not checked; this can be a problem if, for instance, you  Comments are not checked; this can be a problem if, for instance, you
7605  have some macro left unexpanded after an @samp{#include}.  No consensus  have some macro left unexpanded after an @samp{#include}.  No consensus
7606  is currently found in the Autoconf community, as some people consider it  is currently found in the Autoconf community, as some people consider it
7607  should be valid to name macros in comments (which doesn't makes sense to  should be valid to name macros in comments (which doesn't makes sense to
7608  the author of this documentation, as @samp{#}-comments should document  the author of this documentation, as @samp{#}-comments should document
7609  the output, not the input, documented vy @samp{dnl}-comments).  the output, not the input, documented by @samp{dnl} comments).
7610  @end defmac  @end defmac
7611    
7612  Of course, you might encounter exceptions to these generic rules, for  Of course, you might encounter exceptions to these generic rules, for
# Line 7620  Any token matching @var{pattern} is allo Line 7624  Any token matching @var{pattern} is allo
7624  @c FIXME: Eventually will become a chapter, as it is not related to  @c FIXME: Eventually will become a chapter, as it is not related to
7625  @c programming in M4 per se.  @c programming in M4 per se.
7626    
7627  M4sh, pronounce ``mash'', is aiming at producing portable Bourne shell  M4sh, pronounced ``mash'', is aiming at producing portable Bourne shell
7628  scripts.  This name was coined by Lars J. Aas, who notes thats,  scripts.  This name was coined by Lars J. Aas, who notes that,
7629  according to the Webster's Revised Unabridged Dictionary (1913):  according to the Webster's Revised Unabridged Dictionary (1913):
7630    
7631  @quotation  @quotation
# Line 7751  same convention (@pxref{Cache Variable N Line 7755  same convention (@pxref{Cache Variable N
7755  them).  them).
7756    
7757  The first word of the name after @samp{AC_} usually tells the category  The first word of the name after @samp{AC_} usually tells the category
7758  of feature being tested.  Here are the categories used in Autoconf for  of the feature being tested.  Here are the categories used in Autoconf for
7759  specific test macros, the kind of macro that you are more likely to  specific test macros, the kind of macro that you are more likely to
7760  write.  They are also used for cache variables, in all-lowercase.  Use  write.  They are also used for cache variables, in all-lowercase.  Use
7761  them where applicable; where they're not, invent your own categories.  them where applicable; where they're not, invent your own categories.
# Line 7808  when @command{configure} is run, see @re Line 7812  when @command{configure} is run, see @re
7812  @defmac AC_DIAGNOSE (@var{category}, @var{message})  @defmac AC_DIAGNOSE (@var{category}, @var{message})
7813  @acindex DIAGNOSE  @acindex DIAGNOSE
7814  Report @var{message} as a warning (or as an error if requested by the  Report @var{message} as a warning (or as an error if requested by the
7815  user) if it falls into the @var{category}.  You are encouraged to use  user) if warnings of the @var{category} are turned on.  You are encouraged to use
7816  standard categories, which currently include:  standard categories, which currently include:
7817    
7818  @table @samp  @table @samp
7819  @item all  @item all
7820  messages that don't fall into one of the following category.  Use of an  messages that don't fall into one of the following categories.  Use of an
7821  empty @var{category} is equivalent.  empty @var{category} is equivalent.
7822    
7823  @item cross  @item cross
# Line 8000  ad-hoc approaches are systematized.  Thi Line 8004  ad-hoc approaches are systematized.  Thi
8004  parts of Autoconf.  One result is that some of the macros are now  parts of Autoconf.  One result is that some of the macros are now
8005  considered @dfn{obsolete}; they still work, but are no longer considered  considered @dfn{obsolete}; they still work, but are no longer considered
8006  the best thing to do, hence they should be replaced with more modern  the best thing to do, hence they should be replaced with more modern
8007  macros.  Ideally, @command{autoupdate} should substitute the old macro calls  macros.  Ideally, @command{autoupdate} should replace the old macro calls
8008  with their modern implementation.  with their modern implementation.
8009    
8010  Autoconf provides a simple means to obsolete a macro.  Autoconf provides a simple means to obsolete a macro.
# Line 8024  The Autoconf macros follow a strict codi Line 8028  The Autoconf macros follow a strict codi
8028  follow this style, especially if you intend to distribute your macro,  follow this style, especially if you intend to distribute your macro,
8029  either by contributing it to Autoconf itself, or via other means.  either by contributing it to Autoconf itself, or via other means.
8030    
8031  The first requirement is to pay great attention to the quotation, for  The first requirement is to pay great attention to the quotation.  For
8032  more details, see @ref{Autoconf Language}, and @ref{M4 Quotation}.  more details, see @ref{Autoconf Language}, and @ref{M4 Quotation}.
8033    
8034  Do not try to invent new interfaces.  It is likely that there is a macro  Do not try to invent new interfaces.  It is likely that there is a macro
# Line 8115  m4_bpatsubst([$1], [$""]) Line 8119  m4_bpatsubst([$1], [$""])
8119  @end example  @end example
8120    
8121  @noindent  @noindent
8122  so that Emacsen do not open a endless ``string'' at the first quote.  so that Emacsen do not open an endless ``string'' at the first quote.
8123  For the same reasons, avoid:  For the same reasons, avoid:
8124    
8125  @example  @example
# Line 8146  use @samp{,}. Line 8150  use @samp{,}.
8150    
8151  @xref{Macro Definitions}, for details on how to define a macro.  If a  @xref{Macro Definitions}, for details on how to define a macro.  If a
8152  macro doesn't use @code{AC_REQUIRE} and it is expected to never be the  macro doesn't use @code{AC_REQUIRE} and it is expected to never be the
8153  object of an @code{AC_REQUIRE} directive, then use @code{define}.  In  object of an @code{AC_REQUIRE} directive, then use @code{m4_define}.  In
8154  case of doubt, use @code{AC_DEFUN}.  All the @code{AC_REQUIRE}  case of doubt, use @code{AC_DEFUN}.  All the @code{AC_REQUIRE}
8155  statements should be at the beginning of the macro, @code{dnl}'ed.  statements should be at the beginning of the macro, @code{dnl}'ed.
8156    
# Line 8213  and the new way: Line 8217  and the new way:
8217  # _AC_EMXOS2  # _AC_EMXOS2
8218  # ----------  # ----------
8219  # Check for EMX on OS/2.  # Check for EMX on OS/2.
8220  define([_AC_EMXOS2],  m4_define([_AC_EMXOS2],
8221  [AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2],  [AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2],
8222  [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])],  [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])],
8223                     [ac_cv_emxos2=yes],                     [ac_cv_emxos2=yes],
# Line 8322  cat $@{FOO=`bar`@} Line 8326  cat $@{FOO=`bar`@}
8326  @end example  @end example
8327    
8328  @item  @item
8329  beware that single builtin substitutions are not performed by a sub  beware that single builtin substitutions are not performed by a
8330  shell, hence their effect applies to the current shell!  @xref{Shell  subshell, hence their effect applies to the current shell!  @xref{Shell
8331  Substitutions}, item ``Command Substitution''.  Substitutions}, item ``Command Substitution''.
8332  @end itemize  @end itemize
8333    
# Line 8338  details. Line 8342  details.
8342  @item Bash 2.05 and later  @item Bash 2.05 and later
8343  @cindex Bash 2.05 and later  @cindex Bash 2.05 and later
8344  Versions 2.05 and later of @command{bash} use a different format for the  Versions 2.05 and later of @command{bash} use a different format for the
8345  output of the @command{set} builtin, designed to make evaluating this  output of the @command{set} builtin, designed to make evaluating its
8346  output easier.  However, this output is not compatible with earlier  output easier.  However, this output is not compatible with earlier
8347  versions of @command{bash} (or with many other shells, probably).  So if  versions of @command{bash} (or with many other shells, probably).  So if
8348  you use @command{bash} 2.05 or higher to execute @command{configure},  you use @command{bash} 2.05 or higher to execute @command{configure},
# Line 8394  So while most modern systems do have a s Line 8398  So while most modern systems do have a s
8398  @section Here-Documents  @section Here-Documents
8399    
8400  Don't rely on @samp{\} being preserved just because it has no special  Don't rely on @samp{\} being preserved just because it has no special
8401  meaning together with the next symbol.  in the native @command{/bin/sh}  meaning together with the next symbol.  In the native @command{/bin/sh}
8402  on OpenBSD 2.7 @samp{\"} expands to @samp{"} in here-documents with  on OpenBSD 2.7 @samp{\"} expands to @samp{"} in here-documents with
8403  unquoted delimiter.  As a general rule, if @samp{\\} expands to @samp{\}  unquoted delimiter.  As a general rule, if @samp{\\} expands to @samp{\}
8404  use @samp{\\} to get @samp{\}.  use @samp{\\} to get @samp{\}.
# Line 8455  A shell parses the whole @code{if}/@code Line 8459  A shell parses the whole @code{if}/@code
8459  temporary files for each here document in it.  Some shells create links  temporary files for each here document in it.  Some shells create links
8460  for such here-documents on every @code{fork}, so that the clean-up code  for such here-documents on every @code{fork}, so that the clean-up code
8461  they had installed correctly removes them.  It is creating the links  they had installed correctly removes them.  It is creating the links
8462  that the shell can take forever.  that can take the shell forever.
8463    
8464  Moving the tests out of the @code{if}/@code{fi}, or creating multiple  Moving the tests out of the @code{if}/@code{fi}, or creating multiple
8465  @code{if}/@code{fi} constructs, would improve the performance  @code{if}/@code{fi} constructs, would improve the performance
# Line 8477  arcane, use them for special purpose: Line 8481  arcane, use them for special purpose:
8481  4 --- used on the Kubota Titan.  4 --- used on the Kubota Titan.
8482  @end display  @end display
8483    
8484  Don't redirect several times the same file descriptor, as you are doomed  Don't redirect the same file descriptor several times, as you are doomed
8485  to failure under Ultrix.  to failure under Ultrix.
8486    
8487  @example  @example
# Line 8533  One workaround is to grep out uninterest Line 8537  One workaround is to grep out uninterest
8537  good ones@enddots{}  good ones@enddots{}
8538    
8539  Don't try to move/delete open files, such as in @samp{exec >foo; mv foo  Don't try to move/delete open files, such as in @samp{exec >foo; mv foo
8540  bar}, see @ref{Limitations of Builtins}, @command{mv} for more details.  bar}; see @ref{Limitations of Builtins}, @command{mv} for more details.
8541    
8542  @node File System Conventions  @node File System Conventions
8543  @section File System Conventions  @section File System Conventions
# Line 8849  test "$@{var+set@}" = set || var=@var{@{ Line 8853  test "$@{var+set@}" = set || var=@var{@{
8853  @cindex `@var{commands}`  @cindex `@var{commands}`
8854  @cindex Command Substitution  @cindex Command Substitution
8855  While in general it makes no sense, do not substitute a single builtin  While in general it makes no sense, do not substitute a single builtin
8856  with side effects as Ash 0.2, trying to optimize, does not fork a  with side effects, becauase Ash 0.2, trying to optimize, does not fork a
8857  sub-shell to perform the command.  subshell to perform the command.
8858    
8859  For instance, if you wanted to check that @command{cd} is silent, do not  For instance, if you wanted to check that @command{cd} is silent, do not
8860  use @samp{test -z "`cd /`"} because the following can happen:  use @samp{test -z "`cd /`"} because the following can happen:
# Line 9056  Most modern shells provide the current l Line 9060  Most modern shells provide the current l
9060  Its value is the line number of the beginning of the current command.  Its value is the line number of the beginning of the current command.
9061  Autoconf attempts to execute @command{configure} with a modern shell.  Autoconf attempts to execute @command{configure} with a modern shell.
9062  If no such shell is available, it attempts to implement @code{LINENO}  If no such shell is available, it attempts to implement @code{LINENO}
9063  with a Sed prepass that replaces the each instance of the string  with a Sed prepass that replaces each instance of the string
9064  @code{$LINENO} (not followed by an alphanumeric character) with the  @code{$LINENO} (not followed by an alphanumeric character) with the
9065  line's number.  line's number.
9066    
# Line 9142  $ @kbd{sed '=' <lineno |} Line 9146  $ @kbd{sed '=' <lineno |}
9146  @item NULLCMD  @item NULLCMD
9147  @evindex NULLCMD  @evindex NULLCMD
9148  When executing the command @samp{>foo}, @command{zsh} executes  When executing the command @samp{>foo}, @command{zsh} executes
9149  @samp{$NULLCMD >foo}.  The Bourne shell considers @code{NULLCMD} is  @samp{$NULLCMD >foo}.  The Bourne shell considers @code{NULLCMD} to be
9150  @samp{:}, while @command{zsh}, even in Bourne shell compatibility mode,  @samp{:}, while @command{zsh}, even in Bourne shell compatibility mode,
9151  sets @code{NULLCMD} to @samp{cat}.  If you forgot to set @code{NULLCMD},  sets @code{NULLCMD} to @samp{cat}.  If you forgot to set @code{NULLCMD},
9152  your script might be suspended waiting for data on its standard input.  your script might be suspended waiting for data on its standard input.
# Line 9207  variable or set it to @samp{;}. Line 9211  variable or set it to @samp{;}.
9211  @item RANDOM  @item RANDOM
9212  @evindex RANDOM  @evindex RANDOM
9213  Many shells provide @code{RANDOM}, a variable that returns a different  Many shells provide @code{RANDOM}, a variable that returns a different
9214  integer when used.  Most of the time, its value does not change when it  integer each time it is used.  Most of the time, its value does not change when it
9215  is not used, but on @sc{irix 6.5} the value changes all the time.  This  is not used, but on @sc{irix 6.5} the value changes all the time.  This
9216  can be observed by using @command{set}.  can be observed by using @command{set}.
9217  @end table  @end table
# Line 9218  can be observed by using @command{set}. Line 9222  can be observed by using @command{set}.
9222    
9223  No, no, we are serious: some shells do have limitations!  :)  No, no, we are serious: some shells do have limitations!  :)
9224    
9225  You should always keep in mind that any built-in or command may support  You should always keep in mind that any builtin or command may support
9226  options, and therefore have a very different behavior with arguments  options, and therefore have a very different behavior with arguments
9227  starting with a dash.  For instance, the innocent @samp{echo "$word"}  starting with a dash.  For instance, the innocent @samp{echo "$word"}
9228  can give unexpected results when @code{word} starts with a dash.  It is  can give unexpected results when @code{word} starts with a dash.  It is
# Line 9236  directory, you must use @samp{. ./foo}. Line 9240  directory, you must use @samp{. ./foo}.
9240    
9241  @item @command{!}  @item @command{!}
9242  @prindex @command{!}  @prindex @command{!}
9243  You can't use @command{!}, you'll have to rewrite your code.  You can't use @command{!}; you'll have to rewrite your code.
9244    
9245    
9246  @item @command{break}  @item @command{break}
9247  @c ------------------  @c ------------------
9248  @prindex @command{break}  @prindex @command{break}
9249  The use of @samp{break 2}, etcetera, is safe.  The use of @samp{break 2} etc. is safe.
9250    
9251    
9252  @item @command{cd}  @item @command{cd}
# Line 9294  bash-2.02$ @kbd{case /tmp in [\\/]*) ech Line 9298  bash-2.02$ @kbd{case /tmp in [\\/]*) ech
9298  OK  OK
9299  @end example  @end example
9300    
9301  Some shells, such as Ash 0.3.8, are confused by empty  Some shells, such as Ash 0.3.8, are confused by an empty
9302  @code{case}/@code{esac}:  @code{case}/@code{esac}:
9303    
9304  @example  @example
# Line 9322  which are not aiming at portability shou Line 9326  which are not aiming at portability shou
9326  @samp{echo}.  @samp{echo}.
9327    
9328  Don't expect any option.  @xref{Preset Output Variables}, @code{ECHO_N}  Don't expect any option.  @xref{Preset Output Variables}, @code{ECHO_N}
9329  etc.@: for a means to simulate @option{-c}.  etc.@: for a means to simulate @option{-n}.
9330    
9331  Do not use backslashes in the arguments, as there is no consensus on  Do not use backslashes in the arguments, as there is no consensus on
9332  their handling.  On @samp{echo '\n' | wc -l}, the @command{sh} of  their handling.  On @samp{echo '\n' | wc -l}, the @command{sh} of
9333  Digital Unix 4.0, @sc{mips risc/os} 4.52, answer 2, but the Solaris'  Digital Unix 4.0 and @sc{mips risc/os} 4.52, answer 2, but the Solaris'
9334  @command{sh}, Bash and Zsh (in @command{sh} emulation mode) report 1.  @command{sh}, Bash, and Zsh (in @command{sh} emulation mode) report 1.
9335  Please note that the problem is truly @command{echo}: all the shells  Please note that the problem is truly @command{echo}: all the shells
9336  understand @samp{'\n'} as the string composed of a backslash and an  understand @samp{'\n'} as the string composed of a backslash and an
9337  @samp{n}.  @samp{n}.
# Line 9369  nonzero status, the trap also exits with Line 9373  nonzero status, the trap also exits with
9373  invoker can tell that an error occurred.  invoker can tell that an error occurred.
9374    
9375  Unfortunately, in some shells, such as Solaris 8 @command{sh}, an exit  Unfortunately, in some shells, such as Solaris 8 @command{sh}, an exit
9376  trap ignores the @code{exit} command's status.  In these shells, a trap  trap ignores the @code{exit} command's argument.  In these shells, a trap
9377  cannot determine whether it was invoked by plain @code{exit} or by  cannot determine whether it was invoked by plain @code{exit} or by
9378  @code{exit 1}.  Instead of calling @code{exit} directly, use the  @code{exit 1}.  Instead of calling @code{exit} directly, use the
9379  @code{AC_MSG_ERROR} macro that has a workaround for this problem.  @code{AC_MSG_ERROR} macro that has a workaround for this problem.
# Line 9378  cannot determine whether it was invoked Line 9382  cannot determine whether it was invoked
9382  @item @command{export}  @item @command{export}
9383  @c -------------------  @c -------------------
9384  @prindex @command{export}  @prindex @command{export}
9385  The builtin @command{export} dubs @dfn{environment variable} a shell  The builtin @command{export} dubs a shell variable @dfn{environment
9386  variable.  Each update of exported variables corresponds to an update of  variable}.  Each update of exported variables corresponds to an update
9387  the environment variables.  Conversely, each environment variable  of the environment variables.  Conversely, each environment variable
9388  received by the shell when it is launched should be imported as a shell  received by the shell when it is launched should be imported as a shell
9389  variable marked as exported.  variable marked as exported.
9390    
9391  Alas, many shells, such as Solaris 2.5, IRIX 6.3, IRIX 5.2, AIX 4.1.5  Alas, many shells, such as Solaris 2.5, IRIX 6.3, IRIX 5.2, AIX 4.1.5,
9392  and DU 4.0, forget to @command{export} the environment variables they  and DU 4.0, forget to @command{export} the environment variables they
9393  receive.  As a result, two variables are coexisting: the environment  receive.  As a result, two variables are coexisting: the environment
9394  variable and the shell variable.  The following code demonstrates this  variable and the shell variable.  The following code demonstrates this
# Line 9411  that you update. Line 9415  that you update.
9415  @c ------------------  @c ------------------
9416  @prindex @command{false}  @prindex @command{false}
9417  Don't expect @command{false} to exit with status 1: in the native Bourne  Don't expect @command{false} to exit with status 1: in the native Bourne
9418  shell of Solaris 8, it exits with status 255.  shell of Solaris 8 it exits with status 255.
9419    
9420    
9421  @item @command{for}  @item @command{for}
# Line 9447  done Line 9451  done
9451    
9452  @noindent  @noindent
9453  But keep in mind that Zsh, even in Bourne shell emulation mode, performs  But keep in mind that Zsh, even in Bourne shell emulation mode, performs
9454  word splitting on @samp{$@{1+"$@@"@}}, see @ref{Shell Substitutions},  word splitting on @samp{$@{1+"$@@"@}}; see @ref{Shell Substitutions},
9455  item @samp{$@@}, for more.  item @samp{$@@}, for more.
9456    
9457    
# Line 9535  Also please see the discussion of the @c Line 9539  Also please see the discussion of the @c
9539  @prindex @command{set}  @prindex @command{set}
9540  This builtin faces the usual problem with arguments starting with a  This builtin faces the usual problem with arguments starting with a
9541  dash.  Modern shells such as Bash or Zsh understand @option{--} to specify  dash.  Modern shells such as Bash or Zsh understand @option{--} to specify
9542  the end of the options (any argument after @option{--} is a parameters,  the end of the options (any argument after @option{--} is a parameter,
9543  even @samp{-x} for instance), but most shells simply stop the option  even @samp{-x} for instance), but most shells simply stop the option
9544  processing as soon as a non-option argument is found.  Therefore, use  processing as soon as a non-option argument is found.  Therefore, use
9545  @samp{dummy} or simply @samp{x} to end the option processing, and use  @samp{dummy} or simply @samp{x} to end the option processing, and use
# Line 9606  start with a dash, since @code{test} mig Line 9610  start with a dash, since @code{test} mig
9610  option (e.g., @samp{@var{string} = "-n"}).  option (e.g., @samp{@var{string} = "-n"}).
9611    
9612  Contrary to a common belief, @samp{test -n @var{string}} and @samp{test  Contrary to a common belief, @samp{test -n @var{string}} and @samp{test
9613  -z @var{string}} @strong{are} portable, nevertheless many shells (such  -z @var{string}} @strong{are} portable.  Nevertheless many shells (such
9614  as Solaris 2.5, AIX 3.2, UNICOS 10.0.0.6, Digital Unix 4 etc.) have  as Solaris 2.5, AIX 3.2, UNICOS 10.0.0.6, Digital Unix 4 etc.) have
9615  bizarre precedence and may be confused if @var{string} looks like an  bizarre precedence and may be confused if @var{string} looks like an
9616  operator:  operator:
# Line 9675  expr "x$ac_feature" : '.*[^-a-zA-Z0-9_]' Line 9679  expr "x$ac_feature" : '.*[^-a-zA-Z0-9_]'
9679  @item @command{trap}  @item @command{trap}
9680  @c -----------------  @c -----------------
9681  @prindex @command{trap}  @prindex @command{trap}
9682  It is safe to trap at least the signals 1, 2, 13 and 15.  You can also  It is safe to trap at least the signals 1, 2, 13, and 15.  You can also
9683  trap 0, i.e., have the @command{trap} run when the script ends (either via an  trap 0, i.e., have the @command{trap} run when the script ends (either via an
9684  explicit @command{exit}, or the end of the script).  explicit @command{exit}, or the end of the script).
9685    
# Line 9741  for @command{true}. Line 9745  for @command{true}.
9745  @item @command{unset}  @item @command{unset}
9746  @c ------------------  @c ------------------
9747  @prindex @command{unset}  @prindex @command{unset}
9748  You cannot assume the support of @command{unset}, nevertheless, because  You cannot assume the support of @command{unset}.  Nevertheless, because
9749  it is extremely useful to disable embarrassing variables such as  it is extremely useful to disable embarrassing variables such as
9750  @code{PS1}, you can test for its existence and use  @code{PS1}, you can test for its existence and use
9751  it @emph{provided} you give a neutralizing value when @command{unset} is  it @emph{provided} you give a neutralizing value when @command{unset} is
# Line 9771  include some limitations you should be a Line 9775  include some limitations you should be a
9775  @item @command{awk}  @item @command{awk}
9776  @c ----------------  @c ----------------
9777  @prindex @command{awk}  @prindex @command{awk}
9778  Don't leave white spaces before the parentheses in user functions calls,  Don't leave white spaces before the parentheses in user functions calls;
9779  @sc{gnu} awk will reject it:  @sc{gnu} awk will reject it:
9780    
9781  @example  @example
# Line 9882  kernel allows it then it happens.  If th Line 9886  kernel allows it then it happens.  If th
9886  it does not happen.  It is not something @command{cp} itself has control  it does not happen.  It is not something @command{cp} itself has control
9887  over.  over.
9888    
9889  In SysV any user can chown files to any other user, and also had a  In SysV any user can chown files to any other user, and SysV also had a
9890  non-sticky @file{/tmp}.  That undoubtedly derives from the heritage of  non-sticky @file{/tmp}.  That undoubtedly derives from the heritage of
9891  SysV in a business environment without hostile users.  BSD changed this  SysV in a business environment without hostile users.  BSD changed this
9892  to be a more secure model where only root can @command{chown} files, and  to be a more secure model where only root can @command{chown} files and
9893  used a sticky @file{/tmp}.  That undoubtedly derives from the heritage  a sticky @file{/tmp} is used.  That undoubtedly derives from the heritage
9894  of BSD in a campus environment.  of BSD in a campus environment.
9895    
9896  Linux by default follows BSD, but it can be configured to allow  Linux by default follows BSD, but it can be configured to allow
# Line 10111  doesn't exist) of @code{grep} to @file{/ Line 10115  doesn't exist) of @code{grep} to @file{/
10115  status of @code{grep} to determine whether it found a match.  status of @code{grep} to determine whether it found a match.
10116    
10117  Don't use multiple regexps with @option{-e}, as some @code{grep} will only  Don't use multiple regexps with @option{-e}, as some @code{grep} will only
10118  honor the last pattern (eg., IRIX 6.5 and Solaris 2.5.1).  Anyway,  honor the last pattern (e.g., IRIX 6.5 and Solaris 2.5.1).  Anyway,
10119  Stardent Vistra SVR4 @code{grep} lacks @option{-e}@dots{}  Instead, use  Stardent Vistra SVR4 @code{grep} lacks @option{-e}@dots{}  Instead, use
10120  extended regular expressions and alternation.  extended regular expressions and alternation.
10121    
# Line 10124  Don't rely on @command{ln} having a @opt Line 10128  Don't rely on @command{ln} having a @opt
10128  are not available on old systems; use @samp{$(LN_S)} as a portable substitute.  are not available on old systems; use @samp{$(LN_S)} as a portable substitute.
10129    
10130  For versions of the DJGPP before 2.04, @command{ln} emulates soft links  For versions of the DJGPP before 2.04, @command{ln} emulates soft links
10131  for executables by generating a stub that in turn calls the real  to executables by generating a stub that in turn calls the real
10132  program.  This feature also works with nonexistent files like in the  program.  This feature also works with nonexistent files like in the
10133  Unix spec.  So @samp{ln -s file link} will generate @file{link.exe},  Unix spec.  So @samp{ln -s file link} will generate @file{link.exe},
10134  which will attempt to call @file{file.exe} if run.  But this feature only  which will attempt to call @file{file.exe} if run.  But this feature only
# Line 10239  quite portable to modern hosts, but is n Line 10243  quite portable to modern hosts, but is n
10243    
10244  Of course the option @option{-e} is portable, but it is not needed.  No  Of course the option @option{-e} is portable, but it is not needed.  No
10245  valid Sed program can start with a dash, so it does not help  valid Sed program can start with a dash, so it does not help
10246  disambiguating.  Its sole usefulness is helping enforcing indenting as  disambiguating.  Its sole usefulness is to help enforcing indentation as
10247  in:  in:
10248    
10249  @example  @example
# Line 10323  d, and the output is produced.  When pro Line 10327  d, and the output is produced.  When pro
10327  still set (this is the bug).  Line a fails to match, but @command{sed}  still set (this is the bug).  Line a fails to match, but @command{sed}
10328  is not supposed to clear the t flag when a substitution fails.  Line b  is not supposed to clear the t flag when a substitution fails.  Line b
10329  sees that the flag is set, therefore it clears it, and jumps to d, hence  sees that the flag is set, therefore it clears it, and jumps to d, hence
10330  you get @samp{delete me} instead of @samp{deleted}.  When processing 3 t  you get @samp{delete me} instead of @samp{deleted}.  When processing 3, t
10331  is clear, a matches, so the flag is set, hence b clears the flags and  is clear, a matches, so the flag is set, hence b clears the flags and
10332  jumps.  Finally, since the flag is clear, 4 is processed properly.  jumps.  Finally, since the flag is clear, 4 is processed properly.
10333    
10334  There are two things one should remind about @samp{t} in @command{sed}.  There are two things one should remember about @samp{t} in @command{sed}.
10335  Firstly, always remember that @samp{t} jumps if @emph{some} substitution  Firstly, always remember that @samp{t} jumps if @emph{some} substitution
10336  succeeded, not only the immediately preceding substitution, therefore,  succeeded, not only the immediately preceding substitution.  Therefore,
10337  always use a fake @samp{t clear; : clear} to reset the t flag where  always use a fake @samp{t clear; : clear} to reset the t flag where
10338  indeed.  indeed.
10339    
# Line 10364  on SunOS 4.1.3 when the empty file is on Line 10368  on SunOS 4.1.3 when the empty file is on
10368  @section Limitations of Make  @section Limitations of Make
10369    
10370  @command{make} itself suffers a great number of limitations, only a few  @command{make} itself suffers a great number of limitations, only a few
10371  of which being listed here.  First of all, remember that since commands  of which are listed here.  First of all, remember that since commands
10372  are executed by the shell, all its weaknesses are inherited@enddots{}  are executed by the shell, all its weaknesses are inherited@enddots{}
10373    
10374  @table @asis  @table @asis
# Line 10445  Fatal errors encountered -- cannot conti Line 10449  Fatal errors encountered -- cannot conti
10449  @end example  @end example
10450    
10451  @noindent  @noindent
10452  Therefore, if you want to comment a multi-line definition, prefix each  Therefore, if you want to comment out a multi-line definition, prefix each
10453  line with @code{#}, not only the first.  line with @code{#}, not only the first.
10454    
10455  @example  @example
# Line 10459  line with @code{#}, not only the first. Line 10463  line with @code{#}, not only the first.
10463  A command-line variable definition such as @code{foo=bar} overrides any  A command-line variable definition such as @code{foo=bar} overrides any
10464  definition of @code{foo} in the @file{Makefile}.  Some @command{make}  definition of @code{foo} in the @file{Makefile}.  Some @command{make}
10465  implementations (such as @sc{gnu} @command{make}) will propagate this  implementations (such as @sc{gnu} @command{make}) will propagate this
10466  override to sub-invocations of @command{make}, this is allowed but not  override to sub-invocations of @command{make}.  This is allowed but not
10467  required by @sc{posix}.  required by @sc{posix}.
10468    
10469  @example  @example
# Line 10522  you do that. Line 10526  you do that.
10526    
10527  @sc{posix}-compliant @command{make}s internally use the @code{$(SHELL)}  @sc{posix}-compliant @command{make}s internally use the @code{$(SHELL)}
10528  macro to spawn shell processes and execute @file{Makefile} rules.  This  macro to spawn shell processes and execute @file{Makefile} rules.  This
10529  is a built-in macro supplied by @command{make}, but it can be modified  is a builtin macro supplied by @command{make}, but it can be modified
10530  from the @file{Makefile} or a command-line argument.  from the @file{Makefile} or a command-line argument.
10531    
10532  Not all @command{make}s will define this @code{SHELL} macro.  OSF/Tru64  Not all @command{make}s will define this @code{SHELL} macro.  OSF/Tru64
# Line 10651  you can reproduce this, please send us a Line 10655  you can reproduce this, please send us a
10655  @cindex suffix rules, @code{$<}, and @code{VPATH}  @cindex suffix rules, @code{$<}, and @code{VPATH}
10656  @cindex @code{$<}, inference rules, and @code{VPATH}  @cindex @code{$<}, inference rules, and @code{VPATH}
10657  @cindex @code{VPATH}, inference rules, and @code{$<}  @cindex @code{VPATH}, inference rules, and @code{$<}
10658  An implementation of @command{make} would not prefix @code{$<} if this  One implementation of @command{make} would not prefix @code{$<} if this
10659  prerequisite has been found in a @code{VPATH} dir.  This means that  prerequisite has been found in a @code{VPATH} dir.  This means that
10660    
10661  @example  @example
# Line 10765  install-HEADERS: $(HEADERS) Line 10769  install-HEADERS: $(HEADERS)
10769          done          done
10770  @end example  @end example
10771    
10772  The above @code{install-HEADERS} rule is not sun-proof because @code{for  The above @code{install-HEADERS} rule is not SunOS-proof because @code{for
10773  i in $(HEADERS);} will be expanded as @code{for i in foo.h foo2.h foo3.h;}  i in $(HEADERS);} will be expanded as @code{for i in foo.h foo2.h foo3.h;}
10774  where @code{foo.h} and @code{foo2.h} are plain words and are hence  where @code{foo.h} and @code{foo2.h} are plain words and are hence
10775  subject to @code{VPATH} adjustments.  subject to @code{VPATH} adjustments.
# Line 11039  example, @samp{decstation} can be used i Line 11043  example, @samp{decstation} can be used i
11043  @command{config.sub} to canonicalize system type aliases.  @command{config.sub} to canonicalize system type aliases.
11044    
11045  This section deliberately omits the description of the obsolete  This section deliberately omits the description of the obsolete
11046  interface, see @ref{Hosts and Cross-Compilation}.  interface; see @ref{Hosts and Cross-Compilation}.
11047    
11048    
11049  @node Canonicalizing  @node Canonicalizing
# Line 11116  otherwise it defaults to @code{host}. Line 11120  otherwise it defaults to @code{host}.
11120  @end defmac  @end defmac
11121    
11122  Note that there can be artifacts due to the backward compatibility  Note that there can be artifacts due to the backward compatibility
11123  code.  @xref{Hosts and Cross-Compilation}, for more.  code.  See @xref{Hosts and Cross-Compilation}, for more.
11124    
11125  @node Using System Type  @node Using System Type
11126  @section Using the System Type  @section Using the System Type
# Line 11260  looks like this: Line 11264  looks like this:
11264  @noindent  @noindent
11265  @var{help-string} may be more than one line long, if more detail is  @var{help-string} may be more than one line long, if more detail is
11266  needed.  Just make sure the columns line up in @samp{configure --help}.  needed.  Just make sure the columns line up in @samp{configure --help}.
11267  Avoid tabs in the help string.  You'll need to enclose it in @samp{[}  Avoid tabs in the help string.  You'll need to enclose the help string in @samp{[}
11268  and @samp{]} in order to produce the leading spaces.  and @samp{]} in order to produce the leading spaces.
11269    
11270  You should format your @var{help-string} with the macro  You should format your @var{help-string} with the macro
# Line 11408  edited @emph{only by users}, not by prog Line 11412  edited @emph{only by users}, not by prog
11412  can either be based on the @code{prefix} variable, or be a standard  can either be based on the @code{prefix} variable, or be a standard
11413  location such as the user's home directory.  It could even be specified  location such as the user's home directory.  It could even be specified
11414  by an environment variable.  The programs should examine that file at  by an environment variable.  The programs should examine that file at
11415  run time, rather than at compile time.  Run time configuration is more  run time, rather than at compile time.  Run-time configuration is more
11416  convenient for users and makes the configuration process simpler than  convenient for users and makes the configuration process simpler than
11417  getting the information while configuring.  @xref{Directory Variables,,  getting the information while configuring.  @xref{Directory Variables,,
11418  Variables for Installation Directories, standards, GNU Coding  Variables for Installation Directories, standards, GNU Coding
# Line 11580  in the site file if you specify it with Line 11584  in the site file if you specify it with
11584  environment variable.  environment variable.
11585    
11586  You can set some cache values in the site file itself.  Doing this is  You can set some cache values in the site file itself.  Doing this is
11587  useful if you are cross-compiling, so it is impossible to check features  useful if you are cross-compiling, where it is impossible to check features
11588  that require running a test program.  You could ``prime the cache'' by  that require running a test program.  You could ``prime the cache'' by
11589  setting those values correctly for that system in  setting those values correctly for that system in
11590  @file{@var{prefix}/etc/config.site}.  To find out the names of the cache  @file{@var{prefix}/etc/config.site}.  To find out the names of the cache
# Line 11619  fi Line 11623  fi
11623    
11624  @c ============================================== Running configure Scripts.  @c ============================================== Running configure Scripts.
11625    
11626  @node Running configure scripts  @node Running configure Scripts
11627  @chapter Running @command{configure} Scripts  @chapter Running @command{configure} Scripts
11628  @cindex @command{configure}  @cindex @command{configure}
11629    
# Line 11660  Synopsis: Line 11664  Synopsis:
11664  ./config.status @var{option}@dots{} [@var{file}@dots{}]  ./config.status @var{option}@dots{} [@var{file}@dots{}]
11665  @end example  @end example
11666    
11667  It configures the @var{files}, if none are specified, all the templates  It configures the @var{files}; if none are specified, all the templates
11668  are instantiated.  The files must be specified without their  are instantiated.  The files must be specified without their
11669  dependencies, as in  dependencies, as in
11670    
# Line 11681  The supported @var{option}s are: Line 11685  The supported @var{option}s are:
11685  @item --help  @item --help
11686  @itemx -h  @itemx -h
11687  Print a summary of the command line options, the list of the template  Print a summary of the command line options, the list of the template
11688  files and exit.  files, and exit.
11689    
11690  @item --version  @item --version
11691  @itemx -V  @itemx -V
# Line 11760  Makefile: Makefile.in config.status Line 11764  Makefile: Makefile.in config.status
11764  @end group  @end group
11765  @end example  @end example
11766    
11767  The calling convention of @file{config.status} has changed, see  The calling convention of @file{config.status} has changed; see
11768  @ref{Obsolete config.status Use}, for details.  @ref{Obsolete config.status Use}, for details.
11769    
11770    
# Line 11769  The calling convention of @file{config.s Line 11773  The calling convention of @file{config.s
11773  @node Obsolete Constructs  @node Obsolete Constructs
11774  @chapter Obsolete Constructs  @chapter Obsolete Constructs
11775    
11776  Autoconf changes, and throughout the years some constructs are obsoleted.  Autoconf changes, and throughout the years some constructs have been obsoleted.
11777  Most of the changes involve the macros, but the tools themselves, or  Most of the changes involve the macros, but in some cases the tools themselves, or
11778  even some concepts, are now considered obsolete.  even some concepts, are now considered obsolete.
11779    
11780  You may completely skip this chapter if you are new to Autoconf, its  You may completely skip this chapter if you are new to Autoconf.  Its
11781  intention is mainly to help maintainers updating their packages by  intention is mainly to help maintainers updating their packages by
11782  understanding how to move to more modern constructs.  understanding how to move to more modern constructs.
11783    
# Line 11790  understanding how to move to more modern Line 11794  understanding how to move to more modern
11794  @section Obsolete @file{config.status} Invocation  @section Obsolete @file{config.status} Invocation
11795    
11796  @file{config.status} now supports arguments to specify the files to  @file{config.status} now supports arguments to specify the files to
11797  instantiate, see @ref{config.status Invocation}, for more details.  instantiate; see @ref{config.status Invocation}, for more details.
11798  Before, environment variables had to be used.  Before, environment variables had to be used.
11799    
11800  @defvar CONFIG_COMMANDS  @defvar CONFIG_COMMANDS
# Line 11840  Makefile: Makefile.in config.status Line 11844  Makefile: Makefile.in config.status
11844    
11845  @noindent  @noindent
11846  (If @file{configure.ac} does not call @code{AC_CONFIG_HEADERS}, there is  (If @file{configure.ac} does not call @code{AC_CONFIG_HEADERS}, there is
11847  no need to set @code{CONFIG_HEADERS} in the @code{make} rules, equally  no need to set @code{CONFIG_HEADERS} in the @code{make} rules.  Equally
11848  for @code{CONFIG_COMMANDS} etc.)  for @code{CONFIG_COMMANDS} etc.)
11849    
11850    
# Line 11855  In order to produce @file{config.h.in}, Line 11859  In order to produce @file{config.h.in},
11859  build or to find templates for each symbol.  Modern releases of Autoconf  build or to find templates for each symbol.  Modern releases of Autoconf
11860  use @code{AH_VERBATIM} and @code{AH_TEMPLATE} (@pxref{Autoheader  use @code{AH_VERBATIM} and @code{AH_TEMPLATE} (@pxref{Autoheader
11861  Macros}), but in older releases a file, @file{acconfig.h}, contained the  Macros}), but in older releases a file, @file{acconfig.h}, contained the
11862  list of needed templates.  @command{autoheader} copies comments and  list of needed templates.  @command{autoheader} copied comments and
11863  @code{#define} and @code{#undef} statements from @file{acconfig.h} in  @code{#define} and @code{#undef} statements from @file{acconfig.h} in
11864  the current directory, if present.  This file used to be mandatory if  the current directory, if present.  This file used to be mandatory if
11865  you @code{AC_DEFINE} any additional symbols.  you @code{AC_DEFINE} any additional symbols.
# Line 11891  configure.ac --.   .------> autoconf* -- Line 11895  configure.ac --.   .------> autoconf* --
11895  @end group  @end group
11896  @end example  @end example
11897    
11898  Use only the @code{AH_} macros, @file{configure.ac} should be  Using only the @code{AH_} macros, @file{configure.ac} should be
11899  self-contained, and should not depend upon @file{acconfig.h} etc.  self-contained, and should not depend upon @file{acconfig.h} etc.
11900    
11901    
# Line 11958  should be avoided. Line 11962  should be avoided.
11962  During the jump from Autoconf version 1 to version 2, most of the  During the jump from Autoconf version 1 to version 2, most of the
11963  macros were renamed to use a more uniform and descriptive naming scheme,  macros were renamed to use a more uniform and descriptive naming scheme,
11964  but their signature did not change.  @xref{Macro Names}, for a  but their signature did not change.  @xref{Macro Names}, for a
11965  description of the new naming scheme.  Below, there is just the mapping  description of the new naming scheme.  Below, if there is just the mapping
11966  from old names to new names for these macros, the reader is invited to  from old names to new names for these macros, the reader is invited to
11967  refer to the definition of the new macro for the signature and the  refer to the definition of the new macro for the signature and the
11968  description.  description.
# Line 12000  other macros. Line 12004  other macros.
12004  Autoconf, up to 2.13, used to provide this version of  Autoconf, up to 2.13, used to provide this version of
12005  @code{AC_CHECK_TYPE}, deprecated because of its flaws.  Firstly, although  @code{AC_CHECK_TYPE}, deprecated because of its flaws.  Firstly, although
12006  it is a member of the @code{CHECK} clan, singular sub-family, it does  it is a member of the @code{CHECK} clan, singular sub-family, it does
12007  more than just checking.  Second, missing types are not  more than just checking.  Secondly, missing types are not
12008  @code{typedef}'d, they are @code{#define}'d, which can lead to  @code{typedef}'d, they are @code{#define}'d, which can lead to
12009  incompatible code in the case of pointer types.  incompatible code in the case of pointer types.
12010    
12011  This use of @code{AC_CHECK_TYPE} is obsolete and discouraged, see  This use of @code{AC_CHECK_TYPE} is obsolete and discouraged; see
12012  @ref{Generic Types}, for the description of the current macro.  @ref{Generic Types}, for the description of the current macro.
12013    
12014  If the type @var{type} is not defined, define it to be the C (or C++)  If the type @var{type} is not defined, define it to be the C (or C++)
12015  builtin type @var{default}; e.g., @samp{short} or @samp{unsigned}.  builtin type @var{default}, e.g., @samp{short} or @samp{unsigned}.
12016    
12017  This macro is equivalent to:  This macro is equivalent to:
12018    
# Line 12355  Use the generic macro @samp{AC_CHECK_SIZ Line 12359  Use the generic macro @samp{AC_CHECK_SIZ
12359  Used to define @code{NEED_MEMORY_H} if the @code{mem} functions were  Used to define @code{NEED_MEMORY_H} if the @code{mem} functions were
12360  defined in @file{memory.h}.  Today it is equivalent to  defined in @file{memory.h}.  Today it is equivalent to
12361  @samp{AC_CHECK_HEADERS(memory.h)}.  Adjust your code to depend upon  @samp{AC_CHECK_HEADERS(memory.h)}.  Adjust your code to depend upon
12362  @code{HAVE_MEMORY_H}, not @code{NEED_MEMORY_H}, see @ref{Standard  @code{HAVE_MEMORY_H}, not @code{NEED_MEMORY_H}; see @ref{Standard
12363  Symbols}.  Symbols}.
12364  @end defmac  @end defmac
12365    
# Line 12415  services to the user. Line 12419  services to the user.
12419    
12420  @defmac AC_OUTPUT (@ovar{file}@dots{}, @ovar{extra-cmds}, @ovar{init-cmds})  @defmac AC_OUTPUT (@ovar{file}@dots{}, @ovar{extra-cmds}, @ovar{init-cmds})
12421  @acindex OUTPUT  @acindex OUTPUT
12422  The use of @code{AC_OUTPUT} with argument is deprecated, this obsoleted  The use of @code{AC_OUTPUT} with argument is deprecated.  This obsoleted
12423  interface is equivalent to:  interface is equivalent to:
12424    
12425  @example  @example
# Line 12447  AC_OUTPUT_COMMANDS([echo this is another Line 12451  AC_OUTPUT_COMMANDS([echo this is another
12451    
12452  Aside from the fact that @code{AC_CONFIG_COMMANDS} requires an  Aside from the fact that @code{AC_CONFIG_COMMANDS} requires an
12453  additional key, an important difference is that  additional key, an important difference is that
12454  @code{AC_OUTPUT_COMMANDS} is quoting its arguments twice, while  @code{AC_OUTPUT_COMMANDS} is quoting its arguments twice, unlike
12455  @code{AC_CONFIG_COMMANDS}.  This means that @code{AC_CONFIG_COMMANDS}  @code{AC_CONFIG_COMMANDS}.  This means that @code{AC_CONFIG_COMMANDS}
12456  can safely be given macro calls as arguments:  can safely be given macro calls as arguments:
12457    
# Line 12456  AC_CONFIG_COMMANDS(foo, [my_FOO()]) Line 12460  AC_CONFIG_COMMANDS(foo, [my_FOO()])
12460  @end example  @end example
12461    
12462  @noindent  @noindent
12463  conversely, where one level of quoting was enough for literal strings  Conversely, where one level of quoting was enough for literal strings
12464  with @code{AC_OUTPUT_COMMANDS}, you need two with  with @code{AC_OUTPUT_COMMANDS}, you need two with
12465  @code{AC_CONFIG_COMMANDS}.  The following lines are equivalent:  @code{AC_CONFIG_COMMANDS}.  The following lines are equivalent:
12466    
# Line 12525  removed because of limited usefulness Line 12529  removed because of limited usefulness
12529    
12530  @defmac AC_RSH  @defmac AC_RSH
12531  @acindex RSH  @acindex RSH
12532  Removed because of limited usefulness.  removed because of limited usefulness
12533  @end defmac  @end defmac
12534    
12535  @defmac AC_SCO_INTL  @defmac AC_SCO_INTL
# Line 12539  AC_CHECK_LIB(intl, strftime, LIBS="-lint Line 12543  AC_CHECK_LIB(intl, strftime, LIBS="-lint
12543  @end example  @end example
12544    
12545  @noindent  @noindent
12546  now it just calls @code{AC_FUNC_STRFTIME} instead.  Now it just calls @code{AC_FUNC_STRFTIME} instead.
12547  @end defmac  @end defmac
12548    
12549  @defmac AC_SETVBUF_REVERSED  @defmac AC_SETVBUF_REVERSED
# Line 12649  Same as @samp{AC_CHECK_HEADERS(unistd.h) Line 12653  Same as @samp{AC_CHECK_HEADERS(unistd.h)
12653  @cvindex USG  @cvindex USG
12654  Define @code{USG} if the @sc{bsd} string functions are defined in  Define @code{USG} if the @sc{bsd} string functions are defined in
12655  @file{strings.h}.  You should no longer depend upon @code{USG}, but on  @file{strings.h}.  You should no longer depend upon @code{USG}, but on
12656  @code{HAVE_STRING_H}, see @ref{Standard Symbols}.  @code{HAVE_STRING_H}; see @ref{Standard Symbols}.
12657  @end defmac  @end defmac
12658    
12659  @defmac AC_UTIME_NULL  @defmac AC_UTIME_NULL
# Line 12661  Define @code{USG} if the @sc{bsd} string Line 12665  Define @code{USG} if the @sc{bsd} string
12665  @acindex VALIDATE_CACHED_SYSTEM_TUPLE  @acindex VALIDATE_CACHED_SYSTEM_TUPLE
12666  If the cache file is inconsistent with the current host, target and  If the cache file is inconsistent with the current host, target and
12667  build system types, it used to execute @var{cmd} or print a default  build system types, it used to execute @var{cmd} or print a default
12668  error message.  error message.  This is now handled by default.
   
 This is now handled by default.  
12669  @end defmac  @end defmac
12670    
12671  @defmac AC_VERBOSE (@var{result-description})  @defmac AC_VERBOSE (@var{result-description})
# Line 12808  Some macros have been superseded by simi Line 12810  Some macros have been superseded by simi
12810  but are not call-compatible.  If you get warnings about calling obsolete  but are not call-compatible.  If you get warnings about calling obsolete
12811  macros while running @command{autoconf}, you may safely ignore them, but  macros while running @command{autoconf}, you may safely ignore them, but
12812  your @command{configure} script will generally work better if you follow  your @command{configure} script will generally work better if you follow
12813  the advice it prints about what to replace the obsolete macros with.  In  the advice that is printed about what to replace the obsolete macros with.  In
12814  particular, the mechanism for reporting the results of tests has  particular, the mechanism for reporting the results of tests has
12815  changed.  If you were using @code{echo} or @code{AC_VERBOSE} (perhaps  changed.  If you were using @code{echo} or @code{AC_VERBOSE} (perhaps
12816  via @code{AC_COMPILE_CHECK}), your @command{configure} script's output will  via @code{AC_COMPILE_CHECK}), your @command{configure} script's output will
# Line 12870  backslashes before quotes, you need to r Line 12872  backslashes before quotes, you need to r
12872  predictably, and does not treat quotes (except back quotes) specially.  predictably, and does not treat quotes (except back quotes) specially.
12873  @xref{Setting Output Variables}.  @xref{Setting Output Variables}.
12874    
12875  All of the boolean shell variables set by Autoconf macros now use  All of the Boolean shell variables set by Autoconf macros now use
12876  @samp{yes} for the true value.  Most of them use @samp{no} for false,  @samp{yes} for the true value.  Most of them use @samp{no} for false,
12877  though for backward compatibility some use the empty string instead.  If  though for backward compatibility some use the empty string instead.  If
12878  you were relying on a shell variable being set to something like 1 or  you were relying on a shell variable being set to something like 1 or
# Line 12900  kludging.  Or perhaps not. Line 12902  kludging.  Or perhaps not.
12902    
12903  To speed up your locally written feature tests, add caching to them.  To speed up your locally written feature tests, add caching to them.
12904  See whether any of your tests are of general enough usefulness to  See whether any of your tests are of general enough usefulness to
12905  encapsulate into macros that you can share.  encapsulate them into macros that you can share.
12906    
12907    
12908  @node Autoconf 2.13  @node Autoconf 2.13
# Line 13013  versions of these macros, integrated in Line 13015  versions of these macros, integrated in
13015  instead of @code{AM_}.  But in order to ease the upgrading via  instead of @code{AM_}.  But in order to ease the upgrading via
13016  @command{autoupdate}, bindings to such @code{AM_} macros are provided.  @command{autoupdate}, bindings to such @code{AM_} macros are provided.
13017    
13018  Unfortunately Automake did not quote the name of these macros!  Unfortunately Automake did not quote the names of these macros!
13019  Therefore, when @command{m4} finds something like  Therefore, when @command{m4} finds something like
13020  @samp{AC_DEFUN(AM_TYPE_PTRDIFF_T, @dots{})} in @file{aclocal.m4},  @samp{AC_DEFUN(AM_TYPE_PTRDIFF_T, @dots{})} in @file{aclocal.m4},
13021  @code{AM_TYPE_PTRDIFF_T} is  @code{AM_TYPE_PTRDIFF_T} is
# Line 13038  Future versions of Automake will simply Line 13040  Future versions of Automake will simply
13040  macros, and will properly quote the names of the remaining macros.  macros, and will properly quote the names of the remaining macros.
13041  But you don't have to wait for it to happen to do the right thing right  But you don't have to wait for it to happen to do the right thing right
13042  now: do not depend upon macros from Automake as it is simply not its job  now: do not depend upon macros from Automake as it is simply not its job
13043  to provide macros (but the one it requires by itself):  to provide macros (but the one it requires itself):
13044    
13045  @example  @example
13046  $ @kbd{cat configure.in}  $ @kbd{cat configure.in}
# Line 13084  build, and build to the result of @comma Line 13086  build, and build to the result of @comma
13086  in order to ease the transition from 2.13 to 2.50, the following  in order to ease the transition from 2.13 to 2.50, the following
13087  transition scheme is implemented.  @emph{Do not rely on it}, as it will  transition scheme is implemented.  @emph{Do not rely on it}, as it will
13088  be completely disabled in a couple of releases (we cannot keep it, as it  be completely disabled in a couple of releases (we cannot keep it, as it
13089  proves to cause more problems than to cure).  proves to cause more problems than it cures).
13090    
13091  They all default to the result of running @command{config.guess}, unless  They all default to the result of running @command{config.guess}, unless
13092  you specify either @option{--build} or @option{--host}.  In this case,  you specify either @option{--build} or @option{--host}.  In this case,
# Line 13102  too. Line 13104  too.
13104    
13105  For backward compatibility, @command{configure} will accept a system  For backward compatibility, @command{configure} will accept a system
13106  type as an option by itself.  Such an option will override the defaults  type as an option by itself.  Such an option will override the defaults
13107  for build, host and target system types.  The following configure  for build, host, and target system types.  The following configure
13108  statement will configure a cross toolchain that will run on NetBSD/alpha  statement will configure a cross toolchain that will run on NetBSD/alpha
13109  but generate code for GNU Hurd/sparc, which is also the build platform.  but generate code for GNU Hurd/sparc, which is also the build platform.
13110    
# Line 13122  its contents is the same as that of @cod Line 13124  its contents is the same as that of @cod
13124  rely on this broken feature.  rely on this broken feature.
13125    
13126  For consistency with the backward compatibility scheme exposed above,  For consistency with the backward compatibility scheme exposed above,
13127  when @option{--host} is specified by @option{--build} isn't, the build  when @option{--host} is specified but @option{--build} isn't, the build
13128  system will be assumed to be the same as @option{--host}, and  system will be assumed to be the same as @option{--host}, and
13129  @samp{build_alias} will be set to that value.  Eventually, this  @samp{build_alias} will be set to that value.  Eventually, this
13130  historically incorrect behavior will go away.  historically incorrect behavior will go away.
# Line 13132  historically incorrect behavior will go Line 13134  historically incorrect behavior will go
13134  The former scheme to enable cross-compilation proved to cause more harm  The former scheme to enable cross-compilation proved to cause more harm
13135  than good, in particular, it used to be triggered too easily, leaving  than good, in particular, it used to be triggered too easily, leaving
13136  regular end users puzzled in front of cryptic error messages.  regular end users puzzled in front of cryptic error messages.
13137  @command{configure} could even enter cross-compilation mode, only  @command{configure} could even enter cross-compilation mode only
13138  because the compiler was not functional.  This is mainly because  because the compiler was not functional.  This is mainly because
13139  @command{configure} used to try to detect cross-compilation, instead of  @command{configure} used to try to detect cross-compilation, instead of
13140  waiting for an explicit flag from the user.  waiting for an explicit flag from the user.
13141    
13142  Now, @command{configure} enters cross-compilation mode iff  Now, @command{configure} enters cross-compilation mode if and only if
13143  @option{--host} is passed.  @option{--host} is passed.
13144    
13145  That's the short documentation.  To ease the transition between 2.13 and  That's the short documentation.  To ease the transition between 2.13 and
13146  its successors, a more complicated scheme is implemented.  @emph{Do not  its successors, a more complicated scheme is implemented.  @emph{Do not
13147  rely on the following}, as it will be removed in a near future.  rely on the following}, as it will be removed in the near future.
13148    
13149  If you specify @option{--host}, but not @option{--build}, when  If you specify @option{--host}, but not @option{--build}, when
13150  @command{configure} performs the first compiler test it will try to run  @command{configure} performs the first compiler test it will try to run
# Line 13212  AC_LIBOBJ([malloc]) Line 13214  AC_LIBOBJ([malloc])
13214  @cindex @code{$U}  @cindex @code{$U}
13215  When asked for automatic de-ANSI-fication, Automake needs  When asked for automatic de-ANSI-fication, Automake needs
13216  @code{LIBOBJS}'ed filenames to have @samp{$U} appended to the base  @code{LIBOBJS}'ed filenames to have @samp{$U} appended to the base
13217  names.  Libtool requires the definition of @code{LTLIBOBJS}, which  names.  Libtool requires the definition of @code{LTLIBOBJS}, whose
13218  suffixes are mapped to @samp{.lo}.  People used to run snippets such as:  suffixes are mapped to @samp{.lo}.  People used to run snippets such as:
13219    
13220  @example  @example

Legend:
Removed from v.1.674  
changed lines
  Added in v.1.675

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26