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