>>>>> "Peter" == Peter Simons <[EMAIL PROTECTED]> writes:
>>>>> Akim Demaille writes:
>> dnl is still useful: it documents M4 constructs.
>> # is useful: it document Autoconf issues.
Peter> I see your point. I think we settle for a compromise and allow
Peter> both forms and explicitely mention both forms on the autoconf
Peter> archive web site. Then we can let the macro authors decide what
Peter> they like best. Supporting both comment delimiters in my tool
Peter> is trivial.
Here is what I wrote in the Autoconf documentation:
| @node Macro Definitions, Macro Names, Writing Macros, Writing Macros
| @section Macro Definitions
|
| @maindex DEFUN
| Autoconf macros are defined using the @code{AC_DEFUN} macro, which is
| similar to the M4 builtin @code{define} macro. In addition to defining
| a macro, @code{AC_DEFUN} adds to it some code which is used to constrain
| the order in which macros are called (@pxref{Prerequisite Macros}).
|
| An Autoconf macro definition looks like this:
|
| @example
| AC_DEFUN(@var{macro-name}, @var{macro-body})
| @end example
|
| You can refer to any arguments passed to the macro as @samp{$1},
| @samp{$2}, etc. @xref{Definitions,, How to define new macros, m4.info,
| GNU m4}, for more complete information on writing M4 macros.
|
| Be sure to quote properly both the @var{macro-body} @emph{and} the
| @var{macro-name}, to avoid any problems if the macro happens to have
| been previously defined.
|
| Each macro should have a header comment which gives its prototype, and a
| brief description. When arguments have default values, display them in
| the prototype. For instance:
|
| @example
| # AC_MSG_ERROR(ERROR, [EXIT-STATUS = 1])
| # --------------------------------------
| define([AC_MSG_ERROR],
| [@{ _AC_ECHO([configure: error: $1], 2); exit m4_default([$2], 1); @}])
| @end example
|
| Comments about the macro should be left in the header comment. Most
| other comments should make their way into @file{configure}, hence just
| keep using @samp{#} to introduce comments.
|
| @cindex @code{dnl}
| If you have some very special comments about pure M4 code, comments
| which make no sense in @file{configure} and in the header comment, then
| use the builtin @code{dnl}: it causes @code{m4} to discard the text
| through the next newline.
|
| Keep in mind that @code{dnl} is rarely needed to introduce comments,
| rather it is useful to get rid of the newlines following macros that
| produce no output, such as @code{AC_REQUIRE}.
|
And
| @node Coding Style, , Obsoleting Macros, Writing Macros
| @section Coding Style
|
| The Autoconf macros follow a strict coding style. You are encouraged to
| follow this style, especially if you intend to distribute your macro,
| either by contributing it to Autoconf itself, or via other means.
|
| The first requirement is to pay great attention to the quotation, for
| more details, see @ref{Autoconf Language}, and @ref{Quoting}.
|
| Do not try to invent new interfaces, it is likely that there is a macro
| in Autoconf which resembles the macro you are defining: try to stick to
| this existing interface (order of arguments, default values etc.). We
| @emph{are} conscious that some of these interfaces are not perfect,
| nevertheless, when harmless, homogeneity should be preferred over
| creativity.
|
| Be careful about clashes both between M4 symbols, and shell variables.
|
| If you stick to the suggested M4 naming scheme (@pxref{Macro Names}) you
| are unlikely to generate conflicts. Nevertheless, when you need to set
| a special value, @emph{avoid using a regular macro name}, rather, use an
| ``impossible'' name. For instance, up to version 2.13, the macro
| @code{AC_SUBST} used to remember what @var{symbol}s were already defined
| by setting @code{AC_SUBST_@var{symbol}}, which is a regular macro name.
| But since there is a macro named @code{AC_SUBST_FILE} it was just
| impossible to @samp{AC_SUBST(FILE)}! In this case,
| @code{AC_SUBST(@var{symbol})} or @code{_AC_SUBST(@var{symbol})} should
| have been used (yes, with the parentheses). Or better yet, using high
| level macros such as @code{AC_EXPAND_ONCE}.
|
| No Autoconf macro should ever enter the user variables name space, i.e.,
| but the variables which are the actual result of running the macro, all
| the shell variables should start with @code{ac_}. In addition, small
| macros or any macro which is likely to be embedded in other macros
| should be careful not to use obvious names.
|
| @cindex @code{dnl}
| Do not use @code{dnl} to introduce comments: most of the comments you
| are likely to write are either header comments which are not output
| anyway, or comments that should make their way into @file{configure}.
| There are exceptional cases where you do want to comment special M4
| constructs, in which case @code{dnl} is right, but keep in mind that it
| is unlikely.
|
| M4 ignores the leading spaces before each argument, use this feature to
| indent in such a way that arguments are (more or less) aligned with the
| opening parenthesis of the macro being called. For instance, instead of
|
| @example
| AC_CACHE_CHECK(for EMX OS/2 environment,
| ac_cv_emxos2,
| [AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, [return __EMX__;])],
| [ac_cv_emxos2=yes], [ac_cv_emxos2=no])])
| @end example
|
| @noindent
| write
|
| @example
| AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2],
| [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])],
| [ac_cv_emxos2=yes],
| [ac_cv_emxos2=no])])
| @end example
|
| @noindent
| or even
|
| @example
| AC_CACHE_CHECK([for EMX OS/2 environment],
| [ac_cv_emxos2],
| [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([],
| [return __EMX__;])],
| [ac_cv_emxos2=yes],
| [ac_cv_emxos2=no])])
| @end example
|
| When using @code{AC_TRY_RUN} or any macro which cannot work when
| cross-compiling, provide a pessimistic value (typically @samp{no}).
|
| Feel free to use various tricks to avoid that auxiliary tools, such as
| syntax-highlighting editors, behave improperly. For instance, instead
| of
|
| @example
| patsubst([$1], [$"])
| @end example
|
| @noindent
| use
|
| @example
| patsubst([$1], [$""])
| @end example
|
| @noindent
| so that Emacsen do not open a endless ``string'' at the first quote.
| For the same reasons, avoid
|
| @example
| test $[#] != 0
| @end example
|
| @noindent
| but use
|
| @example
| test $[@@%:@@] != 0
| @end example
|
| @noindent
| otherwise, the closing bracket would be hidden inside a @samp{#}-comment
| breaking the bracket matching highlighting from Emacsen. Note the
| preferred style to escape from M4: @samp{$[1]}, @samp{$[@@]} etc. Do
| not escape when it is unneeded. Common examples of useless quotation
| are @samp{[$]$1} (write @samp{$$1}), @samp{[$]var} (use @samp{$var}),
| etc. If you add portability issues to the picture, you'll prefer
| @samp{$@{1+"$[@@]"@}} to @samp{"[$]@@"}, and you'll prefer do something
| better than hacking Autoconf @code{:-)}.
|
| When using @command{sed}, don't use @option{-e} but for indenting
| purpose. With the @code{s} command, the preferred separator is @samp{/}
| unless @samp{/} itself is used in the command, in which case you should
| use @samp{,}.
|
| @xref{Macro Definitions}, for details on how to define a macro. If a
| macro doesn't use @code{AC_REQUIRE} and it is expected never to be the
| object of an @code{AC_REQUIRE} directive, then use @code{define}. In
| case of doubt, use @code{AC_DEFUN}. All the @code{AC_REQUIRE}
| statements should be at the beginning of the macro, @code{dnl}'ed.
|
| Unless the macro is short, try to leave the closing @samp{])} at the
| beginning of a line, followed by a comment which repeats the name of the
| macro being defined. If you want to avoid the new-line which is then
| introduced, use @code{dnl}. Better yet, use @samp{[]dnl} @emph{even}
| behind of parenthesis, since because of the M4 evaluation rule the
| @samp{dnl} might be appended to the result of the evaluation of the
| macro before it (e.g., leading to @samp{yesdnl} instead of @samp{yes}).
| For instance, instead of:
|
| @example
| AC_DEFUN([AC_PATH_X],
| [AC_MSG_CHECKING(for X)
| AC_REQUIRE_CPP()
| @r{# cut...}
| AC_MSG_RESULT([libraries $x_libraries, headers $x_includes])
| fi])
| @end example
|
| @noindent
| write:
|
| @example
| AC_DEFUN([AC_PATH_X],
| [AC_REQUIRE_CPP()dnl
| AC_MSG_CHECKING(for X)
| @r{# cut...}
| AC_MSG_RESULT([libraries $x_libraries, headers $x_includes])
| fi[]dnl
| ])# AC_PATH_X
| @end example
|
| If the macro is long, try to split it into logical chunks. Typically,
| macros which check for a bug in a function and prepare its
| @code{AC_LIBOBJ} replacement should have an auxiliary macro to perform
| this setup.
|
| Do not hesitate to introduce auxiliary macros to factor your code.
|
| In order to highlight this coding style, here is a macro written the old
| way:
|
| @example
| dnl Check for EMX on OS/2.
| dnl _AC_EMXOS2
| AC_DEFUN(_AC_EMXOS2,
| [AC_CACHE_CHECK(for EMX OS/2 environment, ac_cv_emxos2,
| [AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, return __EMX__;)],
| ac_cv_emxos2=yes, ac_cv_emxos2=no)])
| test "$ac_cv_emxos2" = yes && EMXOS2=yes])
| @end example
|
| @noindent
| and the new way:
|
| @example
| # _AC_EMXOS2
| # ----------
| # Check for EMX on OS/2.
| define([_AC_EMXOS2],
| [AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2],
| [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])],
| [ac_cv_emxos2=yes],
| [ac_cv_emxos2=no])])
| test "$ac_cv_emxos2" = yes && EMXOS2=yes[]dnl
| ])# _AC_EMXOS2
| @end example
