diff options
author | Eric Blake <eblake@redhat.com> | 2014-01-27 11:33:07 -0700 |
---|---|---|
committer | Eric Blake <eblake@redhat.com> | 2014-02-05 14:20:44 -0700 |
commit | e5d3c9621fbd23c5e2d62fdb19534ed1b5f3ab09 (patch) | |
tree | bf2e40cdcfb9889b0cd69a1573ce57d3d84e739c /doc/autoconf.texi | |
parent | 251d13ff2491e470f16569a9bb31123558ae84b2 (diff) | |
download | autoconf-e5d3c9621fbd23c5e2d62fdb19534ed1b5f3ab09.tar.gz |
doc: give an example of using the macro for pkg-config
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@redhat.com>
Diffstat (limited to 'doc/autoconf.texi')
-rw-r--r-- | doc/autoconf.texi | 17 |
1 files changed, 17 insertions, 0 deletions
diff --git a/doc/autoconf.texi b/doc/autoconf.texi index 6c374c07..6795fcb6 100644 --- a/doc/autoconf.texi +++ b/doc/autoconf.texi @@ -13373,6 +13373,18 @@ should be valid to name macros in comments (which doesn't make sense to 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 @@ instance you might have to refer to @samp{$m4_flags}. @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 |