How to debug macros and input

When writing macros for m4, most of the time they woould not work as intended (as is the case with most programming languages). There is a little support for macro debugging in m4.

• Dumpdef: Displaying macro definitions
• Trace: Tracing macro calls
• Debug Levels: Controlling debugging output
• Debug Output: Saving debugging output

Displaying macro definitions

If you want to see what a name expands into, you can use the builtin dumpdef:

dumpdef(...)

which accepts any number of arguments. If called without any arguments, it displays the definitions of all known names, otherwise it displays the definitions of the names given. The output is printed directly on the standard error output.

The expansion of dumpdef is void.

define(`foo', `Hello world.')
=>
dumpdef(`foo')
error-->foo:	`Hello world.'
=>
dumpdef(`define')
error-->define:	<define>
=>

The last example shows how builtin macros definitions are displayed.

See section Controlling debugging output for information on controlling the details of the display.

Tracing macro calls

It is possible to trace macro calls and expansions through the builtins traceon and traceoff:

traceon(...)
traceoff(...)

When called without any arguments, traceon and traceoff will turn tracing on and off, respectively, for all defined macros. When called with arguments, only the named macros are affected.

The expansion of traceon and traceoff is void.

Whenever a traced macro is called and the arguments have been collected, the call is displayed. If the expansion of the macro call is not void, the expansion can be displayed after the call. The output is printed directly on the standard error output.

define(`foo', `Hello World.')
=>
define(`echo', `$@')
=>
traceon(`foo', `echo')
=>
foo
error-->m4trace: -1- foo -> `Hello World.'
=>Hello World.
echo(gnus, and gnats)
error-->m4trace: -1- echo(`gnus', `and gnats') -> "gnus',`and gnats"
=>gnus,and gnats

The number between dashes is the depth of the expansion. It is one most of the time, signifying an expansion at the outermost level, but it increases when macro arguments contain unquoted macro calls.

See section Controlling debugging output for information on controlling the details of the display.

Controlling debugging output

The `-d' option to m4 controls the amount of details presented, when using the macros described in the preceding sections.

The flags following the option can be one or more of the following:

t

Trace all macro calls made in this invocation of m4.

a

Show the actual arguments in each macro call. This applies to all macro calls if the `t' flag is used, otherwise only the macros covered by calls of traceon.

e

Show the expansion of each macro call, if it is not void. This applies to all macro calls if the `t' flag is used, otherwise only the macros covered by calls of traceon.

q

Quote actual arguments and macro expansions in the display with the current quotes.

c

Show several trace lines for each macro call. A line is shown when the macro is seen, but before the arguments are collected; a second line when the arguments have been collected and a third line after the call has completed.

x

Add a unique `macro call id' to each line of the trace output. This is useful in connection with the `c' flag above.

f

Show the name of the current input file in each trace output line.

l

Show the the current input line number in each trace output line.

p

Print a message when a named file is found through the path search mecanism (see section Searching for include files), giving the actual filename used.

i

Print a message each time the current input file is changed, giving file name and input line number.

V

A shorthand for all of the above flags.

If no flags are specified with the `-d' option, the default is `aeq'. The examples in the previous two sections assumed the default flags.

There is a builtin macro debugmode, which allows on-the-fly control of the debugging output format:

debugmode(opt flags)

The argument flags should be a subset of the letters listed above. As special cases, if the argument starts with a `+', the flags are added to the current debug flags, and if it starts with a `-', they are removed. If no argument is present, the debugging flags are set to zero (as if no `-d' was given), and with an empty argument the flags are reset to the default.

Saving debugging output

Debug and tracing output can be redirected to files using either the `-o' option to m4, or with the builtin macro debugfile:

debugfile(opt filename)

will send all further debug and trace output to filename. If filename is empty, debug and trace output are discarded and if debugfile is called without any arguments, debug and trace output are sent to the standard error output.