Warning: This is the manual of the legacy Guile 2.0 series. You may want to read the manual of the current stable series instead.

6.25.3.4 Debug options

The behavior of the backtrace procedure and of the default error handler can be parameterized via the debug options.

Scheme Procedure: debug-options [setting]

Display the current settings of the debug options. If setting is omitted, only a short form of the current read options is printed. Otherwise if setting is the symbol help, a complete options description is displayed.

The set of available options, and their default values, may be had by invoking debug-options at the prompt.

scheme@(guile-user)>
backwards       no      Display backtrace in anti-chronological order.
width           79      Maximal width of backtrace.
depth           20      Maximal length of printed backtrace.
backtrace       yes     Show backtrace on error.
stack           1048576 Stack size limit (measured in words;
                        0 = no check). 
show-file-name  #t      Show file names and line numbers in backtraces
                        when not `#f'.  A value of `base' displays only
                        base names, while `#t' displays full names. 
warn-deprecated no      Warn when deprecated features are used.

The boolean options may be toggled with debug-enable and debug-disable. The non-boolean keywords option must be set using debug-set!.

Scheme Procedure: debug-enable option-name

Scheme Procedure: debug-disable option-name

Scheme Syntax: debug-set! option-name value

Modify the debug options. debug-enable should be used with boolean options and switches them on, debug-disable switches them off.

debug-set! can be used to set an option to a specific value. Due to historical oddities, it is a macro that expects an unquoted option name.

Stack overflow

Stack overflow errors are caused by a computation trying to use more stack space than has been enabled by the stack option. There are actually two kinds of stack that can overflow, the C stack and the Scheme stack.

Scheme stack overflows can occur if Scheme procedures recurse too far deeply. An example would be the following recursive loop:

scheme@(guile-user)> (let lp () (+ 1 (lp)))
<unnamed port>:8:17: In procedure vm-run:
<unnamed port>:8:17: VM: Stack overflow

The default stack size should allow for about 10000 frames or so, so one usually doesn’t hit this level of recursion. Unfortunately there is no way currently to make a VM with a bigger stack. If you are in this unfortunate situation, please file a bug, and in the meantime, rewrite your code to be tail-recursive (see Tail Calls).

The other limit you might hit would be C stack overflows. If you call a primitive procedure which then calls a Scheme procedure in a loop, you will consume C stack space. Guile tries to detect excessive consumption of C stack space, throwing an error when you have hit 80% of the process’ available stack (as allocated by the operating system), or 160 kilowords in the absence of a strict limit.

For example, looping through call-with-vm, a primitive that calls a thunk, gives us the following:

scheme@(guile-user)> (use-modules (system vm vm))
scheme@(guile-user)> (debug-set! stack 10000)
scheme@(guile-user)> (let lp () (call-with-vm (the-vm) lp))
ERROR: In procedure call-with-vm:
ERROR: Stack overflow

If you get an error like this, you can either try rewriting your code to use less stack space, or increase the maximum stack size. To increase the maximum stack size, use debug-set!, for example:

(debug-set! stack 200000)

But of course it’s better to have your code operate without so much resource consumption, avoiding loops through C trampolines.