Debugging Calc
--------------

A few commands exist to help in the debugging of Calc commands.
See Programming, to see the various ways that you can write
your own Calc commands.

The `Z T' (`calc-timing') command turns on and off a mode in which the
timing of slow commands is reported in the Trail.  Any Calc command
that takes two seconds or longer writes a line to the Trail showing
how many seconds it took.  This value is accurate only to within one
second.

All steps of executing a command are included; in particular, time
taken to format the result for display in the stack and trail is
counted.  Some prompts also count time taken waiting for them to be
answered, while others do not; this depends on the exact
implementation of the command.  For best results, if you are timing a
sequence that includes prompts or multiple commands, define a keyboard
macro to run the whole sequence at once.  Calc's `X' command (*Note
Keyboard Macros::) will then report the time taken to execute the
whole macro.

Another advantage of the `X' command is that while it is executing,
the stack and trail are not updated from step to step.  So if you
expect the output of your test sequence to leave a result that may
take a long time to format and you don't wish to count this formatting
time, end your sequence with a DEL keystroke to clear the result from
the stack.  When you run the sequence with `X', Calc will never bother
to format the large result.

Another thing `Z T' does is to increase the Emacs variable
`gc-cons-threshold' to a much higher value (two million; the usual
default in Calc is 250,000) for the duration of each command.  This
generally prevents garbage collection during the timing of the
command, though it may cause your Emacs process to grow abnormally
large.  (Garbage collection time is a major unpredictable factor in
the timing of Emacs operations.)

Another command that is useful when debugging your own Lisp extensions
to Calc is `M-x calc-pass-errors', which disables the error handler
that changes the "`max-lisp-eval-depth' exceeded" message to the much
more friendly "Computation got stuck or ran too long."  This handler
interferes with the Emacs Lisp debugger's `debug-on-error' mode.
Errors are reported in the handler itself rather than at the true
location of the error.  After you have executed `calc-pass-errors',
Lisp errors will be reported correctly but the user-friendly message
will be lost.