mirror of
https://git.savannah.gnu.org/git/guile.git
synced 2025-05-01 20:30:28 +02:00
398 lines
12 KiB
Text
398 lines
12 KiB
Text
@page
|
|
@node Options and Config
|
|
@chapter Runtime Options and Configuration
|
|
|
|
Guile's behaviour can be modified by setting options. For example, is
|
|
the language that Guile accepts case sensitive, or should the debugger
|
|
automatically show a backtrace on error?
|
|
|
|
Guile has two levels of interface for managing options: a low-level
|
|
control interface, and a user-level interface which allows the enabling
|
|
or disabling of options.
|
|
|
|
Moreover, the options are classified in groups according to whether they
|
|
configure @emph{reading}, @emph{printing}, @emph{debugging} or
|
|
@emph{evaluating}.
|
|
|
|
@menu
|
|
* General option interface::
|
|
* Reader options::
|
|
* Printing options::
|
|
* Debugger options::
|
|
* Evaluator options::
|
|
* Evaluator trap options::
|
|
* Examples of option use::
|
|
* Install Config:: Installation and configuration data.
|
|
@end menu
|
|
|
|
@node General option interface
|
|
@section General option interface
|
|
|
|
We will use the expression @code{<group>} to represent @code{read},
|
|
@code{print}, @code{debug} or @code{evaluator}.
|
|
|
|
@subheading Low level
|
|
|
|
@c NJFIXME
|
|
@deffn primitive <group>-options-interface
|
|
@deffnx primitive read-options-interface [SOME-INT]
|
|
@deffnx primitive print-options-interface [SOME-INT]
|
|
@deffnx primitive evaluator-traps-interface [SOME-INT]
|
|
@deffnx primitive read-options-interface [SOME-INT]
|
|
[FIXME: I have just taken the comments for C routine scm_options that
|
|
implements all of these. It needs to be presented better.]
|
|
|
|
If scm_options is called without arguments, the current option setting
|
|
is returned. If the argument is an option setting, options are altered
|
|
and the old setting is returned. If the argument isn't a list, a list
|
|
of sublists is returned, where each sublist contains option name, value
|
|
and documentation string.
|
|
@end deffn
|
|
|
|
|
|
@subheading User level
|
|
|
|
@c @deftp {Data type} scm_option
|
|
@c @code{scm_option} is used to represent run time options. It can be a
|
|
@c @emph{boolean} type, in which case the option will be set by the strings
|
|
@c @code{"yes"} and @code{"no"}. It can be a
|
|
@c @end deftp
|
|
|
|
@c NJFIXME
|
|
@deffn procedure <group>-options [arg]
|
|
@deffnx procedure read-options [arg]
|
|
@deffnx procedure print-options [arg]
|
|
@deffnx procedure debug-options [arg]
|
|
@deffnx procedure traps [arg]
|
|
These functions list the options in their group. The optional argument
|
|
@var{arg} is a symbol which modifies the form in which the options are
|
|
presented.
|
|
|
|
With no arguments, @code{<group>-options} returns the values of the
|
|
options in that particular group. If @var{arg} is @code{'help}, a
|
|
description of each option is given. If @var{arg} is @code{'full},
|
|
programmers' options are also shown.
|
|
|
|
@var{arg} can also be a list representing the state of all options. In
|
|
this case, the list contains single symbols (for enabled boolean
|
|
options) and symbols followed by values.
|
|
@end deffn
|
|
[FIXME: I don't think 'full is ever any different from 'help. What's
|
|
up?]
|
|
|
|
@c NJFIXME
|
|
@deffn procedure <group>-enable option-symbol
|
|
@deffnx procedure read-enable option-symbol
|
|
@deffnx procedure print-enable option-symbol
|
|
@deffnx procedure debug-enable option-symbol
|
|
@deffnx procedure trap-enable option-symbol
|
|
These functions set the specified @var{option-symbol} in their options
|
|
group. They only work if the option is boolean, and throw an error
|
|
otherwise.
|
|
@end deffn
|
|
|
|
@c NJFIXME
|
|
@deffn procedure <group>-disable option-symbol
|
|
@deffnx procedure read-disable option-symbol
|
|
@deffnx procedure print-disable option-symbol
|
|
@deffnx procedure debug-disable option-symbol
|
|
@deffnx procedure trap-disable option-symbol
|
|
These functions turn off the specified @var{option-symbol} in their
|
|
options group. They only work if the option is boolean, and throw an
|
|
error otherwise.
|
|
@end deffn
|
|
|
|
@c NJFIXME
|
|
@deffn syntax <group>-set! option-symbol value
|
|
@deffnx syntax read-set! option-symbol value
|
|
@deffnx syntax print-set! option-symbol value
|
|
@deffnx syntax debug-set! option-symbol value
|
|
@deffnx syntax trap-set! option-symbol value
|
|
These functions set a non-boolean @var{option-symbol} to the specified
|
|
@var{value}.
|
|
@end deffn
|
|
|
|
|
|
@node Reader options
|
|
@section Reader options
|
|
@cindex options - read
|
|
@cindex read options
|
|
|
|
Here is the list of reader options generated by typing
|
|
@code{(read-options 'full)} in Guile. You can also see the default
|
|
values.
|
|
|
|
@smalllisp
|
|
keywords #f Style of keyword recognition: #f or 'prefix
|
|
case-insensitive no Convert symbols to lower case.
|
|
positions yes Record positions of source code expressions.
|
|
copy no Copy source code expressions.
|
|
@end smalllisp
|
|
|
|
Notice that while Standard Scheme is case insensitive, to ease
|
|
translation of other Lisp dialects, notably Emacs Lisp, into Guile,
|
|
Guile is case-sensitive by default.
|
|
|
|
To make Guile case insensitive, you can type
|
|
|
|
@smalllisp
|
|
(read-enable 'case-insensitive)
|
|
@end smalllisp
|
|
|
|
@node Printing options
|
|
@section Printing options
|
|
|
|
Here is the list of print options generated by typing
|
|
@code{(print-options 'full)} in Guile. You can also see the default
|
|
values.
|
|
|
|
@smallexample
|
|
source no Print closures with source.
|
|
closure-hook #f Hook for printing closures.
|
|
@end smallexample
|
|
|
|
|
|
@node Evaluator options
|
|
@section Evaluator options
|
|
These are the evaluator options with their default values, as they are
|
|
printed by typing @code{(eval-options 'full)} in Guile.
|
|
|
|
@smallexample
|
|
stack 22000 Size of thread stacks (in machine words).
|
|
@end smallexample
|
|
|
|
@node Evaluator trap options
|
|
@section Evaluator trap options
|
|
[FIXME: These flags, together with their corresponding handlers, are not
|
|
user level options. Probably this entire section should be moved to the
|
|
documentation about the low-level programmer debugging interface.]
|
|
|
|
Here is the list of evaluator trap options generated by typing
|
|
@code{(traps 'full)} in Guile. You can also see the default values.
|
|
|
|
@smallexample
|
|
exit-frame no Trap when exiting eval or apply.
|
|
apply-frame no Trap when entering apply.
|
|
enter-frame no Trap when eval enters new frame.
|
|
traps yes Enable evaluator traps.
|
|
@end smallexample
|
|
|
|
@deffn apply-frame-handler key cont tailp
|
|
Called when a procedure is being applied.
|
|
|
|
Called if:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
evaluator traps are enabled [traps interface], and
|
|
@item
|
|
either
|
|
@itemize @minus
|
|
@item
|
|
@code{apply-frame} is enabled [traps interface], or
|
|
@item
|
|
trace mode is on [debug-options interface], and the procedure being
|
|
called has the trace property enabled.
|
|
@end itemize
|
|
@end itemize
|
|
|
|
If cheap traps are enabled [debug-options interface], @var{cont} is a
|
|
debug object, otherwise it is a restartable continuation.
|
|
|
|
@var{tailp} is true if this is a tail call
|
|
@end deffn
|
|
|
|
@deffn exit-frame-handler key cont retval
|
|
Called when a value is returned from a procedure.
|
|
|
|
Called if:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
evaluator traps are enabled [traps interface], and
|
|
@item
|
|
either
|
|
@itemize @minus
|
|
@item
|
|
@code{exit-frame} is enabled [traps interface], or
|
|
@item
|
|
trace mode is on [debug-options interface], and the procedure being
|
|
called has the trace property enabled.
|
|
@end itemize
|
|
@end itemize
|
|
|
|
If cheap traps are enabled [debug-options interface], @var{cont} is a
|
|
debug object, otherwise it is a restartable continuation.
|
|
|
|
@var{retval} is the return value.
|
|
@end deffn
|
|
|
|
@node Debugger options
|
|
@section Debugger options
|
|
|
|
Here is the list of print options generated by typing
|
|
@code{(debug-options 'full)} in Guile. You can also see the default
|
|
values.
|
|
|
|
@smallexample
|
|
stack 20000 Stack size limit (0 = no check).
|
|
debug yes Use the debugging evaluator.
|
|
backtrace no Show backtrace on error.
|
|
depth 20 Maximal length of printed backtrace.
|
|
maxdepth 1000 Maximal number of stored backtrace frames.
|
|
frames 3 Maximum number of tail-recursive frames in backtrace.
|
|
indent 10 Maximal indentation in backtrace.
|
|
backwards no Display backtrace in anti-chronological order.
|
|
procnames yes Record procedure names at definition.
|
|
trace no *Trace mode.
|
|
breakpoints no *Check for breakpoints.
|
|
cheap yes *Flyweight representation of the stack at traps.
|
|
@end smallexample
|
|
|
|
|
|
@node Examples of option use
|
|
@section Examples of option use
|
|
|
|
Here is an example of a session in which some read and debug option
|
|
handling procedures are used. In this example, the user
|
|
|
|
@enumerate
|
|
@item
|
|
Notices that the symbols @code{abc} and @code{aBc} are not the same
|
|
@item
|
|
Examines the @code{read-options}, and sees that @code{case-insensitive}
|
|
is set to ``no''.
|
|
@item
|
|
Enables @code{case-insensitive}
|
|
@item
|
|
Verifies that now @code{aBc} and @code{abc} are the same
|
|
@item
|
|
Disables @code{case-insensitive} and enables debugging @code{backtrace}
|
|
@item
|
|
Reproduces the error of displaying @code{aBc} with backtracing enabled
|
|
[FIXME: this last example is lame because there is no depth in the
|
|
backtrace. Need to give a better example, possibly putting debugging
|
|
option examples in a separate session.]
|
|
@end enumerate
|
|
|
|
|
|
@smalllisp
|
|
guile> (define abc "hello")
|
|
guile> abc
|
|
"hello"
|
|
guile> aBc
|
|
ERROR: In expression aBc:
|
|
ERROR: Unbound variable: aBc
|
|
ABORT: (misc-error)
|
|
|
|
Type "(backtrace)" to get more information.
|
|
guile> (read-options 'help)
|
|
keywords #f Style of keyword recognition: #f or 'prefix
|
|
case-insensitive no Convert symbols to lower case.
|
|
positions yes Record positions of source code expressions.
|
|
copy no Copy source code expressions.
|
|
guile> (debug-options 'help)
|
|
stack 20000 Stack size limit (0 = no check).
|
|
debug yes Use the debugging evaluator.
|
|
backtrace no Show backtrace on error.
|
|
depth 20 Maximal length of printed backtrace.
|
|
maxdepth 1000 Maximal number of stored backtrace frames.
|
|
frames 3 Maximum number of tail-recursive frames in backtrace.
|
|
indent 10 Maximal indentation in backtrace.
|
|
backwards no Display backtrace in anti-chronological order.
|
|
procnames yes Record procedure names at definition.
|
|
trace no *Trace mode.
|
|
breakpoints no *Check for breakpoints.
|
|
cheap yes *Flyweight representation of the stack at traps.
|
|
guile> (read-enable 'case-insensitive)
|
|
(keywords #f case-insensitive positions)
|
|
guile> aBc
|
|
"hello"
|
|
guile> (read-disable 'case-insensitive)
|
|
(keywords #f positions)
|
|
guile> (debug-enable 'backtrace)
|
|
(stack 20000 debug backtrace depth 20 maxdepth 1000 frames 3 indent 10 procnames cheap)
|
|
guile> aBc
|
|
|
|
Backtrace:
|
|
0* aBc
|
|
|
|
ERROR: In expression aBc:
|
|
ERROR: Unbound variable: aBc
|
|
ABORT: (misc-error)
|
|
guile>
|
|
@end smalllisp
|
|
|
|
|
|
@node Install Config
|
|
@section Installation and Configuration Data
|
|
|
|
It is often useful to have site-specific information about the current
|
|
Guile installation. This chapter describes how to find out about
|
|
Guile's configuration at run time.
|
|
|
|
@deffn primitive version
|
|
@deffnx primitive major-version
|
|
@deffnx primitive minor-version
|
|
@deffnx primitive micro-version
|
|
Return a string describing Guile's version number, or its major or minor
|
|
version numbers, respectively.
|
|
|
|
@lisp
|
|
(version) @result{} "1.6.5"
|
|
(major-version) @result{} "1"
|
|
(minor-version) @result{} "6"
|
|
(micro-version) @result{} "5"
|
|
@end lisp
|
|
@end deffn
|
|
|
|
@c NJFIXME not in libguile!
|
|
@deffn primitive libguile-config-stamp
|
|
Return a string describing the date on which @code{libguile} was
|
|
configured. This is used to determine whether the Guile core
|
|
interpreter and the ice-9 runtime have grown out of date with one
|
|
another.
|
|
@end deffn
|
|
|
|
@deffn primitive %package-data-dir
|
|
Return the name of the directory where Scheme packages, modules and
|
|
libraries are kept. On most Unix systems, this will be
|
|
@samp{/usr/local/share/guile}.
|
|
@end deffn
|
|
|
|
@deffn primitive %library-dir
|
|
Return the directory where the Guile Scheme library files are installed.
|
|
E.g., may return "/usr/share/guile/1.3.5".
|
|
@end deffn
|
|
|
|
@deffn primitive %site-dir
|
|
Return the directory where the Guile site files are installed.
|
|
E.g., may return "/usr/share/guile/site".
|
|
@end deffn
|
|
|
|
@deffn primitive parse-path path [tail]
|
|
Parse @var{path}, which is expected to be a colon-separated
|
|
string, into a list and return the resulting list with
|
|
@var{tail} appended. If @var{path} is @code{#f}, @var{tail}
|
|
is returned.
|
|
@end deffn
|
|
|
|
@deffn primitive search-path path filename [extensions]
|
|
Search @var{path} for a directory containing a file named
|
|
@var{filename}. The file must be readable, and not a directory.
|
|
If we find one, return its full filename; otherwise, return
|
|
@code{#f}. If @var{filename} is absolute, return it unchanged.
|
|
If given, @var{extensions} is a list of strings; for each
|
|
directory in @var{path}, we search for @var{filename}
|
|
concatenated with each @var{extension}.
|
|
@end deffn
|
|
|
|
@defvar %load-path
|
|
Return the list of directories which should be searched for Scheme
|
|
modules and libraries.
|
|
@end defvar
|
|
|
|
|
|
@c Local Variables:
|
|
@c TeX-master: "guile.texi"
|
|
@c End:
|