m4: Debug Levels
1
1 7.3 Controlling debugging output
1 ================================
1
11 The '-d' option to 'm4' (or '--debug', ⇒Invoking m4 Debugging
options.) controls the amount of details presented in three categories
1 of output. Trace output is requested by 'traceon' (⇒Trace), and
1 each line is prefixed by 'm4trace:' in relation to a macro invocation.
1 Debug output tracks useful events not associated with a macro
1 invocation, and each line is prefixed by 'm4debug:'. Finally, 'dumpdef'
1 (⇒Dumpdef) output is affected, with no prefix added to the output
1 lines.
1
1 The FLAGS following the option can be one or more of the following:
1
1 'a'
1 In trace output, show the actual arguments that were collected
1 before invoking the macro. This applies to all macro calls if the
1 't' flag is used, otherwise only the macros covered by calls of
1 'traceon'. Arguments are subject to length truncation specified by
1 the command line option '--arglength' (or '-l').
1
1 'c'
1 In trace output, show several trace lines for each macro call. A
1 line is shown when the macro is seen, but before the arguments are
1 collected; a second line when the arguments have been collected and
1 a third line after the call has completed.
1
1 'e'
1 In trace output, show the expansion of each macro call, if it is
1 not void. This applies to all macro calls if the 't' flag is used,
1 otherwise only the macros covered by calls of 'traceon'. The
1 expansion is subject to length truncation specified by the command
1 line option '--arglength' (or '-l').
1
1 'f'
1 In debug and trace output, include the name of the current input
1 file in the output line.
1
1 'i'
1 In debug output, print a message each time the current input file
1 is changed.
1
1 'l'
1 In debug and trace output, include the current input line number in
1 the output line.
1
1 'p'
1 In debug output, print a message when a named file is found through
1 the path search mechanism (⇒Search Path), giving the actual
1 file name used.
1
1 'q'
1 In trace and dumpdef output, quote actual arguments and macro
1 expansions in the display with the current quotes. This is useful
1 in connection with the 'a' and 'e' flags above.
1
1 't'
1 In trace output, trace all macro calls made in this invocation of
1 'm4', regardless of the settings of 'traceon'.
1
1 'x'
1 In trace output, add a unique 'macro call id' to each line of the
1 trace output. This is useful in connection with the 'c' flag
1 above.
1
1 'V'
1 A shorthand for all of the above flags.
1
1 If no flags are specified with the '-d' option, the default is 'aeq'.
1 The examples throughout this manual assume the default flags.
1
1 There is a builtin macro 'debugmode', which allows on-the-fly control
1 of the debugging output format:
1
1 -- Builtin: debugmode ([FLAGS])
1 The argument FLAGS should be a subset of the letters listed above.
1 As special cases, if the argument starts with a '+', the flags are
1 added to the current debug flags, and if it starts with a '-', they
1 are removed. If no argument is present, all debugging flags are
1 cleared (as if no '-d' was given), and with an empty argument the
1 flags are reset to the default of 'aeq'.
1
1 The expansion of 'debugmode' is void.
1
1 $ m4
1 define(`foo', `FOO')
1 =>
1 traceon(`foo')
1 =>
1 debugmode()
1 =>
1 foo
1 error->m4trace: -1- foo -> `FOO'
1 =>FOO
1 debugmode
1 =>
1 foo
1 error->m4trace: -1- foo
1 =>FOO
1 debugmode(`+l')
1 =>
1 foo
1 error->m4trace:8: -1- foo
1 =>FOO
1
1 The following example demonstrates the behavior of length truncation,
1 when specified on the command line. Note that each argument and the
1 final result are individually truncated. Also, the special tokens for
1 builtin functions are not truncated.
1
1 $ m4 -d -l 6
1 define(`echo', `$@')debugmode(`+t')
1 =>
1 echo(`1', `long string')
1 error->m4trace: -1- echo(`1', `long s...') -> ``1',`l...'
1 =>1,long string
1 indir(`echo', defn(`changequote'))
1 error->m4trace: -2- defn(`change...')
1 error->m4trace: -1- indir(`echo', <changequote>) -> ``''
1 =>
1
1 This example shows the effects of the debug flags that are not
1 related to macro tracing.
1
1 $ m4 -dip -I examples
1 error->m4debug: input read from stdin
1 include(`foo')dnl
1 error->m4debug: path search for `foo' found `examples/foo'
1 error->m4debug: input read from examples/foo
1 =>bar
1 error->m4debug: input reverted to stdin, line 1
1 ^D
1 error->m4debug: input exhausted
1