The autoconf manual doesn't mention any examples of actually
using m4_pattern_forbid. Yet this is the perfect macro for
avoiding the all-too-common failure mode of configure dying with:
checking if libxml2 is present... ./configure: line 11586: syntax
error
near unexpected token `LIBXML2,'
./configure: line 11586: `PKG_CHECK_MODULES(LIBXML2, libxml-2.0>=
2.6.19,'
for developers that forgot to install pkg-config. While we don't
necessarily advertise the use of PKG_CHECK_MODULES, it is a
common enough situation that the manual should make it easier to
help developers learn about missing third-party macros.
Based on a mailing list report by Daniel Pocock:
http://lists.gnu.org/archive/html/autoconf/2014-01/msg00030.html
* doc/autoconf.texi (Forbidden Patterns): Add examples.
Signed-off-by: Eric Blake <eblake@xxxxxxxxxx>
---
No wonder it took us a couple of iterations to give you the
right advice - we didn't have good documentation. This patch
should give us something to point the next person to, when
encountering a similar situation.
doc/autoconf.texi | 17 +++++++++++++++++
1 file changed, 17 insertions(+)
diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index 6c374c0..ae2987a 100644
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -13373,6 +13373,18 @@ Forbidden Patterns
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 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 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, 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.
@end defmac
Of course, you might encounter exceptions to these generic rules, for
@@ -13382,6 +13394,11 @@ Forbidden Patterns
@msindex{pattern_allow}
Any token matching @var{pattern} is allowed, including if it matches an
@code{m4_pattern_forbid} pattern.
+
+For example, gnulib uses @code{m4_pattern_forbid([^gl_])} to reserve the
+@code{gl_} namespace for itself, but also uses
+@code{m4_pattern_allow([^gl_ES$])} to avoid a false negative on the
+valid locale name.
@end defmac
@node Debugging via autom4te
--
1.8.5.3
_______________________________________________
Autoconf mailing list
Autoconf@xxxxxxx
https://lists.gnu.org/mailman/listinfo/autoconf
