From: Matěj Týč Date: Thu, 16 Apr 2015 21:00:24 +0000 (+0200) Subject: m4_pattern_forbid: better documentation X-Git-Tag: v2.69b~92 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=d2f0ec870814233f21d9f3404ef60b8c65b47cad;p=thirdparty%2Fautoconf.git m4_pattern_forbid: better documentation Give a more concrete description of what the m4_pattern_forbid thingy that pretends it is a macro accepts as an argument. Copyright-paper-exempt: Yes Signed-off-by: Eric Blake --- diff --git a/doc/autoconf.texi b/doc/autoconf.texi index bab87ad2..b2ca0ae5 100644 --- a/doc/autoconf.texi +++ b/doc/autoconf.texi @@ -13370,7 +13370,13 @@ patterns to the list. @defmac m4_pattern_forbid (@var{pattern}) @msindex{pattern_forbid} -Declare that no token matching @var{pattern} must be found in the output. +Declare that no token matching @var{pattern} must be found in the +output. The output file is (temporarily) split into one word per line +as part of the @command{autom4te} post-processing, with each line (and +therefore word) then being checked against the Perl regular expression +@var{pattern}. If the regular expression matches, and +@code{m4_pattern_allow} does not also match, then an error is raised. + Comments are not checked; this can be a problem if, for instance, you have some macro left unexpanded after an @samp{#include}. No consensus is currently found in the Autoconf community, as some people consider it @@ -13379,6 +13385,11 @@ the authors of this documentation: input, such as macros, should be documented by @samp{dnl} comments; reserving @samp{#}-comments to document the output). +As an example, if you define your own macros that begin with @samp{M_} +and are composed from capital letters and underscores, the specification +of @code{m4_pattern_forbid([^M_[A-Z_]+])} will ensure all your macros +are expanded when not used in comments. + As an example of a common use of this macro, consider what happens in packages that want to use the @command{pkg-config} script via the third-party @code{PKG_CHECK_MODULES} macro. By default, if a developer @@ -13386,7 +13397,7 @@ checks out the development tree but has not yet installed the pkg-config macros locally, they can manage to successfully run @command{autoconf} on the package, but the resulting @file{configure} file will likely result in a confusing shell message about a syntax error on the line -mentioning the unexpanded PKG_CHECK_MODULES macro. On the other hand, +mentioning the unexpanded @code{PKG_CHECK_MODULES} macro. On the other hand, if @file{configure.ac} includes @code{m4_pattern_forbid([^PKG_])}, the missing pkg-config macros will be detected immediately without allowing @command{autoconf} to succeed. diff --git a/lib/m4sugar/m4sugar.m4 b/lib/m4sugar/m4sugar.m4 index f6be8bcd..9bdafd59 100644 --- a/lib/m4sugar/m4sugar.m4 +++ b/lib/m4sugar/m4sugar.m4 @@ -2000,7 +2000,7 @@ m4_define([_m4_defun_once], # m4_pattern_forbid(ERE, [WHY]) # ----------------------------- -# Declare that no token matching the forbidden extended regular +# Declare that no token matching the forbidden perl extended regular # expression ERE should be seen in the output unless... m4_define([m4_pattern_forbid], []) @@ -2008,7 +2008,7 @@ m4_define([m4_pattern_forbid], []) # m4_pattern_allow(ERE) # --------------------- # ... that token also matches the allowed extended regular expression ERE. -# Both used via traces. +# Both used via traces, by autom4te post-processing. m4_define([m4_pattern_allow], [])