5.4 debug-tpl options

The following options are often useful while debugging new templates. They specify limits that prevent the template from taking overly long or producing more output than expected.

loop-limit option.

This is the “limit on increment loops” option. This option takes a number argument ‘lim’. This option prevents runaway loops. For example, if you accidentally specify, "FOR x (for-from 1) (for-to -1) (for-by 1)", it will take a long time to finish. If you do have more than 256 entries in tables, you will need to specify a new limit with this option.

timeout option (-t).

This is the “limit server shell operations to seconds” option. This option takes a number argument ‘SECONDS’.

This option has some usage constraints. It:

• must be compiled in by defining SHELL_ENABLED during the compilation.

AutoGen works with a shell server process. Most normal commands will complete in less than 10 seconds. If, however, your commands need more time than this, use this option.

The valid range is 0 to 3600 seconds (1 hour). Zero will disable the server time limit.

trace option.

This is the “tracing level of detail” option. This option takes a keyword argument ‘level’.

This option has some usage constraints. It:

• This option takes a keyword as its argument. The argument sets an enumeration value that can be tested by comparing the option value macro (OPT_VALUE_TRACE). The available keywords are:

  nothing debug-message server-shell templates block-macros expressions everything

  or their numeric equivalent.

This option will cause AutoGen to display a trace of its template processing. There are six levels, each level including messages from the previous levels:

‘nothing’

Does no tracing at all (default)

‘debug-message’

Print messages from the "DEBUG" AutoGen macro (see section DEBUG - Print debug message to trace output).

‘server-shell’

Traces all input and output to the server shell. This includes a shell "independent" initialization script about 30 lines long. Its output is discarded and not inserted into any template.

‘templates’

Traces the invocation of DEFINEd macros and INCLUDEs

‘block-macros’

Traces all block macros. The above, plus IF, FOR, CASE and WHILE.

‘expressions’

Displays the results of expression evaluations.

‘everything’

Displays the invocation of every AutoGen macro, even TEXT macros (i.e. the text outside of macro quotes). Additionally, if you rebuild the “expr.ini” file with debugging enabled, then all calls to AutoGen defined scheme functions will also get logged:

cd ${top_builddir}/agen5 DEBUG_ENABLED=true bash bootstrap.dir expr.ini make CFLAGS='-g -DDEBUG_ENABLED=1'

Be aware that you cannot rebuild this source in this way without first having installed the autogen executable in your search path. Because of this, "expr.ini" is in the distributed source list, and not in the dependencies.

trace-out option.

This is the “tracing output file or filter” option. This option takes a string argument ‘file’. The output specified may be a file name, a file that is appended to, or, if the option argument begins with the pipe operator (|), a command that will receive the tracing output as standard in. For example, --traceout='| less' will run the trace output through the less program. Appending to a file is specified by preceding the file name with two greater-than characters (>>).

show-defs option.

This is the “show the definition tree” option.

This option has some usage constraints. It:

• must be compiled in by defining DEBUG_ENABLED during the compilation.
• may not be preset with environment variables or configuration (rc/ini) files.

This will print out the complete definition tree before processing the template.

used-defines option.

This is the “show the definitions used” option.

This option has some usage constraints. It:

• may not be preset with environment variables or configuration (rc/ini) files.

This will print out the names of definition values searched for during the processing of the template, whether actually found or not. There may be other referenced definitions in a template in portions of the template not evaluated. Some of the names listed may be computed names and others AutoGen macro arguments. This is not a means for producing a definitive, all-encompassing list of all and only the values used from a definition file. This is intended as an aid to template documentation only.

core option (-C).

This is the “leave a core dump on a failure exit” option.

This option has some usage constraints. It:

• must be compiled in by defining HAVE_SYS_RESOURCE_H during the compilation.

Many systems default to a zero sized core limit. If the system has the sys/resource.h header and if this option is supplied, then in the failure exit path, autogen will attempt to set the soft core limit to whatever the hard core limit is. If that does not work, then an administrator must raise the hard core size limit.

This document was generated by Bruce Korb on August 21, 2015 using texi2html 1.82.