[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

# 7. How to debug macros and input

When writing macros for `m4`, they often do not work as intended on the first try (as is the case with most programming languages). Fortunately, there is support for macro debugging in `m4`.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 7.1 Displaying macro definitions

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

Builtin: dumpdef ([names…])

  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 to the current debug file (usually standard error), and is sorted by name. If an unknown name is encountered, a warning is printed.

  The expansion of `dumpdef` is void.

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

The last example shows how builtin macros definitions are displayed. The definition that is dumped corresponds to what would occur if the macro were to be called at that point, even if other definitions are still live due to redefining a macro during argument collection.

    pushdef(`f', ``$0'1')pushdef(`f', ``$0'2')
    ⇒
    f(popdef(`f')dumpdef(`f'))
    error-->f: @c"$0'1'
    ⇒f2
    f(popdef(`f')dumpdef(`f'))
    error-->m4:stdin:3: undefined macro `f'
    ⇒f1

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

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 7.2 Tracing macro calls

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

Builtin: traceon ([names…])
Builtin: traceoff ([names…])

  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 macros listed in names 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 (defaulting to standard error, see section Saving debugging 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. The maximum number that will appear between dashes is controlled by the option ``--nesting-limit'` (see section 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 section Renaming macros) 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 section Controlling debugging output, for information on controlling the details of the display.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 7.3 Controlling debugging output

The ``-d'` option to `m4` (see section Invoking 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:

`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`.

`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.

`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`.

`f`

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

`i`

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

`l`

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

`p`

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

`q`

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

`t`

  Trace all macro calls made in this invocation of `m4`.

`x`

  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.

    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

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 7.4 Saving debugging output

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

Builtin: debugfile ([file])

  Sends all further debug and trace output to file, opened in append mode. If file is the empty string, debug and trace output are discarded. If `debugfile` is called without any arguments, debug and trace output are sent to standard error. This does not affect warnings, error messages, or `errprint` output, which are always sent to standard error. If file cannot be opened, the current debug file is unchanged, and an error is issued.

  The expansion of `debugfile` is void.

    traceon(`divnum')
    ⇒
    divnum(`extra')
    error-->m4:stdin:2: Warning: excess arguments to builtin `divnum' ignored
    error-->m4trace: -1- divnum(`extra') -> `0'
    ⇒0
    debugfile()
    ⇒
    divnum(`extra')
    error-->m4:stdin:4: Warning: excess arguments to builtin `divnum' ignored
    ⇒0
    debugfile
    ⇒
    divnum
    error-->m4trace: -1- divnum -> `0'
    ⇒0

[ << ] | [ >> ] |  |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

This document was generated by root on April, 16 2008 using texi2html 1.76.