Probably the most important debugging tool is the backtrace. When Nyquist encounters an error, it suspends execution and prints an error message. To find out where in the program the error occurred and how you got there, start by typing (bt)
. This will print out the last several function calls and their arguments, which is usually sufficient to see what is going on.
In order for (bt)
to work, you must have a couple of global variables set: *tracenable*
is ordinarily set to NIL
. If it is true, then a backtrace is automatically printed when an error occurs; *breakenable*
must be set to T
, as it enables the execution to be suspended when an error is encountered. If *breakenable*
is NIL
(false), then execution stops when an error occurs but the stack is not saved and you cannot get a backtrace. Finally, bt
is just a macro to save typing. The actual backtrace function is baktrace
, which takes an integer argument telling how many levels to print. All of these things are set up by default when you start Nyquist.
Since Nyquist sounds are executed with a lazy evaluation scheme, some errors are encountered when samples are being generated. In this case, it may not be clear which expression is in error. Sometimes, it is best to explore a function or set of functions by examining intermediate results. Any expression that yields a sound can be assigned to a variable and examined using one or more of: s-plot
, snd-print-tree
, and of course play
. The snd-print-tree
function prints a lot of detail about the inner representaion of the sound.
Another technique is to use low sample rates so that it is easier to plot results or look at samples directly. The calls:
(set-sound-srate 100) (set-control-srate 100)set the default sample rates to 100, which is too slow for audio, but useful for examining programs and results. The function
(snd-samples sound limit)will convert up to limit samples from sound into a Lisp array. This is another way to look at results in detail.
The trace
function is sometimes useful. It prints the name of a function and its arguments everytimg the function is called, and the result is printed when the function exits. To trace the osc function, type:
(trace osc)and to stop tracing, type
(untrace osc)
.
If a variable needs a value or a function is undefined, you can fix the error (by setting the variable or loading the function definition) and keep going. Use (co)
, short for (continue)
to reevaluate the variable or function and continue execution.
When you finish debugging a particular call, you can ``pop'' up to the top level by typing (top)
, a short name for (top-level)
.