diff options
Diffstat (limited to 'doc/autoconf.texi')
-rw-r--r-- | doc/autoconf.texi | 64 |
1 files changed, 44 insertions, 20 deletions
diff --git a/doc/autoconf.texi b/doc/autoconf.texi index dea85e4a..9f05cee8 100644 --- a/doc/autoconf.texi +++ b/doc/autoconf.texi @@ -14888,29 +14888,53 @@ with their modern implementation. Autoconf provides a simple means to obsolete a macro. @anchor{AU_DEFUN} -@defmac AU_DEFUN (@var{old-macro}, @var{implementation}, @ovar{message}) +@defmac AU_DEFUN (@var{old-macro}, @var{implementation}, @ovar{message}, @ovar{silent}) @auindex{DEFUN} -Define @var{old-macro} as @var{implementation}. The only difference -with @code{AC_DEFUN} is that the user is warned that -@var{old-macro} is now obsolete. - -If she then uses @command{autoupdate}, the call to @var{old-macro} is -replaced by the modern @var{implementation}. @var{message} should -include information on what to do after running @command{autoupdate}; -@command{autoupdate} prints it as a warning, and includes it -in the updated @file{configure.ac} file. +Define @var{old-macro} as @var{implementation}, just like +@code{AC_DEFUN}, but also declare @var{old-macro} to be obsolete. +When @command{autoupdate} is run, occurrences of @var{old-macro} will +be replaced by the text of @var{implementation} in the updated +@file{configure.ac} file. + +If a simple textual replacement is not enough to finish the job of +updating a @file{configure.ac} to modern style, provide instructions for +whatever additional manual work is required as @var{message}. These +instructions will be printed by @command{autoupdate}, and embedded in the +updated @file{configure.ac} file, next to the text of @var{implementation}. + +Normally, @command{autoconf} will also issue a warning (in the +``obsolete'' category) when it expands @var{old-macro}. This warning +does not include @var{message}; it only advises the maintainer to run +@command{autoupdate}. If it is inappropriate to issue this warning, set +the @var{silent} argument to the word @code{silent}. One might want to +use a silent @code{AU_DEFUN} when @var{old-macro} is used in a +widely-distributed third-party macro. If that macro's maintainers are +aware of the need to update their code, it's unnecessary to nag all +of the transitive users of @var{old-macro} as well. This capability +was added to @code{AU_DEFUN} in Autoconf 2.70; older versions of +autoconf will ignore the @var{silent} argument and issue the warning +anyway. + +@strong{Caution:} If @var{implementation} contains M4 or M4sugar macros, +they will be evaluated when @command{autoupdate} is run, not emitted +verbatim like the rest of @var{implementation}. This cannot be avoided +with extra quotation, because then @var{old-macro} will not work when +it is called normally. See the definition of @code{AC_FOREACH} in +@file{general.m4} for a workaround. +@end defmac + +@defmac AU_ALIAS (@var{old-name}, @var{new-name}, @ovar{silent}) +@auindex{ALIAS} +A shorthand version of @code{AU_DEFUN}, to be used when a macro has +simply been renamed. @command{autoupdate} will replace calls to +@var{old-name} with calls to @var{new-name}, keeping any arguments +intact. No instructions for additional manual work will be printed. -The details of this macro are hairy: if @command{autoconf} encounters an -@code{AU_DEFUN}ed macro, all macros inside its second argument are expanded -as usual. However, when @command{autoupdate} is run, only M4 and M4sugar -macros are expanded here, while all other macros are disabled and -appear literally in the updated @file{configure.ac}. -@end defmac +The @var{silent} argument works the same as the @var{silent} argument +to @code{AU_DEFUN}. It was added to @code{AU_ALIAS} in Autoconf 2.70. -@defmac AU_ALIAS (@var{old-name}, @var{new-name}) -@auindex{ALIAS} -Used if the @var{old-name} is to be replaced by a call to @var{new-macro} -with the same parameters. This happens for example if the macro was renamed. +@strong{Caution:} @code{AU_ALIAS} cannot be used when @var{new-name} is +an M4 or M4sugar macro. See above. @end defmac @node Coding Style |