autoconf: Coding Style
1
1 10.6 Coding Style
1 =================
1
1 The Autoconf macros follow a strict coding style. You are encouraged to
1 follow this style, especially if you intend to distribute your macro,
1 either by contributing it to Autoconf itself or the Autoconf Macro
1 Archive (http://www.gnu.org/software/autoconf-archive/), or by other
1 means.
1
1 The first requirement is to pay great attention to the quotation.
DONTPRINTYET 1 For more details, see ⇒Autoconf Language, and *noteM4
1DONTPRINTYET 1 For more details, see ⇒Autoconf Language, and ⇒M4
Quotation.
1
1 Do not try to invent new interfaces. It is likely that there is a
1 macro in Autoconf that resembles the macro you are defining: try to
1 stick to this existing interface (order of arguments, default values,
1 etc.). We _are_ conscious that some of these interfaces are not
1 perfect; nevertheless, when harmless, homogeneity should be preferred
1 over creativity.
1
1 Be careful about clashes both between M4 symbols and between shell
1 variables.
1
1 If you stick to the suggested M4 naming scheme (⇒Macro Names),
1 you are unlikely to generate conflicts. Nevertheless, when you need to
1 set a special value, _avoid using a regular macro name_; rather, use an
1 "impossible" name. For instance, up to version 2.13, the macro
1 `AC_SUBST' used to remember what SYMBOL macros were already defined by
1 setting `AC_SUBST_SYMBOL', which is a regular macro name. But since
1 there is a macro named `AC_SUBST_FILE', it was just impossible to
1 `AC_SUBST(FILE)'! In this case, `AC_SUBST(SYMBOL)' or
1 `_AC_SUBST(SYMBOL)' should have been used (yes, with the parentheses).
1
1 No Autoconf macro should ever enter the user-variable name space;
1 i.e., except for the variables that are the actual result of running the
1 macro, all shell variables should start with `ac_'. In addition, small
1 macros or any macro that is likely to be embedded in other macros
1 should be careful not to use obvious names.
1
1 Do not use `dnl' to introduce comments: most of the comments you are
1 likely to write are either header comments which are not output anyway,
1 or comments that should make their way into `configure'. There are
1 exceptional cases where you do want to comment special M4 constructs,
1 in which case `dnl' is right, but keep in mind that it is unlikely.
1
1 M4 ignores the leading blanks and newlines before each argument.
1 Use this feature to indent in such a way that arguments are (more or
1 less) aligned with the opening parenthesis of the macro being called.
1 For instance, instead of
1
1 AC_CACHE_CHECK(for EMX OS/2 environment,
1 ac_cv_emxos2,
1 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, [return __EMX__;])],
1 [ac_cv_emxos2=yes], [ac_cv_emxos2=no])])
1
1 write
1
1 AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2],
1 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])],
1 [ac_cv_emxos2=yes],
1 [ac_cv_emxos2=no])])
1
1 or even
1
1 AC_CACHE_CHECK([for EMX OS/2 environment],
1 [ac_cv_emxos2],
1 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([],
1 [return __EMX__;])],
1 [ac_cv_emxos2=yes],
1 [ac_cv_emxos2=no])])
1
1 When using `AC_RUN_IFELSE' or any macro that cannot work when
1 cross-compiling, provide a pessimistic value (typically `no').
1
1 Feel free to use various tricks to prevent auxiliary tools, such as
1 syntax-highlighting editors, from behaving improperly. For instance,
1 instead of:
1
1 m4_bpatsubst([$1], [$"])
1
1 use
1
1 m4_bpatsubst([$1], [$""])
1
1 so that Emacsen do not open an endless "string" at the first quote.
1 For the same reasons, avoid:
1
1 test $[#] != 0
1
1 and use:
1
1 test $[@%:@] != 0
1
1 Otherwise, the closing bracket would be hidden inside a `#'-comment,
1 breaking the bracket-matching highlighting from Emacsen. Note the
1 preferred style to escape from M4: `$[1]', `$[@]', etc. Do not escape
1 when it is unnecessary. Common examples of useless quotation are
1 `[$]$1' (write `$$1'), `[$]var' (use `$var'), etc. If you add
1 portability issues to the picture, you'll prefer `${1+"$[@]"}' to
1 `"[$]@"', and you'll prefer do something better than hacking Autoconf
1 `:-)'.
1
1 When using `sed', don't use `-e' except for indenting purposes.
1 With the `s' and `y' commands, the preferred separator is `/' unless
1 `/' itself might appear in the pattern or replacement, in which case
1 you should use `|', or optionally `,' if you know the pattern and
1 replacement cannot contain a file name. If none of these characters
1 will do, choose a printable character that cannot appear in the pattern
1 or replacement. Characters from the set `"#$&'()*;<=>?`|~' are good
1 choices if the pattern or replacement might contain a file name, since
1 they have special meaning to the shell and are less likely to occur in
1 file names.
1
1 ⇒Macro Definitions, for details on how to define a macro. If
1 a macro doesn't use `AC_REQUIRE', is expected to never be the object of
1 an `AC_REQUIRE' directive, and macros required by other macros inside
1 arguments do not need to be expanded before this macro, then use
1 `m4_define'. In case of doubt, use `AC_DEFUN'. Also take into account
1 that public third-party macros need to use `AC_DEFUN' in order to be
11 found by `aclocal' (⇒Extending aclocal (automake)Extending
aclocal.). All the `AC_REQUIRE' statements should be at the beginning
1 of the macro, and each statement should be followed by `dnl'.
1
1 You should not rely on the number of arguments: instead of checking
1 whether an argument is missing, test that it is not empty. It provides
1 both a simpler and a more predictable interface to the user, and saves
1 room for further arguments.
1
1 Unless the macro is short, try to leave the closing `])' at the
1 beginning of a line, followed by a comment that repeats the name of the
1 macro being defined. This introduces an additional newline in
1 `configure'; normally, that is not a problem, but if you want to remove
1 it you can use `[]dnl' on the last line. You can similarly use `[]dnl'
1 after a macro call to remove its newline. `[]dnl' is recommended
1 instead of `dnl' to ensure that M4 does not interpret the `dnl' as
1 being attached to the preceding text or macro output. For example,
1 instead of:
1
1 AC_DEFUN([AC_PATH_X],
1 [AC_MSG_CHECKING([for X])
1 AC_REQUIRE_CPP()
1 # ...omitted...
1 AC_MSG_RESULT([libraries $x_libraries, headers $x_includes])
1 fi])
1
1 you would write:
1
1 AC_DEFUN([AC_PATH_X],
1 [AC_REQUIRE_CPP()[]dnl
1 AC_MSG_CHECKING([for X])
1 # ...omitted...
1 AC_MSG_RESULT([libraries $x_libraries, headers $x_includes])
1 fi[]dnl
1 ])# AC_PATH_X
1
1 If the macro is long, try to split it into logical chunks.
1 Typically, macros that check for a bug in a function and prepare its
1 `AC_LIBOBJ' replacement should have an auxiliary macro to perform this
1 setup. Do not hesitate to introduce auxiliary macros to factor your
1 code.
1
1 In order to highlight the recommended coding style, here is a macro
1 written the old way:
1
1 dnl Check for EMX on OS/2.
1 dnl _AC_EMXOS2
1 AC_DEFUN(_AC_EMXOS2,
1 [AC_CACHE_CHECK(for EMX OS/2 environment, ac_cv_emxos2,
1 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, return __EMX__;)],
1 ac_cv_emxos2=yes, ac_cv_emxos2=no)])
1 test "x$ac_cv_emxos2" = xyes && EMXOS2=yes])
1
1 and the new way:
1
1 # _AC_EMXOS2
1 # ----------
1 # Check for EMX on OS/2.
1 m4_define([_AC_EMXOS2],
1 [AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2],
1 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])],
1 [ac_cv_emxos2=yes],
1 [ac_cv_emxos2=no])])
1 test "x$ac_cv_emxos2" = xyes && EMXOS2=yes[]dnl
1 ])# _AC_EMXOS2
1