autoconf: Autoconf Language

1 
1 3.1.2 The Autoconf Language
1 ---------------------------
1 
1 The Autoconf language differs from many other computer languages
1 because it treats actual code the same as plain text.  Whereas in C,
1 for instance, data and instructions have different syntactic status, in
1 Autoconf their status is rigorously the same.  Therefore, we need a
1 means to distinguish literal strings from text to be expanded:
1 quotation.
1 
1    When calling macros that take arguments, there must not be any white
1 space between the macro name and the open parenthesis.
1 
1      AC_INIT ([oops], [1.0]) # incorrect
1      AC_INIT([hello], [1.0]) # good
1 
1    Arguments should be enclosed within the quote characters `[' and
1 `]', and be separated by commas.  Any leading blanks or newlines in
1 arguments are ignored, unless they are quoted.  You should always quote
1 an argument that might contain a macro name, comma, parenthesis, or a
1 leading blank or newline.  This rule applies recursively for every macro
1 call, including macros called from other macros.  For more details on
1 quoting rules, see ⇒Programming in M4.
1 
1    For instance:
1 
1      AC_CHECK_HEADER([stdio.h],
1                      [AC_DEFINE([HAVE_STDIO_H], [1],
1                         [Define to 1 if you have <stdio.h>.])],
1                      [AC_MSG_ERROR([sorry, can't do anything for you])])
1 
1 is quoted properly.  You may safely simplify its quotation to:
1 
1      AC_CHECK_HEADER([stdio.h],
1                      [AC_DEFINE([HAVE_STDIO_H], 1,
1                         [Define to 1 if you have <stdio.h>.])],
1                      [AC_MSG_ERROR([sorry, can't do anything for you])])
1 
1 because `1' cannot contain a macro call.  Here, the argument of
1 `AC_MSG_ERROR' must be quoted; otherwise, its comma would be
1 interpreted as an argument separator.  Also, the second and third
1 arguments of `AC_CHECK_HEADER' must be quoted, since they contain macro
1 calls.  The three arguments `HAVE_STDIO_H', `stdio.h', and `Define to 1
1 if you have <stdio.h>.' do not need quoting, but if you unwisely
1 defined a macro with a name like `Define' or `stdio' then they would
1 need quoting.  Cautious Autoconf users would keep the quotes, but many
1 Autoconf users find such precautions annoying, and would rewrite the
1 example as follows:
1 
1      AC_CHECK_HEADER(stdio.h,
1                      [AC_DEFINE(HAVE_STDIO_H, 1,
1                         [Define to 1 if you have <stdio.h>.])],
1                      [AC_MSG_ERROR([sorry, can't do anything for you])])
1 
1 This is safe, so long as you adopt good naming conventions and do not
1 define macros with names like `HAVE_STDIO_H', `stdio', or `h'.  Though
1 it is also safe here to omit the quotes around `Define to 1 if you have
1 <stdio.h>.' this is not recommended, as message strings are more likely
1 to inadvertently contain commas.
1 
1    The following example is wrong and dangerous, as it is underquoted:
1 
1      AC_CHECK_HEADER(stdio.h,
1                      AC_DEFINE(HAVE_STDIO_H, 1,
1                         Define to 1 if you have <stdio.h>.),
1                      AC_MSG_ERROR([sorry, can't do anything for you]))
1 
1    In other cases, you may have to use text that also resembles a macro
1 call.  You must quote that text even when it is not passed as a macro
1 argument.  For example, these two approaches in `configure.ac' (quoting
1 just the potential problems, or quoting the entire line) will protect
1 your script in case autoconf ever adds a macro `AC_DC':
1 
1      echo "Hard rock was here!  --[AC_DC]"
1      [echo "Hard rock was here!  --AC_DC"]
1 
1 which results in this text in `configure':
1 
1      echo "Hard rock was here!  --AC_DC"
1      echo "Hard rock was here!  --AC_DC"
1 
1 When you use the same text in a macro argument, you must therefore have
1 an extra quotation level (since one is stripped away by the macro
1 substitution).  In general, then, it is a good idea to _use double
1 quoting for all literal string arguments_, either around just the
1 problematic portions, or over the entire argument:
1 
1      AC_MSG_WARN([[AC_DC] stinks  --Iron Maiden])
1      AC_MSG_WARN([[AC_DC stinks  --Iron Maiden]])
1 
1    However, the above example triggers a warning about a possibly
1 unexpanded macro when running `autoconf', because it collides with the
1 namespace of macros reserved for the Autoconf language.  To be really
1 safe, you can use additional escaping (either a quadrigraph, or
1 creative shell constructs) to silence that particular warning:
1 
1      echo "Hard rock was here!  --AC""_DC"
1      AC_MSG_WARN([[AC@&t@_DC stinks  --Iron Maiden]])
1 
1    You are now able to understand one of the constructs of Autoconf that
1 has been continually misunderstood...  The rule of thumb is that
1 _whenever you expect macro expansion, expect quote expansion_; i.e.,
1 expect one level of quotes to be lost.  For instance:
1 
1      AC_COMPILE_IFELSE(AC_LANG_SOURCE([char b[10];]), [],
1       [AC_MSG_ERROR([you lose])])
1 
1 is incorrect: here, the first argument of `AC_LANG_SOURCE' is `char
1 b[10];' and is expanded once, which results in `char b10;'; and the
1 `AC_LANG_SOURCE' is also expanded prior to being passed to
1 `AC_COMPILE_IFELSE'.  (There was an idiom common in Autoconf's past to
1 address this issue via the M4 `changequote' primitive, but do not use
1 it!)  Let's take a closer look: the author meant the first argument to
1 be understood as a literal, and therefore it must be quoted twice;
1 likewise, the intermediate `AC_LANG_SOURCE' macro should be quoted once
1 so that it is only expanded after the rest of the body of
1 `AC_COMPILE_IFELSE' is in place:
1 
1      AC_COMPILE_IFELSE([AC_LANG_SOURCE([[char b[10];]])], [],
1        [AC_MSG_ERROR([you lose])])
1 
1 Voila`, you actually produce `char b[10];' this time!
1 
1    On the other hand, descriptions (e.g., the last parameter of
1 `AC_DEFINE' or `AS_HELP_STRING') are not literals--they are subject to
1 line breaking, for example--and should not be double quoted.  Even if
1 these descriptions are short and are not actually broken, double
1 quoting them yields weird results.
1 
1    Some macros take optional arguments, which this documentation
1 represents as [ARG] (not to be confused with the quote characters).
1 You may just leave them empty, or use `[]' to make the emptiness of the
1 argument explicit, or you may simply omit the trailing commas.  The
1 three lines below are equivalent:
1 
1      AC_CHECK_HEADERS([stdio.h], [], [], [])
1      AC_CHECK_HEADERS([stdio.h],,,)
1      AC_CHECK_HEADERS([stdio.h])
1 
1    It is best to put each macro call on its own line in `configure.ac'.
1 Most of the macros don't add extra newlines; they rely on the newline
1 after the macro call to terminate the commands.  This approach makes
1 the generated `configure' script a little easier to read by not
1 inserting lots of blank lines.  It is generally safe to set shell
1 variables on the same line as a macro call, because the shell allows
1 assignments without intervening newlines.
1 
1    You can include comments in `configure.ac' files by starting them
1 with the `#'.  For example, it is helpful to begin `configure.ac' files
1 with a line like this:
1 
1      # Process this file with autoconf to produce a configure script.
1