summaryrefslogtreecommitdiff
path: root/doc/ref/api-debug.texi
diff options
context:
space:
mode:
authorAndy Wingo <wingo@pobox.com>2010-10-01 11:47:53 +0200
committerAndy Wingo <wingo@pobox.com>2010-10-01 11:47:53 +0200
commit1cfdb1bbcadfdba7b83677e5b25772ff0f38163e (patch)
tree44686f3a7a1f6537d1650c528fdbee8ee3e84ab8 /doc/ref/api-debug.texi
parent84898084c0a56dbcf1e4753ae73d4462425cf9fa (diff)
downloadguile-1cfdb1bbcadfdba7b83677e5b25772ff0f38163e.tar.gz
finish cleaning out api-options.texi
* doc/ref/api-debug.texi (Debug on Error): Move debug options here (for now). Leave debug-options-interface undocumented. * doc/ref/api-options.texi (Runtime Options): Remove debug options. Link to the sections where the options documentation is now. Update the options example transcript.
Diffstat (limited to 'doc/ref/api-debug.texi')
-rw-r--r--doc/ref/api-debug.texi77
1 files changed, 77 insertions, 0 deletions
diff --git a/doc/ref/api-debug.texi b/doc/ref/api-debug.texi
index 04dc25c1c..46d0a39c8 100644
--- a/doc/ref/api-debug.texi
+++ b/doc/ref/api-debug.texi
@@ -508,6 +508,83 @@ Debugging} for more information about this.
Invoke the Guile debugger to explore the context of the last error.
@end deffn
+@subsubsection Debug options
+
+The behavior when an error is the @code{backtrace} procedure and of the
+default error handler can be parameterized via the debug options.
+
+@cindex options - debug
+@cindex debug options
+@deffn {Scheme Procedure} debug-options [setting]
+Display the current settings of the debug options. If @var{setting} is
+omitted, only a short form of the current read options is printed.
+Otherwise if @var{setting} is the symbol @code{help}, a complete options
+description is displayed.
+@end deffn
+
+The set of available options, and their default values, may be had by
+invoking @code{debug-options} at the prompt.
+
+@smallexample
+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.
+@end smallexample
+
+The boolean options may be toggled with @code{debug-enable} and
+@code{debug-disable}. The non-boolean @code{keywords} option must be set
+using @code{debug-set!}.
+
+@deffn {Scheme Procedure} debug-enable option-name
+@deffnx {Scheme Procedure} debug-disable option-name
+@deffnx {Scheme Procedure} debug-set! option-name value
+Modify the debug options. @code{debug-enable} should be used with boolean
+options and switches them on, @code{debug-disable} switches them off.
+@code{debug-set!} can be used to set an option to a specific value.
+@end deffn
+
+@subsubheading Stack overflow
+
+@cindex overflow, stack
+@cindex stack overflow
+Stack overflow errors are caused by a computation trying to use more
+stack space than has been enabled by the @code{stack} option. They are
+reported like this:
+
+@lisp
+(non-tail-recursive-factorial 500)
+@print{}
+ERROR: Stack overflow
+ABORT: (stack-overflow)
+@end lisp
+
+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 @code{debug-set!}, for example:
+
+@lisp
+(debug-set! stack 200000)
+@result{}
+(show-file-name #t stack 200000 debug backtrace depth 20
+ maxdepth 1000 frames 3 indent 10 width 79 procnames cheap)
+
+(non-tail-recursive-factorial 500)
+@result{}
+122013682599111006870123878542304692625357434@dots{}
+@end lisp
+
+If you prefer to try rewriting your code, you may be able to save stack
+space by making some of your procedures @dfn{tail recursive}
+(@pxref{Tail Calls}).
+
@node Traps
@subsection Traps