Next: , Previous: Dumpdef, Up: Debugging

6.2 Tracing macro calls

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

— Builtin: traceon (...)
— Builtin: 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, whether or not they are currently defined.

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 to the current debug file (usually standard error). 

     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. The maximum number that will appear between dashes is controlled by the option --nesting-limit (see Invoking m4).

Tracing by name is an attribute that is preserved whether the macro is defined or not. This allows the -t option to select macros to trace before those macros are defined. 

     traceoff(`foo')
     =>
     traceon(`foo')
     =>
     foo
     =>foo
     define(`foo', `bar')
     =>
     foo
     error-->m4trace: -1- foo -> `bar'
     =>bar
     undefine(`foo')
     =>
     ifdef(`foo', `yes', `no')
     =>no
     indir(`foo')
     error-->m4:stdin:8: undefined macro `foo'
     =>
     define(`foo', `blah')
     =>
     foo
     error-->m4trace: -1- foo -> `blah'
     =>blah
     traceoff
     =>
     foo
     =>blah

Tracing even works on builtins. However, defn (see Defn) does not transfer tracing status. 

     traceon(`eval', `m4_divnum')
     =>
     define(`m4_eval', defn(`eval'))
     =>
     define(`m4_divnum', defn(`divnum'))
     =>
     eval(divnum)
     error-->m4trace: -1- eval(`0') -> `0'
     =>0
     m4_eval(m4_divnum)
     error-->m4trace: -2- m4_divnum -> `0'
     =>0

See Debug Levels, for information on controlling the details of the display.