7.3 Controlling debugging output

The -d option to m4 (or --debug, see Invoking m4) controls the amount of details presented in three categories of output. Trace output is requested by traceon (see Trace), and each line is prefixed by `m4trace:' in relation to a macro invocation. Debug output tracks useful events not associated with a macro invocation, and each line is prefixed by `m4debug:'. Finally, dumpdef (see Dumpdef) output is affected, with no prefix added to the output lines.

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

a

In trace output, show the actual arguments that were collected before invoking the macro. This applies to all macro calls if the `t' flag is used, otherwise only the macros covered by calls of traceon.

c

In trace output, 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.

e

In trace output, 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.

f

In debug and trace output, include the name of the current input file in the output line.

i

In debug output, print a message each time the current input file is changed.

l

In debug and trace output, include the current input line number in the output line.

p

In debug output, print a message when a named file is found through the path search mechanism (see Search Path), giving the actual file name used.

q

In trace and dumpdef output, quote actual arguments and macro expansions in the display with the current quotes. This is useful in connection with the `a' and `e' flags above.

t

In trace output, trace all macro calls made in this invocation of m4, regardless of the settings of traceon.

x

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

V

A shorthand for all of the above flags.

If no flags are specified with the -d option, the default is `aeq'. The examples throughout this manual assume the default flags.

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

     $ m4
     define(`foo', `FOO')
     =>
     traceon(`foo')
     =>
     debugmode()
     =>
     foo
     error-->m4trace: -1- foo -> `FOO'
     =>FOO
     debugmode
     =>
     foo
     error-->m4trace: -1- foo
     =>FOO
     debugmode(`+l')
     =>
     foo
     error-->m4trace:8: -1- foo
     =>FOO