File: m4.info,  Node: Debug Levels,  Next: Debug Output,  Prev: Trace,  Up: Debugging

7.3 Controlling debugging output
================================

The ‘-d’ option to ‘m4’ (or ‘--debug’, *note Invoking m4: Debugging
options.) controls the amount of details presented in three categories
of output.  Trace output is requested by ‘traceon’ (*note 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’
(*note 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’.  Arguments are subject to length truncation specified by
     the command line option ‘--arglength’ (or ‘-l’).

‘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’.  The
     expansion is subject to length truncation specified by the command
     line option ‘--arglength’ (or ‘-l’).

‘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 (*note 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:

 -- Builtin: debugmode([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, all debugging flags are
     cleared (as if no ‘-d’ was given), and with an empty argument the
     flags are reset to the default of ‘aeq’.

     The expansion of ‘debugmode’ is void.

     $ 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

   The following example demonstrates the behavior of length truncation,
when specified on the command line.  Note that each argument and the
final result are individually truncated.  Also, the special tokens for
builtin functions are not truncated.

     $ m4 -d -l 6
     define(`echo', `$@')debugmode(`+t')
     ⇒
     echo(`1', `long string')
     error→m4trace: -1- echo(`1', `long s...') -> ``1',`l...'
     ⇒1,long string
     indir(`echo', defn(`changequote'))
     error→m4trace: -2- defn(`change...')
     error→m4trace: -1- indir(`echo', ) -> ``''
     ⇒

   This example shows the effects of the debug flags that are not
related to macro tracing.

     $ m4 -dip -I examples
     error→m4debug: input read from stdin
     include(`foo')dnl
     error→m4debug: path search for `foo' found `examples/foo'
     error→m4debug: input read from examples/foo
     ⇒bar
     error→m4debug: input reverted to stdin, line 1
     ^D
     error→m4debug: input exhausted