Re: a debugging trick: how to peek into m4's processing

[Eric Blake]

-----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             address@hidden
-----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 <address@hidden>
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 <address@hidden>
---
 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  <address@hidden>

+       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

address@hidden Debugging via autom4te
address@hidden Debugging via autom4te
address@hidden debugging tips
address@hidden autom4te debugging tips
address@hidden 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
address@hidden 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
address@hidden option provided by @command{autom4te} (as well as each
+of the programs that wrap @command{autom4te}, such as
address@hidden), 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:
+
address@hidden
+$ @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
address@hidden 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:
+
address@hidden
+$ @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]
address@hidden smallexample
+
 @node Programming in M4sh
 @chapter Programming in M4sh

-- 
1.6.3.3.334.g916e1