File: autoconf.info,  Node: Autoconf Language,  Next: Autoconf Input Layout,  Prev: Shell Script Compiler,  Up: Writing Autoconf Input

3.1.2 The Autoconf Language
---------------------------

The Autoconf language differs from many other computer languages because
it treats actual code the same as plain text.  Whereas in C, for
instance, data and instructions have 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 white
space between the macro name and the open parenthesis.

     AC_INIT ([oops], [1.0]) # incorrect
     AC_INIT([hello], [1.0]) # good

   Arguments should be enclosed within the quote characters ‘[’ and ‘]’,
and be separated by commas.  Any leading blanks or newlines in arguments
are ignored, unless they are quoted.  You should always quote an
argument that might contain a macro name, comma, parenthesis, or a
leading blank or newline.  This rule applies recursively for every macro
call, including macros called from other macros.  For more details on
quoting rules, see *note Programming in M4::.

   For instance:

     AC_CHECK_HEADER([stdio.h],
                     [AC_DEFINE([HAVE_STDIO_H], [1],
                        [Define to 1 if you have .])],
                     [AC_MSG_ERROR([sorry, can't do anything for you])])

is quoted properly.  You may safely simplify its quotation to:

     AC_CHECK_HEADER([stdio.h],
                     [AC_DEFINE([HAVE_STDIO_H], 1,
                        [Define to 1 if you have .])],
                     [AC_MSG_ERROR([sorry, can't do anything for you])])

because ‘1’ cannot contain a macro call.  Here, the argument of
‘AC_MSG_ERROR’ must be quoted; otherwise, its comma would be interpreted
as an argument separator.  Also, the second and third arguments of
‘AC_CHECK_HEADER’ must be quoted, since they contain macro calls.  The
three arguments ‘HAVE_STDIO_H’, ‘stdio.h’, and ‘Define to 1 if you have
.’ do not need quoting, but if you unwisely defined a macro
with a name like ‘Define’ or ‘stdio’ then they would need quoting.
Cautious Autoconf users would keep the quotes, but many Autoconf users
find such precautions annoying, and would rewrite the example as
follows:

     AC_CHECK_HEADER(stdio.h,
                     [AC_DEFINE(HAVE_STDIO_H, 1,
                        [Define to 1 if you have .])],
                     [AC_MSG_ERROR([sorry, can't do anything for you])])

This is safe, so long as you adopt good naming conventions and do not
define macros with names like ‘HAVE_STDIO_H’, ‘stdio’, or ‘h’.  Though
it is also safe here to omit the quotes around ‘Define to 1 if you have
.’ this is not recommended, as message strings are more likely
to inadvertently contain commas.

   The following example is wrong and dangerous, as it is underquoted:

     AC_CHECK_HEADER(stdio.h,
                     AC_DEFINE(HAVE_STDIO_H, 1,
                        Define to 1 if you have .),
                     AC_MSG_ERROR([sorry, can't do anything for you]))

   In other cases, you may want to use text that also resembles a macro
call.  You must quote that text (whether just the potential problem, or
the entire line) even when it is not passed as a macro argument; and you
may also have to use ‘m4_pattern_allow’ (*note Forbidden Patterns::), to
declare your intention that the resulting configure file will have a
literal that resembles what would otherwise be reserved for a macro
name.  For example:

     dnl Simulate a possible future autoconf macro
     m4_define([AC_DC], [oops])
     dnl Underquoted:
     echo "Hard rock was here!  --AC_DC"
     dnl Correctly quoted:
     m4_pattern_allow([AC_DC])
     echo "Hard rock was here!  --[AC_DC]"
     [echo "Hard rock was here!  --AC_DC"]

which results in this text in ‘configure’:

     echo "Hard rock was here!  --oops"
     echo "Hard rock was here!  --AC_DC"
     echo "Hard rock was here!  --AC_DC"

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 _use double
quoting for all literal string arguments_, either around just the
problematic portions, or over the entire argument:

     m4_pattern_allow([AC_DC])
     AC_MSG_WARN([[AC_DC] stinks  --Iron Maiden])
     AC_MSG_WARN([[AC_DC stinks  --Iron Maiden]])

   It is also possible to avoid the problematic patterns in the first
place, by the use of additional escaping (either a quadrigraph, or
creative shell constructs), in which case it is no longer necessary to
use ‘m4_pattern_allow’:

     echo "Hard rock was here!  --AC""_DC"
     AC_MSG_WARN([[AC@&t@_DC stinks  --Iron Maiden]])

   You are now able to understand one of the constructs of Autoconf that
has been continually misunderstood...  The rule of thumb is that
_whenever you expect macro expansion, expect quote expansion_; i.e.,
expect one level of quotes to be lost.  For instance:

     AC_COMPILE_IFELSE(AC_LANG_SOURCE([char b[10];]), [],
      [AC_MSG_ERROR([you lose])])

is incorrect: here, the first argument of ‘AC_LANG_SOURCE’ is ‘char
b[10];’ and is expanded once, which results in ‘char b10;’; and the
‘AC_LANG_SOURCE’ is also expanded prior to being passed to
‘AC_COMPILE_IFELSE’.  (There was an idiom common in Autoconf's past to
address this issue via the M4 ‘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;
likewise, the intermediate ‘AC_LANG_SOURCE’ macro should be quoted once
so that it is only expanded after the rest of the body of
‘AC_COMPILE_IFELSE’ is in place:

     AC_COMPILE_IFELSE([AC_LANG_SOURCE([[char b[10];]])], [],
       [AC_MSG_ERROR([you lose])])

Voilà, you actually produce ‘char b[10];’ this time!

   On the other hand, descriptions (e.g., the last parameter of
‘AC_DEFINE’ or ‘AS_HELP_STRING’) are not literals--they are subject to
line breaking, for example--and should not be double quoted.  Even if
these descriptions are short and are not actually broken, double quoting
them yields weird results.

   Some macros take optional arguments, which this documentation
represents as [ARG] (not to be confused with the quote characters).  You
may just leave them empty, or use ‘[]’ to make the emptiness of the
argument explicit, or you may simply omit the trailing commas.  The
three lines below are equivalent:

     AC_CHECK_HEADERS([stdio.h], [], [], [])
     AC_CHECK_HEADERS([stdio.h],,,)
     AC_CHECK_HEADERS([stdio.h])

   It is best to put each macro call on its own line in ‘configure.ac’.
Most of the macros don't add extra newlines; they rely on the newline
after the macro call to terminate the commands.  This approach makes the
generated ‘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 ‘configure.ac’ files by starting them
with the ‘#’.  For example, it is helpful to begin ‘configure.ac’ files
with a line like this:

     # Process this file with autoconf to produce a configure script.