-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
According to Bruno Haible on 5/23/2009 6:35 AM:
> Hi Eric, Ralf,
>
> For about 15 years, writing and debugging autoconf macros has been very hard
> for me. I've come to partially understand how m4 internally works, thanks to
> Eric's new documentation in the m4 manual, and due to the ability of "seeing"
> what m4 does when I call it directly, on the command line.
>
> - m4 has no primitives for creating external files.
True, but m4sugar has m4_file_append to append to an arbitrary file (oh,
but that macro is still undocumented).
>
> Here comes the trick: If, say, I want to see the definition of AM_INIT_AUTOMAKE
> at a particular point, I do:
>
> ------------------------------------------------------------------
> m4_syscmd([cat 1>&2 <<\EOT
>
> Here comes the definition of AM_INIT_AUTOMAKE:]
> m4_defn([AM_INIT_AUTOMAKE])
> [EOT])
> ------------------------------------------------------------------
Very similar to m4_file_append, except that it outputs to stderr rather
than appending to a file. For that matter, m4_errprint does that, without
having to spawn a subprocess.
>
> Benefits:
> - Offers an unobstructed view to the m4 state.
> - Any m4 expression, any number of m4 expressions can be printed.
> - The results appear on the screen immediately. No need to open a file
> to view them.
>
> Could something like this be documented in the autoconf manual?
I think so. Done with the patch below.
>
> Or, alternatively, document how to use --trace for the same purpose?
Hmm, --trace shows arguments, not definition, but it also has a place.
- --
Don't work too hard, make some time for fun as well!
Eric Blake ebb9@xxxxxxx
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (Cygwin)
Comment: Public key at home.comcast.net/~ericblake/eblake.gpg
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org
iEYEARECAAYFAkprAGIACgkQ84KuGfSFAYA4eQCfYi4FiHOObzCQSt4xdr/McAHk
3d4An3YP9iUs0pzoNwtXC4voh2Ww1MkF
=bRA9
-----END PGP SIGNATURE-----
>From de8a83c3e977937782ef3ce686909d7fa7538e81 Mon Sep 17 00:00:00 2001
From: Eric Blake <ebb9@xxxxxxx>
Date: Sat, 25 Jul 2009 06:51:59 -0600
Subject: [PATCH] Document some autom4te debugging tips.
* doc/autoconf.texi (Debugging via autom4te): New node.
Suggested by Bruno Haible.
Signed-off-by: Eric Blake <ebb9@xxxxxxx>
---
ChangeLog | 4 +++
doc/autoconf.texi | 62 +++++++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 66 insertions(+), 0 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index b8b3be1..4ed5149 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,9 @@
2009-07-25 Eric Blake <ebb9@xxxxxxx>
+ Document some autom4te debugging tips.
+ * doc/autoconf.texi (Debugging via autom4te): New node.
+ Suggested by Bruno Haible.
+
Fix font-lock.
* configure.ac (ac_cv_unsupported_fs_chars): Make editing easier.
diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index 34df30b..0b61e35 100644
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -430,6 +430,7 @@ Top
* M4 Quotation:: Protecting macros from unwanted expansion
* Using autom4te:: The Autoconf executables backbone
* Programming in M4sugar:: Convenient pure M4 macros
+* Debugging via autom4te:: Figuring out what M4 was doing
Programming in M4sh
@@ -9414,6 +9415,7 @@ Programming in M4
* M4 Quotation:: Protecting macros from unwanted expansion
* Using autom4te:: The Autoconf executables backbone
* Programming in M4sugar:: Convenient pure M4 macros
+* Debugging via autom4te:: Figuring out what M4 was doing
@end menu
@node M4 Quotation
@@ -12426,6 +12428,66 @@ Forbidden Patterns
@code{m4_pattern_forbid} pattern.
@end defmac
+@node Debugging via autom4te
+@section Debugging via autom4te
+@cindex debugging tips
+@cindex autom4te debugging tips
+@cindex m4sugar debugging tips
+At times, it is desirable to see what was happening inside m4, to see
+why output was not matching expectations. However, post-processing done
+by @command{autom4te} means that directly using the m4 builtin
+@code{m4_traceon} is likely to interfere with operation. Also, frequent
+diversion changes and the concept of forbidden tokens make it difficult
+to use @code{m4_defn} to generate inline comments in the final output.
+
+There are a couple of tools to help with this. One is the use of the
+@option{--trace} option provided by @command{autom4te} (as well as each
+of the programs that wrap @command{autom4te}, such as
+@command{autoconf}), in order to inspect when a macro is called and with
+which arguments. For example, when this paragraph was written, the
+autoconf version could be found by:
+
+@example
+$ @kbd{autoconf --trace=AC_INIT}
+configure.ac:23:AC_INIT:GNU Autoconf:2.63b.95-3963:bug-autoconf@@gnu.org
+$ @kbd{autoconf --trace='AC_INIT:version is $2'}
+version is 2.63b.95-3963
+@end example
+
+Another trick is using @code{m4_errprintn} to output debugging messages
+to standard error with no further m4 expansion, and without interfering
+with the post-processing done to standard output. For example, contrast
+these two attempts to learn how @code{m4_dquote} is implemented:
+
+@smallexample
+$ @kbd{cat <<\EOF > foo.m4}
+m4_init
+try one: [m4_dquote is ]m4_defn([m4_dquote])
+m4_divert([0])dnl
+try two: [m4_dquote is ]m4_defn([m4_dquote])
+m4_dquote([hi])
+EOF
+$ @kbd{autom4te --language=m4sugar -o foo foo.m4}
+foo.m4:2: error: possibly undefined macro: m4_dquote
+ If this token and others are legitimate, please use m4_pattern_allow.
+ See the Autoconf documentation.
+$ @kbd{cat foo}
+try two: m4_dquote is [$@@]
+[hi]
+$ @kbd{cat <<\EOF > foo.m4}
+m4_init
+m4_errprintn([try one: m4_dquote is ]m4_defn([m4_dquote]))
+m4_divert([0])dnl
+m4_errprintn([try two: m4_dquote is ]m4_defn([m4_dquote]))dnl
+m4_dquote([hi])
+EOF
+$ @kbd{autom4te --language=m4sugar foo.m4}
+try one: m4_dquote is [$@@]
+try two: m4_dquote is [$@@]
+$ @kbd{cat foo}
+[hi]
+@end smallexample
+
@node Programming in M4sh
@chapter Programming in M4sh
--
1.6.3.3.334.g916e1
_______________________________________________
Autoconf mailing list
Autoconf@xxxxxxx
http://lists.gnu.org/mailman/listinfo/autoconf
