Index: autoconf.texi =================================================================== RCS file: /cvs/autoconf/doc/autoconf.texi,v retrieving revision 1.437 diff -u -r1.437 autoconf.texi --- autoconf.texi 2001/03/30 12:50:29 1.437 +++ autoconf.texi 2001/03/31 19:06:59 @@ -614,10 +614,11 @@ for more information). Previous versions of Autoconf promoted the name @file{configure.in}, -which is somewhat ambiguous (the tool needed to proceed this file is not -given by the extension), and introduces a slight confusion with address@hidden and so on, for which @samp{.in} means ``to be -processed by @code{configure}''. Using @file{configure.ac} is now preferred. +which is somewhat ambiguous (the tool needed to produce this file is not +described by its extension), and introduces a slight confusion with address@hidden and so on (for which @samp{.in} means ``to be +processed by @code{configure}''). Using @file{configure.ac} is now +preferred. @menu * Shell Script Compiler:: Autoconf as solution of a problem @@ -628,66 +629,67 @@ @node Shell Script Compiler, Autoconf Language, Writing configure.ac, Writing configure.ac @subsection A Shell Script Compiler -Like for any other language, to properly program in Autoconf, i.e., the -language in which you write @file{configure.ac}, you must understand address@hidden is the problem it tries to answer, and @emph{how} it does. +Just as for any other computer language, in order to properly program address@hidden in Autoconf you must understand @emph{what} problem +the language tries to address and @emph{how} it does so. -The problem Autoconf addresses is that the world is a mess: after all, +The problem Autoconf addresses is that the world is a mess. After all, you are using Autoconf in order to have your package compile easily on -all sort of different systems, some of them being extremely hostile. -But Autoconf itself suffers from these differences: @code{configure} -must run on all those systems, hence @code{configure} must use the -least common divisor between all supported system. - -Naturally, you orient yourself towards shell scripts. And in fact, -there is not even the need for a tool like @code{autoconf}: a set of -properly written shell functions is way enough to make it easy to write address@hidden scripts by hand. Sigh! Unfortunately, shell functions -do not belong to the least common divisor, therefore, where you'd define -a function and use it ten times, you need to write ten times its body. - -Therefore, what is really needed is some kind of compiler, address@hidden, which takes an Autoconf program, @file{configure.ac}, -and transform it in a portable shell script, @code{configure}. +all sorts of different systems, some of them being extremely hostile. +Autoconf itself bears the price for these differences: @code{configure} +must run on all those systems, and thus @code{configure} must limit itself +to their lowest common denominator of features. + +Naturally, you might then think of shell scripts; who needs address@hidden A set of properly written shell functions is enough to +make it easy to write @code{configure} scripts by hand. Sigh! +Unfortunately, shell functions do not belong to the least common +denominator; therefore, where you would like to define a function and +use it ten times, you would instead need to copy its body ten times. + +So, what is really needed is some kind of compiler, @code{autoconf}, +that takes an Autoconf program, @file{configure.ac}, and transforms it +into a portable shell script, @code{configure}. How does @code{autoconf} perform this task? -Two obvious solutions: creating a brand new language, or extending an -existing one. The former option is very attractive: all sort of -optimizations could easily be implemented in the compiler, many rigorous -checks could be performed on the Autoconf program, and in particular, it -would be extremely easy to reject any non portable construct etc. -Alternatively, you can extend an existing language, of course, the address@hidden language. - -Autoconf does the latter: it is an layer on top of @code{sh}. Quite -naturally then, it has been chosen to implement @code{autoconf} as a -macro expander, i.e., a program that takes a text in input and -repeatedly performs @dfn{macro expansions}, repeatedly replaces macro -uses with macro bodies. Instead of implementing a dedicated Autoconf -macro expander, it is natural to use an existing general purpose macro -expander, such as M4, and implement the extensions as a set of M4 -macros. +There are two obvious possibilities: creating a brand new language or +extending an existing one. The former option is very attractive: all +sorts of optimizations could easily be implemented in the compiler and +many rigorous checks could be performed on the Autoconf program +(e.g. rejecting any non-portable construct). Alternatively, you can +extend an existing language, such as the @code{sh} (Bourne shell) +language. + +Autoconf does the latter: it is a layer on top of @code{sh}. It was +therefore most convenient to implement @code{autoconf} as a macro +expander: a program that repeatedly performs @dfn{macro expansions} on +text input, replacing macro calls with macro bodies and producing a pure address@hidden script in the end. Instead of implementing a dedicated +Autoconf macro expander, it is natural to use an existing +general-purpose macro language, such as M4, and implement the extensions +as a set of M4 macros. @node Autoconf Language, configure.ac Layout, Shell Script Compiler, Writing configure.ac @subsection The Autoconf Language @cindex quotation -The Autoconf language is very different from usual languages because you -handle actual code just as plain text. Where in C for instance, data -and instructions have very different syntactic status, in Autoconf their -status is rigorously the same. Therefore we need a means to distinguish -literal strings from text to be expanded: quotation. +The Autoconf language is very different from many other computer +languages because it treats actual code the same as plain text. Whereas +in C, for instance, data and instructions have very different syntactic +status, in Autoconf their status is rigorously the same. Therefore, we +need a means to distinguish literal strings from text to be expanded: +quotation. When calling macros that take arguments, there must not be any blank space between the macro name and the open parenthesis. Arguments should -be enclosed within the M4 quote characters @samp{[} and @samp{]}, and -are separated by a comma. Any leading spaces in arguments are ignored, +be enclosed within the M4 quote characters @samp{[} and @samp{]}, and be +separated by commas. Any leading spaces in arguments are ignored, unless they are quoted. You may safely leave out the quotes when the argument is simple text, but @emph{always} quote complex arguments such -as other macro calls. This rule recursively applies for each macro -call, including macro called from other macros. +as other macro calls. This rule applies recursively for every macro +call, including macros called from other macros. For instance: @@ -698,7 +700,7 @@ @end example @noindent -is perfectly quoted. You may safely simplify quotation to +is quoted properly. You may safely simplify its quotation to: @example AC_CHECK_HEADER(stdio.h, @@ -707,8 +709,8 @@ @end example @noindent -Notice that the argument of @code{AC_MSG_ERROR} is still quoted, -otherwise its comma would have been understood as an argument separator. +Notice that the argument of @code{AC_MSG_ERROR} is still quoted; +otherwise, its comma would have been interpreted as an argument separator. The following example is wrong and dangerous, as it is underquoted: @@ -718,8 +720,9 @@ AC_MSG_ERROR([Sorry, can't do anything for you])) @end example -You may have to use text that also resembles a macro call. In this -case, you must quote this text at top level: +In other cases, you may have to use text that also resembles a macro +call. You must quote that text even when it is not passed as a macro +argument: @example echo "Hard rock was here! --[AC_DC]" @@ -733,17 +736,18 @@ @end example @noindent -in @code{configure}. Since there is an additional quoting level for each -macro invocation, this results in @emph{double quoting all the literal -strings}: +When you use the same text in a macro argument, you must therefore have +an extra quotation level (since one is stripped away by the macro +substitution). In general, then, it is a good idea to @emph{use double +quoting for all literal string arguments}: @example AC_MSG_WARN([[AC_DC stinks --Iron Maiden]]) @end example You are now able to understand one of the constructs of Autoconf that -has continuously been misunderstood... The rule of thumb is that address@hidden you expect macro expansion, expect quote expansion}, +has been continually misunderstood... The rule of thumb is that address@hidden you expect macro expansion, expect quote expansion}; i.e., expect one level of quotes to be lost. For instance @example @@ -751,32 +755,30 @@ @end example @noindent -is incorrect: here the first argument of @code{AC_COMPILE_IFELSE}, is address@hidden b[10];}, and it will be expanded once, which results in address@hidden b10;}. There was a idiom developed in the Autoconf world to -address this issue, based on the M4 @code{changequote} primitive, but do -not use it! Let's take a closer look: the author meant the first -argument to be understood as a literal, and therefore it must be quoted -twice: +is incorrect: here, the first argument of @code{AC_COMPILE_IFELSE} is address@hidden b[10];} and will be expanded once, which results in address@hidden b10;}. (There was a idiom common in Autoconf's past to +address this issue via the M4 @code{changequote} primitive, but do not +use it!) Let's take a closer look: the author meant the first argument +to be understood as a literal, and therefore it must be quoted twice: @example AC_COMPILE_IFELSE([[char b[10];]],, [AC_MSG_ERROR([you lose])]) @end example @noindent -and address@hidden You really produced @samp{char b[10];}. address@hidden, you actually produce @samp{char b[10];} this time! -The careful reader will note that the so-called perfectly quoted address@hidden example above is actually lacking three pairs of -quotes! Nevertheless, for sake of readability, double quotation of -literals is used only where needed. +The careful reader will notice that, according to these guidelines, the +"properly" quoted @code{AC_CHECK_HEADER} example above is actually +lacking three pairs of quotes! Nevertheless, for the sake of readability, +double quotation of literals is used only where needed in this manual. - Some macros take optional arguments, which this documentation represents address@hidden (not to be confounded with the quote characters). You may -just leave them empty, or use @samp{[]} to make explicit the emptiness -of the argument. Finally you may simply leave out the trailing commas. -The three lines below are equivalent: +as @ovar{arg} (not to be confused with the quote characters). You may +just leave them empty, or use @samp{[]} to make the emptiness of the +argument explicit, or you may simply omit the trailing commas. The +three lines below are equivalent: @example AC_CHECK_HEADERS(stdio.h, [], []) @@ -800,6 +802,8 @@ # Process this file with autoconf to produce a configure script. @end example +Such comments will be included in the generated @file{configure} script. + @node configure.ac Layout, , Autoconf Language, Writing configure.ac @subsection Standard @file{configure.ac} Layout @@ -810,13 +814,13 @@ rely on other macros having been called first, because they check previously set values of some variables to decide what to do. These macros are noted in the individual descriptions (@pxref{Existing -Tests}), and they also warn you when creating @code{configure} if they +Tests}), and they also warn you when @code{configure} is created if they are called out of order. To encourage consistency, here is a suggested order for calling the Autoconf macros. Generally speaking, the things near the end of this -list could depend on things earlier in it. For example, library -functions could be affected by types and libraries. +list are those that could depend on things earlier in it. For example, +library functions could be affected by types and libraries. @display @group @@ -851,7 +855,7 @@ You should manually examine @file{configure.scan} before renaming it to @file{configure.ac}; it will probably need some adjustments. -Occasionally @code{autoscan} outputs a macro in the wrong order relative +Occasionally, @code{autoscan} outputs a macro in the wrong order relative to another macro, so that @code{autoconf} produces a warning; you need to move such macros manually. Also, if you want the package to use a configuration header file, you must add a call to @@ -860,12 +864,12 @@ order to make it work with Autoconf (@pxref{ifnames Invocation}, for information about a program that can help with that job). address@hidden uses several data files, which are installed along with the -distributed Autoconf macro files, to determine which macros to output -when it finds particular symbols in a package's source files. These -files all have the same format. Each line consists of a symbol, -whitespace, and the Autoconf macro to output if that symbol is -encountered. Lines starting with @samp{#} are comments. address@hidden uses several data files (installed along with Autoconf) +to determine which macros to output when it finds particular symbols in +a package's source files. These data files all have the same format: +each line consists of a symbol, whitespace, and the Autoconf macro to +output if that symbol is encountered. Lines starting with @samp{#} are +comments. @code{autoscan} is only installed if you already have Perl installed. @code{autoscan} accepts the following options: @@ -887,24 +891,24 @@ @item address@hidden @itemx -A @var{dir} @evindex AC_MACRODIR -Overwrite the location where Autoconf files were installed. You can -also set the @code{AC_MACRODIR} environment variable to a directory; -this option overrides the environment variable. +Override the location where the installed Autoconf data files are looked +for. You can also set the @code{AC_MACRODIR} environment variable to a +directory; this option overrides the environment variable. -This option is rarely needed and dangerous: only when you play with -different versions of Autoconf. +This option is rarely needed and dangerous; it is only used when one +plays with different versions of Autoconf simultaneously. @end table @node ifnames Invocation, autoconf Invocation, autoscan Invocation, Making configure Scripts @section Using @code{ifnames} to List Conditionals @cindex @code{ifnames} address@hidden can help when writing a @file{configure.ac} for a -software package. It prints the identifiers that the package already -uses in C preprocessor conditionals. If a package has already been set -up to have some portability, this program can help you figure out what -its @code{configure} needs to check for. It may help fill in some gaps -in a @file{configure.ac} generated by @code{autoscan} (@pxref{autoscan address@hidden can help you write @file{configure.ac} for a software +package. It prints the identifiers that the package already uses in C +preprocessor conditionals. If a package has already been set up to have +some portability, @code{ifnames} can thus help you figure out what its address@hidden needs to check for. It may help fill in some gaps in a address@hidden generated by @code{autoscan} (@pxref{autoscan Invocation}). @code{ifnames} scans all of the C source files named on the command line @@ -937,9 +941,9 @@ Autoconf macros. If you give @code{autoconf} an argument, it reads that file instead of @file{configure.ac} and writes the configuration script to the standard output instead of to @code{configure}. If you give address@hidden the argument @option{-}, it reads the standard input -instead of @file{configure.ac} and writes the configuration script on -the standard output. address@hidden the argument @option{-}, it reads from the standard +input instead of @file{configure.ac} and writes the configuration script +to the standard output. The Autoconf macros are defined in several files. Some of the files are distributed with Autoconf; @code{autoconf} reads them first. Then it @@ -973,12 +977,12 @@ @item address@hidden @itemx -A @var{dir} @evindex AC_MACRODIR -Overwrite the location where Autoconf files were installed. You can -also set the @code{AC_MACRODIR} environment variable to a directory; -this option overrides the environment variable. +Override the location where the installed Autoconf data files are looked +for. You can also set the @code{AC_MACRODIR} environment variable to a +directory; this option overrides the environment variable. -This option is rarely needed and dangerous: only when you play with -different versions of Autoconf. +This option is rarely needed and dangerous; it is only used when one +plays with different versions of Autoconf simultaneously. @item address@hidden @itemx -l @var{dir} @@ -1014,32 +1018,33 @@ Warnings about @samp{syntax} are enabled by default, and the environment variable @code{WARNINGS}, a comma separated list of categories, is -honored. @command{autoconf} will actually behave as if you had run +honored. @command{autoconf -W @var{category}} will actually +behave as if you had run: @example -autoconf --warnings=syntax,$WARNINGS,@var{categories} +autoconf --warnings=syntax,$WARNINGS,@var{category} @end example @noindent -If you want to disable @command{autoconf}'s defaults and @code{WARNING} -but enable the warnings about obsolete constructs, use @option{-W -none,obsolete}. +If you want to disable @command{autoconf}'s defaults and @code{WARNING}, +but (for example) enable the warnings about obsolete constructs, you +would use @option{-W none,obsolete}. @cindex Back trace @cindex Macro invocation stack @command{autoconf} displays a back trace for errors, but not for -warnings; if you want them, just pass @option{-W error}. For instance +warnings; if you want them, just pass @option{-W error}. For instance, on this @file{configure.ac}: @example AC_DEFUN([INNER], [AC_TRY_RUN([true])]) -AC_DEFUN([OUTTER], +AC_DEFUN([OUTER], [INNER]) AC_INIT -OUTTER +OUTER @end example @noindent @@ -1054,32 +1059,34 @@ to allow cross compiling acgeneral.m4:3044: AC_TRY_RUN is expanded from... configure.ac:2: INNER is expanded from... -configure.ac:5: OUTTER is expanded from... +configure.ac:5: OUTER is expanded from... configure.ac:8: the top level @end example @item address@hidden:@var{format}] @itemx -t @var{macro}[:@var{format}] Do not create the @code{configure} script, but list the calls to address@hidden according to the @var{format}. Multiple @option{--trace} list -several macros. Multiple @option{--trace} for a single macro do not -accumulate, nevertheless, @var{format} can be arbitrarily long. - -The @var{format} is a regular string, with new lines if wanted. It -defaults to @samp{$f:$l:$n:$%}, see below for details on the address@hidden address@hidden according to the @var{format}. Multiple @option{--trace} +arguments can be used to list several macros. Multiple @option{--trace} +arguments for a single macro are not cumulative; instead, you should +just make @var{format} as long as needed. + +The @var{format} is a regular string, with newlines if desired, and +several special escape codes. It defaults to @samp{$f:$l:$n:$%}; see +below for details on the @var{format}. @item --initialization @itemx -i -By default @option{--trace} does not trace the initialization of the +By default, @option{--trace} does not trace the initialization of the Autoconf macros (typically the @code{AC_DEFUN} definitions). This results in a noticeable speedup, but can be disabled by this option. @end table -It is often necessary to check the content of a @file{configure.ac} file, -but it is extremely fragile and error prone to try to parse it. It is -suggested to rely upon @option{--trace} to scan @file{configure.ac}. +It is often necessary to check the content of a @file{configure.ac} +file, but parsing it yourself is extremely fragile and error-prone. It +is suggested that you rely upon @option{--trace} to scan address@hidden The @var{format} of @option{--trace} can use the following special escapes: @@ -1089,13 +1096,13 @@ The character @samp{$}. @item $f -The filename from where @var{macro} is called. +The filename from which @var{macro} is called. @item $l -The line number from where @var{macro} is called. +The line number from which @var{macro} is called. @item $d -The depth of the @var{macro} call. This is an M4 technical detail which +The depth of the @var{macro} call. This is an M4 technical detail that you probably don't want to know about. @item $n @@ -1107,9 +1114,9 @@ @item $@@ @itemx address@hidden@@ @itemx address@hidden@address@hidden@@ -All the arguments given to the @var{macro} separated by the character address@hidden or the string @var{separator}, @samp{,} by default. Each -argument is quoted, i.e. enclosed in a pair of square bracket. +All the arguments passed to @var{macro}, separated by the character address@hidden or the string @var{separator} (@samp{,} by default). Each +argument is quoted, i.e. enclosed in a pair of square brackets. @item $* @itemx address@hidden @@ -1122,12 +1129,12 @@ As above, but the arguments are not quoted, all new line characters in the arguments are smashed, and the default separator is @samp{:}. -The escape @samp{$%} produces traces that hold in a single line (unless -you put new lines in the @samp{separator}), while @samp{$@@} and address@hidden do not. +The escape @samp{$%} produces single-line trace outputs (unless you put +newlines in the @samp{separator}), while @samp{$@@} and @samp{$*} do +not. @end table -For instance, to know the list of variables that are substituted: +For instance, to find the list of variables that are substituted, use: @example @group @@ -1160,7 +1167,7 @@ @end example @noindent -Much freedom is given over the @var{format}: +The @var{format} gives you a lot of freedom: @example @group @@ -1173,7 +1180,7 @@ @end example @noindent -The long @var{separator}s can be used to ease parsing of complex +A long @var{separator} can be used to improve the readability of complex structures: @example @@ -1210,11 +1217,11 @@ @code{autoreconf} does not support having, in the same directory tree, both directories that are parts of a larger package (sharing address@hidden and @file{acconfig.h}), and directories that are address@hidden and @file{acconfig.h}) and directories that are independent packages (each with their own @file{aclocal.m4} and @file{acconfig.h}). It assumes that they are all part of the same -package, if you use @option{--localdir}, or that each directory is a -separate package, if you don't use it. This restriction may be removed +package if you use @option{--localdir}, or that each directory is a +separate package if you don't use it. This restriction may be removed in the future. @xref{Automatic Remaking}, for @file{Makefile} rules to automatically @@ -1268,12 +1275,12 @@ @item address@hidden @itemx -A @var{dir} @evindex AC_MACRODIR -Overwrite the location where Autoconf files were installed. You can -also set the @code{AC_MACRODIR} environment variable to a directory; -this option overrides the environment variable. +Override the location where the installed Autoconf data files are looked +for. You can also set the @code{AC_MACRODIR} environment variable to a +directory; this option overrides the environment variable. -This option is rarely needed and dangerous: only when you play with -different versions of Autoconf. +This option is rarely needed and dangerous; it is only used when one +plays with different versions of Autoconf simultaneously. @item address@hidden @itemx -M @var{dir} @@ -1309,7 +1316,7 @@ Autoconf-generated @code{configure} scripts need some information about how to initialize, such as how to find the package's source files; and about the output files to produce. The following sections describe -initialization and creating output files. +initialization and the creation of output files. @menu * Notices:: Copyright, version numbers in @code{configure} @@ -1337,7 +1344,7 @@ @cindex Version Ensure that a recent enough version of Autoconf is being used. If the version of Autoconf being used to create @code{configure} is earlier -than @var{version}, print an error message on the standard error output +than @var{version}, print an error message to the standard error output and do not create @code{configure}. For example: @example @@ -1351,12 +1358,12 @@ @defmac AC_COPYRIGHT (@var{copyright-notice}) @maindex COPYRIGHT @cindex Copyright Notice -State that in addition to the Free Software Foundation's copyright over +State that, in addition to the Free Software Foundation's copyright on the Autoconf macros, parts of your @code{configure} are covered by the @var{copyright-notice}. The @var{copyright-notice} will show up in both the head of address@hidden, and in @samp{configure --version}. address@hidden and in @samp{configure --version}. @end defmac @@ -1462,14 +1469,10 @@ @section Outputting Files Every Autoconf-generated @code{configure} script must finish by calling address@hidden It is the macro that generates @file{config.status} -which will create the @file{Makefile}s and optional other files -resulting from configuration. The only other required macro is address@hidden (@pxref{Input}). - -Because of history, this macro is described twice below. The first -definition describes the use that is now recommended. The second -describes the former use, and its modern equivalent. address@hidden It is the macro that generates @file{config.status}, +which will create the @file{Makefile}s and any other files resulting +from configuration. The only other required macro is @code{AC_INIT} +(@pxref{Input}). @defmac AC_OUTPUT @maindex OUTPUT @@ -1487,8 +1490,9 @@ are honored. @end defmac address@hidden Macros}, for a description of the arguments @code{AC_OUTPUT} -used to support. +Historically, the usage of @code{AC_OUTPUT} was somewhat different. address@hidden Macros}, for a description of the arguments that address@hidden used to support. If you run @code{make} on subdirectories, you should run it using the @@ -1519,12 +1523,12 @@ @node Configuration Actions, Configuration Files, Output, Setup @section Taking Configuration Actions -While everything is made so that you imagine @file{configure} does -everything by itself, there is actually a hidden slave: address@hidden @file{configure} is in charge of examining your -system, but it is @file{config.status} that actually takes the proper -actions based on the results of @file{configure}. The most typical task -of @file{config.status} is to @emph{instantiate} files. address@hidden is designed so that it appears to do everything itself, +but there is actually a hidden slave: @file{config.status}. address@hidden is in charge of examining your system, but it is address@hidden that actually takes the proper actions based on the +results of @file{configure}. The most typical task of address@hidden is to @emph{instantiate} files. This section describes the common behavior of the four standard instantiating macros: @code{AC_CONFIG_FILES}, @code{AC_CONFIG_HEADERS}, @@ -1539,25 +1543,26 @@ @noindent where the arguments are: + @table @var @item @address@hidden A whitespace-separated list of tags, which are typically the names of the files to instantiate. @item commands -They are output into @file{config.status} as literally. These commands -are always associated to a tag which the user can use to tell address@hidden what are the commands she wants to run. These -commands are run each time a @var{tag} request is given to address@hidden, i.e., typically each time the file +Shell commands output literally into @file{config.status}, and +associated with a tag that the user can use to tell @file{config.status} +which the commands to run. The commands are run each time a @var{tag} +request is given to @file{config.status}; typically, each time the file @address@hidden is created. @item init-cmds -They are output via an @emph{unquoted} here-doc. As a consequence address@hidden will be output as the value of @var{var}. This is typically -used by @file{configure} to give @file{config.status} some variables it -needs to run the @var{cmds}. At the difference of @var{cmds}, the address@hidden are always run. +Shell commands output @emph{unquoted} near the beginning of address@hidden, and executed each time @file{config.status} runs +(regardless of the tag). Because they are unquoted, for example, address@hidden will be output as the value of @var{var}. @var{init-cmds} +is typically used by @file{configure} to give @file{config.status} some +variables it needs to run the @var{commands}. @end table All these macros can be called multiple times, with different @@ -2052,6 +2057,9 @@ @end group @end example +(Be careful if you copy these lines directly into your Makefile, as you +will need to convert the indented lines to start with the tab character.) + In addition, you should use @samp{AC_CONFIG_FILES(stamp-h, echo timestamp > stamp-h)} so @file{config.status} will ensure that @file{config.h} is considered up to date. @xref{Output}, for more @@ -2183,11 +2191,14 @@ arguments are given, the first one is used. Otherwise, @command{autoheader} creates @file{config.h.in}. -In order to do its job @command{autoheader} needs you to document all -the symbols that you might use, i.e., that there is at least one +In order to do its job, @command{autoheader} needs you to document all +of the symbols that you might use; i.e., there must be at least one @code{AC_DEFINE} or one @code{AC_DEFINE_UNQUOTED} using its third -argument, see @ref{Defining Symbols}. An additional constraint is that -the first argument must be a literal. +argument for each symbol (@pxref{Defining Symbols}). An additional +constraint is that the first argument of @code{AC_DEFINE} must be a +literal. Note that all symbols defined by Autoconf's built-in tests are +already documented properly; you only need to document those that you +define yourself. You might wonder why @command{autoheader} is needed: after all, why would @command{configure} need to ``patch'' a @file{config.h.in} to @@ -2196,7 +2207,7 @@ Well, when everything rocks the answer is just that we are wasting our time maintaining @command{autoheader}: generating @file{config.h} -directly is just what is needed. +directly is all that is needed. But when things go wrong, you'll thank the Autoconf team for @command{autoheader}... @@ -2239,12 +2250,12 @@ @item address@hidden @itemx -A @var{dir} @evindex AC_MACRODIR -Overwrite the location where Autoconf files were installed. You can -also set the @code{AC_MACRODIR} environment variable to a directory; -this option overrides the environment variable. +Override the location where the installed Autoconf data files are looked +for. You can also set the @code{AC_MACRODIR} environment variable to a +directory; this option overrides the environment variable. -This option is rarely needed and dangerous: only when you play with -different versions of Autoconf. +This option is rarely needed and dangerous; it is only used when one +plays with different versions of Autoconf simultaneously. @item address@hidden @itemx -l @var{dir} @@ -2286,23 +2297,22 @@ preprocessor symbols it might define. It knows how to generate templates for symbols defined by @code{AC_CHECK_HEADERS}, @code{AC_CHECK_FUNCS} etc., but if you @code{AC_DEFINE} any additional -symbol, you must define a template for it. @code{autoheader} diagnoses -missing templates, and fails. +symbol, you must define a template for it. If there are missing +templates, @code{autoheader} fails with an error message. -The simplest means to create a template for a @var{symbol} is simply to -document one of the @samp{AC_DEFINE(@var{symbol})}, see @ref{Defining -Symbols}. You may also use one of the following macros. +The simplest way to create a template for a @var{symbol} is to supply +the @var{description} argument to an @samp{AC_DEFINE(@var{symbol})}; see address@hidden Symbols}. You may also use one of the following macros. @defmac AH_VERBATIM (@var{key}, @var{template}) @maindex AH_VERBATIM @maindex VERBATIM -Inform @code{autoheader} that it must include the @var{template} as is -in the header template file. This @var{template} is associated to the address@hidden, which is used to sort all the different templates, and -guarantee their uniqueness. It should be the symbol that can be address@hidden'd. +Tell @code{autoheader} to include the @var{template} as-is in the header +template file. This @var{template} is associated with the @var{key}, +which is used to sort all the different templates and guarantee their +uniqueness. It should be the symbol that can be @code{AC_DEFINE}'d. -For instance: +For example: @example AH_VERBATIM([_GNU_SOURCE], @@ -2317,11 +2327,11 @@ @defmac AH_TEMPLATE (@var{key}, @var{description}) @maindex AH_TEMPLATE @maindex TEMPLATE -Inform @code{autoheader} that it must generate a template for @var{key}. -This macro generates standard templates, as @code{AC_DEFINE} does when a +Tell @code{autoheader} to generate a template for @var{key}. This macro +generates standard templates just like @code{AC_DEFINE} when a @var{description} is given. -For instance: +For example: @example AH_TEMPLATE([CRAY_STACKSEG_END], @@ -2442,12 +2452,13 @@ link to @address@hidden/config/$obj_format.h}. The tempting value @samp{.} for @var{dest} is invalid: it makes it -impossible for @samp{config.status} to guess the links to establish. It -is then valid to run: +impossible for @samp{config.status} to guess the links to establish. + +One can then run: @example ./config.status host.h object.h @end example -to establish the links. +to create the links. @end defmac @@ -6372,8 +6383,8 @@ Don't leave, there is some more! The @sc{qnx} 4.25 @command{expr}, in addition of preferring @samp{0} to -the empty string, has a funny behavior wrt exit status: it's always 1 -when the parenthesis are used! +the empty string, has a funny behavior in its exit status: it's always 1 +when parentheses are used! @example $ val=`expr 'a' : 'a'`; echo "$?: $val" @@ -7143,7 +7154,7 @@ @defmac AC_MSG_ERROR (@var{error-description}, @ovar{exit-status}) @maindex MSG_ERROR Notify the user of an error that prevents @code{configure} from -completing. This macro prints an error message on the standard error +completing. This macro prints an error message to the standard error output and exits @code{configure} with @var{exit-status} (1 by default). @var{error-description} should be something like @samp{invalid value $HOME for \$HOME}. @@ -7155,7 +7166,7 @@ @defmac AC_MSG_WARN (@var{problem-description}) @maindex MSG_WARN Notify the @code{configure} user of a possible problem. This macro -prints the message on the standard error output; @code{configure} +prints the message to the standard error output; @code{configure} continues running afterward, so macros that call @code{AC_MSG_WARN} should provide a default (back-up) behavior for the situations they warn about. @var{problem-description} should be something like @samp{ln -s seems to @@ -7850,7 +7861,7 @@ @defmac AC_BEFORE (@var{this-macro-name}, @var{called-macro-name}) @maindex BEFORE -Make @code{m4} print a warning message on the standard error output if +Make @code{m4} print a warning message to the standard error output if @var{called-macro-name} has already been called. @var{this-macro-name} should be the name of the macro that is calling @code{AC_BEFORE}. The macro @var{called-macro-name} must have been defined using @@ -8025,10 +8036,10 @@ beginning of a line, followed by a comment that repeats the name of the macro being defined. If you want to avoid the new-line which is then introduced, use @code{dnl}. Better yet, use @samp{[]dnl} @emph{even} -behind of parenthesis, since because of the M4 evaluation rule the address@hidden might be appended to the result of the evaluation of the -macro before it (e.g., leading to @samp{yesdnl} instead of @samp{yes}). -For instance, instead of: +inside of parentheses: because of the M4 evaluation rules, the address@hidden might otherwise be appended to the result of the macro +evaluation (e.g., leading to @samp{yesdnl} instead of @samp{yes}). For +instance, instead of: @example AC_DEFUN([AC_PATH_X], @@ -9062,12 +9073,12 @@ @item address@hidden @itemx -A @var{dir} @evindex AC_MACRODIR -Overwrite the location where Autoconf files were installed. You can -also set the @code{AC_MACRODIR} environment variable to a directory; -this option overrides the environment variable. +Override the location where the installed Autoconf data files are looked +for. You can also set the @code{AC_MACRODIR} environment variable to a +directory; this option overrides the environment variable. -This option is rarely needed and dangerous: only when you play with -different versions of Autoconf. +This option is rarely needed and dangerous; it is only used when one +plays with different versions of Autoconf simultaneously. @item address@hidden @itemx -l @var{dir} @@ -9505,7 +9516,7 @@ @defmac AC_OBSOLETE (@var{this-macro-name}, @ovar{suggestion}) @maindex OBSOLETE -Make @code{m4} print a message on the standard error output warning that +Make @code{m4} print a message to the standard error output warning that @var{this-macro-name} is obsolete, and giving the file and line number where it was called. @var{this-macro-name} should be the name of the macro that is calling @code{AC_OBSOLETE}. If @var{suggestion} is given,