* Macro Index:: Index of Autoconf macros
* Concept Index:: General index
-@detailmenu
- --- The Detailed Node Listing ---
+@detailmenu --- The Detailed Node Listing ---
Making @code{configure} Scripts
* Invoking autoconf:: How to create configuration scripts
* Invoking autoreconf:: Remaking multiple @code{configure} scripts
+Writing @file{configure.in}
+
+* Shell Script Compiler:: Autoconf as solution of a problem
+* Autoconf Language:: Programming in Autoconf
+* configure.in Layout:: Standard organization of configure.in
+
Initialization and Output Files
* Notices:: Copyright, version numbers in @code{configure}
@end detailmenu
@end menu
+@c ============================================================= Introduction.
+
@node Introduction, Making configure Scripts, Top, Top
@chapter Introduction
@code{autoconf@@gnu.org}. Please include the Autoconf version number,
which you can get by running @samp{autoconf --version}.
+
+@c ================================================= Making configure Scripts.
+
@node Making configure Scripts, Setup, Introduction, Top
@chapter Making @code{configure} Scripts
@cindex @file{aclocal.m4}
good start in writing @file{configure.in} (@pxref{Invoking autoscan},
for more information).
+
+
+@menu
+* Shell Script Compiler:: Autoconf as solution of a problem
+* Autoconf Language:: Programming in Autoconf
+* configure.in Layout:: Standard organization of configure.in
+@end menu
+
+@node Shell Script Compiler, Autoconf Language, Writing configure.in, Writing configure.in
+@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.in}, you must understand
+@emph{what} is the problem it tries to answer, and @emph{how} it does.
+
+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
+@code{configure} 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,
+@code{autoconf}, which takes an Autoconf program, @file{configure.in},
+and transform it in 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
+@code{sh} 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 which 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 @code{m4}, and implement the extensions as a set of
+@code{m4} macros.
+
+
+@node Autoconf Language, configure.in Layout, Shell Script Compiler, Writing configure.in
+@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.
+
+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 @code{m4} quote characters @samp{[} and @samp{]},
+and are separated by a comma. Any leading space 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.
+
+For instance:
+
+@example
+AC_CHECK_HEADER([stdio.h],
+ [AC_DEFINE([HAVE_STDIO_H])],
+ [AC_MSG_ERROR([Sorry, can't do anything for you])])
+@end example
+
+@noindent
+is perfectly quoted. You may safely simplify quotation to
+
+@example
+AC_CHECK_HEADER(stdio.h,
+ [AC_DEFINE(HAVE_STDIO_H)],
+ [AC_MSG_ERROR([Sorry, can't do anything for you])])
+@end example
+
+@noindent
+Notice that the argument of @code{AC_MSG_ERROR} is still quoted,
+otherwise its comma would have been understood as an argument separator.
+
+The following example is wrong and dangerous, as it is underquoted:
+
+@example
+AC_CHECK_HEADER(stdio.h,
+ AC_DEFINE(HAVE_STDIO_H),
+ AC_MSG_ERROR([Sorry, can't do anything for you]))
+@end example
+
+You may have to use text which also resembles a macro call. In this
+case, you must quote this text at top level:
+
+@example
+echo "Hard rock was here! --[AC_DC]"
+@end example
+
+@noindent
+which will result in
+
+@example
+echo "Hard rock was here! --AC_DC"
+@end example
+
+@noindent
+in @code{configure}. Since there is an additional quoting level for each
+macro invocation, this results in @emph{double quoting all the literal
+strings}:
+
+@example
+AC_MSG_WARN([[AC_DC stinks --Iron Maiden]])
+@end example
+
+You are now able to understand one of the constructs of Autoconf which
+has continuously been misunderstood... The thumb rule is that
+@emph{whenever you expect macro expansion, expect quote expansion},
+i.e., expect one level of quotes to be lost. For instance
+
+@example
+AC_COMPILE_IFELSE([char b[10];],, exit 1)
+@end example
+
+@noindent
+is incorrect: here the first argument of @code{AC_COMPILE_IFELSE}, is
+@samp{char b[10];}, and it will be expanded once, which results in
+@samp{char b10;}. There was a idiom developed in the Autoconf world to
+address this issue, based on the @code{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];]],, exit 1)
+@end example
+
+@noindent
+and voil@`a! You really produced @samp{char b[10];}.
+
+The careful reader will note that the so-called perfectly quoted
+@code{AC_CHECK_HEADER} example above is actually lacking three pairs of
+quotes! Nevertheless, for sake of readability, double quotation of
+literals is used only where needed.
+
+
+Some macros take optional arguments, which this documentation represents
+@ovar{arg} (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:
+
+@example
+AC_CHECK_HEADERS(stdio.h, [], [])
+AC_CHECK_HEADERS(stdio.h,,)
+AC_CHECK_HEADERS(stdio.h)
+@end example
+
+It is best to put each macro call on its own line in
+@file{configure.in}. Most of the macros don't add extra newlines; they
+rely on the newline after the macro call to terminate the commands.
+This approach makes the generated @code{configure} script a little
+easier to read by not inserting lots of blank lines. It is generally
+safe to set shell variables on the same line as a macro call, because
+the shell allows assignments without intervening newlines.
+
+You can include comments in @file{configure.in} files by starting them
+with the @samp{#}. For example, it is helpful to begin
+@file{configure.in} files with a line like this:
+
+@example
+# Process this file with autoconf to produce a configure script.
+@end example
+
+@node configure.in Layout, , Autoconf Language, Writing configure.in
+@subsection Standard @file{configure.in} Layout
+
The order in which @file{configure.in} calls the Autoconf macros is not
important, with a few exceptions. Every @file{configure.in} must
contain a call to @code{AC_INIT} before the checks, and a call to
@end group
@end display
-It is best to put each macro call on its own line in
-@file{configure.in}. Most of the macros don't add extra newlines; they
-rely on the newline after the macro call to terminate the commands.
-This approach makes the generated @code{configure} script a little
-easier to read by not inserting lots of blank lines. It is generally
-safe to set shell variables on the same line as a macro call, because
-the shell allows assignments without intervening newlines.
-
-When calling macros that take arguments, there must not be any blank
-space between the macro name and the open parenthesis. Arguments can be
-more than one line long if they are enclosed within the @code{m4} quote
-characters @samp{[} and @samp{]}. If you have a long line such as a
-list of file names, you can generally use a backslash at the end of a
-line to continue it logically on the next line (this is implemented by
-the shell, not by anything special that Autoconf does).
-
-Some macros handle two cases: what to do if the given condition is met,
-and what to do if the condition is not met. In some places you might
-want to do something if a condition is true but do nothing if it's
-false, or vice versa. To omit the true case, pass an empty value for
-the @var{action-if-found} argument to the macro. To omit the false
-case, omit the @var{action-if-not-found} argument to the macro,
-including the comma before it.
-
-You can include comments in @file{configure.in} files by starting them
-with the @code{m4} builtin macro @code{dnl}, which discards text up
-through the next newline. These comments do not appear in the generated
-@code{configure} scripts. For example, it is helpful to begin
-@file{configure.in} files with a line like this:
-
-@example
-dnl Process this file with autoconf to produce a configure script.
-@end example
@node Invoking autoscan, Invoking ifnames, Writing configure.in, Making configure Scripts
@section Using @code{autoscan} to Create @file{configure.in}
Print the version number of Autoconf and exit.
@end table
+
+@c ========================================= Initialization and Output Files.
+
@node Setup, Existing Tests, Making configure Scripts, Top
@chapter Initialization and Output Files
macro is obsolete; use @code{AC_HEADER_DIRENT} instead.
@end defmac
+
+@c ========================================================= Writing Tests
+
@node Writing Tests, Results, Existing Tests, Top
@chapter Writing Tests
depending on which language is current.
@end defmac
+
+@c ====================================================== Results of Tests.
+
@node Results, Writing Macros, Writing Tests, Top
@chapter Results of Tests
is considered obsolete.
@end defmac
+
+@c ========================================================== Writing Macros.
+
@node Writing Macros, Manual Configuration, Results, Top
@chapter Writing Macros
@node Quoting, Dependencies Between Macros, Macro Names, Writing Macros
@section Quoting
+@cindex quotation
+
+@c FIXME: Grmph, yet another quoting myth: quotation has *never*
+@c prevented `expansion' of $1. Unless it refers to the expansion
+@c of the value of $1? Anyway, we need a rewrite here...
Macros that are called by other macros are evaluated by @code{m4}
several times; each evaluation might require another layer of quotes to
@samp{`} and @samp{'} to @samp{[} and @samp{]}, because many of the
macros use @samp{`} and @samp{'}, mismatched. However, in a few places
the macros need to use brackets (usually in C program text or regular
-expressions). In those places, they use the @code{m4} builtin command
-@code{changequote} to temporarily change the quote characters to
-@samp{<<} and @samp{>>}. (Sometimes, if they don't need to quote
-anything, they disable quoting entirely instead by setting the quote
-characters to empty strings.) Here is an example:
+expressions). In those places, just quote properly! See @ref{Autoconf
+Language}, for some information on quotation.
+
+It is frequent to read Autoconf programs with snippets like:
-@c FIXME: Oh no, please, no, not that crap again. Well, a new section
-@c on quoting is needed since below the bad thing is advocated.
@example
AC_TRY_LINK(
changequote(<<, >>)dnl
extern char *tzname[]; /* RS6000 and others reject char **tzname. */
#endif>>,
changequote([, ])dnl
-[atoi(*tzname);], ac_cv_var_tzname=yes, ac_cv_var_tzname=no)
+[atoi (*tzname);], ac_cv_var_tzname=yes, ac_cv_var_tzname=no)
+@end example
+
+@noindent
+which is incredibly useless since @code{AC_TRY_LINK} is @emph{already}
+double quoting, so you just need:
+
+@example
+AC_TRY_LINK(
+[#include <time.h>
+#ifndef tzname /* For SGI. */
+extern char *tzname[]; /* RS6000 and others reject char **tzname. */
+#endif],
+[atoi (*tzname);], ac_cv_var_tzname=yes, ac_cv_var_tzname=no)
+@end example
+
+@noindent
+The @code{m4} fluent reader noted that these two writings are rigorously
+equivalent, since @code{m4} swallows both the @samp{changequote(<<, >>)}
+and @samp{<<} @samp{>>} when it @dfn{collects} the arguments: these
+quotes are not part of the arguments!
+
+Simplified, the example above is just doing this:
+
+@example
+changequote(<<, >>)dnl
+<<[]>>
+changequote([, ])dnl
@end example
+@noindent
+instead of simply
+
+@example
+[[]]
+@end example
+
+
+With macros which do not double quote their arguments (which is the
+rule), double quote the (risky) literals:
+
+@example
+AC_LINK_IFELSE([AC_LANG_PROGRAM(
+[[#include <time.h>
+#ifndef tzname /* For SGI. */
+extern char *tzname[]; /* RS6000 and others reject char **tzname. */
+#endif]],
+[atoi (*tzname);])], ac_cv_var_tzname=yes, ac_cv_var_tzname=no)
+@end example
+
+@c FIXME: Quadrigraphs and hopeless cases.
+
When you create a @code{configure} script using newly written macros,
examine it carefully to check whether you need to add more quotes in
your macros. If one or more words have disappeared in the @code{m4}
@end defmac
+@c ================================================== Manual Configuration
+
@node Manual Configuration, Site Configuration, Writing Macros, Top
@chapter Manual Configuration
@xref{Generic Programs}, for information about the @code{AC_CHECK_TOOL}
macro which does that.
+
+@c ===================================================== Site Configuration.
+
@node Site Configuration, Invoking configure, Manual Configuration, Top
@chapter Site Configuration
fi
@end example
+
+@c ============================================== Running configure Scripts.
+
@node Invoking configure, Invoking config.status, Site Configuration, Top
@chapter Running @code{configure} Scripts
@cindex @code{configure}
@include install.texi
-@c Parts of the following section should obviously be part of INSTALL.
-@c But how to split that?
+
+@c ============================================== Recreating a Configuration
@node Invoking config.status, Questions, Invoking configure, Top
@chapter Recreating a Configuration
for @code{CONFIG_COMMANDS} etc.)
+@c ================================================ Questions About Autoconf.
+
@node Questions, Upgrading, Invoking config.status, Top
@chapter Questions About Autoconf
entire tree. This means that a lot of common things don't have to be
duplicated, even though they normally are in @code{configure} setups.
+
+@c ================================================= Upgrading From Version 1.
+
@node Upgrading, History, Questions, Top
@chapter Upgrading From Version 1
See whether any of your tests are of general enough usefulness to
encapsulate into macros that you can share.
+
+@c ===================================================== History of Autoconf.
+
@node History, Old Macro Names, Upgrading, Top
@chapter History of Autoconf
Finally, version 2.0 was ready. And there was much rejoicing. (And I
have free time again. I think. Yeah, right.)
+
+@c ========================================================= Old Macro Names.
+
@node Old Macro Names, Environment Variable Index, History, Top
@chapter Old Macro Names
projects / thirdparty / autoconf.git / commitdiff
