2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2008
4 @c Free Software Foundation, Inc.
5 @c See the file guile.texi for copying conditions.
8 @node Options and Config
9 @section Configuration, Features and Runtime Options
11 Why is my Guile different from your Guile? There are three kinds of
16 build differences --- different versions of the Guile source code,
17 installation directories, configuration flags that control pieces of
18 functionality being included or left out, etc.
21 differences in dynamically loaded code --- behaviour and features
22 provided by modules that can be dynamically loaded into a running Guile
25 different runtime options --- some of the options that are provided for
26 controlling Guile's behaviour may be set differently.
29 Guile provides ``introspective'' variables and procedures to query all
30 of these possible variations at runtime. For runtime options, it also
31 provides procedures to change the settings of options and to obtain
32 documentation on what the options mean.
35 * Build Config:: Build and installation configuration.
36 * Feature Tracking:: Available features in the Guile process.
37 * Runtime Options:: Controlling Guile's runtime behaviour.
42 @subsection Configuration, Build and Installation
44 The following procedures and variables provide information about how
45 Guile was configured, built and installed on your system.
47 @deffn {Scheme Procedure} version
48 @deffnx {Scheme Procedure} effective-version
49 @deffnx {Scheme Procedure} major-version
50 @deffnx {Scheme Procedure} minor-version
51 @deffnx {Scheme Procedure} micro-version
52 @deffnx {C Function} scm_version ()
53 @deffnx {C Function} scm_effective_version ()
54 @deffnx {C Function} scm_major_version ()
55 @deffnx {C Function} scm_minor_version ()
56 @deffnx {C Function} scm_micro_version ()
57 Return a string describing Guile's full version number, effective
58 version number, major, minor or micro version number, respectively.
59 The @code{effective-version} function returns the version name that
60 should remain unchanged during a stable series. Currently that means
61 that it omits the micro version. The effective version should be used
62 for items like the versioned share directory name
63 i.e. @file{/usr/share/guile/1.6/}
66 (version) @result{} "1.6.0"
67 (effective-version) @result{} "1.6"
68 (major-version) @result{} "1"
69 (minor-version) @result{} "6"
70 (micro-version) @result{} "0"
74 @deffn {Scheme Procedure} %package-data-dir
75 @deffnx {C Function} scm_sys_package_data_dir ()
76 Return the name of the directory under which Guile Scheme files in
77 general are stored. On Unix-like systems, this is usually
78 @file{/usr/local/share/guile} or @file{/usr/share/guile}.
81 @deffn {Scheme Procedure} %library-dir
82 @deffnx {C Function} scm_sys_library_dir ()
83 Return the name of the directory where the Guile Scheme files that
84 belong to the core Guile installation (as opposed to files from a 3rd
85 party package) are installed. On Unix-like systems this is usually
86 @file{/usr/local/share/guile/<GUILE_EFFECTIVE_VERSION>} or
87 @file{/usr/share/guile/<GUILE_EFFECTIVE_VERSION>};
89 @noindent for example @file{/usr/local/share/guile/1.6}.
92 @deffn {Scheme Procedure} %site-dir
93 @deffnx {C Function} scm_sys_site_dir ()
94 Return the name of the directory where Guile Scheme files specific to
95 your site should be installed. On Unix-like systems, this is usually
96 @file{/usr/local/share/guile/site} or @file{/usr/share/guile/site}.
99 @cindex GUILE_LOAD_PATH
101 List of directories which should be searched for Scheme modules and
102 libraries. @code{%load-path} is initialized when Guile starts up to
103 @code{(list (%site-dir) (%library-dir) (%package-data-dir))},
104 prepended with the contents of the GUILE_LOAD_PATH environment variable,
108 @deffn {Scheme Procedure} parse-path path [tail]
109 @deffnx {C Function} scm_parse_path (path, tail)
110 Parse @var{path}, which is expected to be a colon-separated
111 string, into a list and return the resulting list with
112 @var{tail} appended. If @var{path} is @code{#f}, @var{tail}
116 @deffn {Scheme Procedure} search-path path filename [extensions]
117 @deffnx {C Function} scm_search_path (path, filename, extensions)
118 Search @var{path} for a directory containing a file named
119 @var{filename}. The file must be readable, and not a directory.
120 If we find one, return its full filename; otherwise, return
121 @code{#f}. If @var{filename} is absolute, return it unchanged.
122 If given, @var{extensions} is a list of strings; for each
123 directory in @var{path}, we search for @var{filename}
124 concatenated with each @var{extension}.
127 @defvar %guile-build-info
128 Alist of information collected during the building of a particular
129 Guile. Entries can be grouped into one of several categories:
130 directories, env vars, and versioning info.
132 Briefly, here are the keys in @code{%guile-build-info}, by group:
134 @cindex @code{srcdir}
135 @cindex @code{top_srcdir}
136 @cindex @code{prefix}
137 @cindex @code{exec_prefix}
138 @cindex @code{bindir}
139 @cindex @code{sbindir}
140 @cindex @code{libexecdir}
141 @cindex @code{datadir}
142 @cindex @code{sysconfdir}
143 @cindex @code{sharedstatedir}
144 @cindex @code{localstatedir}
145 @cindex @code{libdir}
146 @cindex @code{infodir}
147 @cindex @code{mandir}
148 @cindex @code{includedir}
149 @cindex @code{pkgdatadir}
150 @cindex @code{pkglibdir}
151 @cindex @code{pkgincludedir}
154 srcdir, top_srcdir, prefix, exec_prefix, bindir, sbindir, libexecdir,
155 datadir, sysconfdir, sharedstatedir, localstatedir, libdir, infodir,
156 mandir, includedir, pkgdatadir, pkglibdir, pkgincludedir
160 @cindex @code{guileversion}
161 @cindex @code{libguileinterface}
162 @cindex @code{buildstamp}
163 @item versioning info
164 guileversion, libguileinterface, buildstamp
167 Values are all strings. The value for @code{LIBS} is typically found
168 also as a part of "guile-config link" output. The value for
169 @code{guileversion} has form X.Y.Z, and should be the same as returned
170 by @code{(version)}. The value for @code{libguileinterface} is
171 libtool compatible and has form CURRENT:REVISION:AGE
172 (@pxref{Versioning,, Library interface versions, libtool, GNU
173 Libtool}). The value for @code{buildstamp} is the output of the
176 In the source, @code{%guile-build-info} is initialized from
177 libguile/libpath.h, which is completely generated, so deleting this file
178 before a build guarantees up-to-date values for that build.
182 @node Feature Tracking
183 @subsection Feature Tracking
185 Guile has a Scheme level variable @code{*features*} that keeps track to
186 some extent of the features that are available in a running Guile.
187 @code{*features*} is a list of symbols, for example @code{threads}, each
188 of which describes a feature of the running Guile process.
191 A list of symbols describing available features of the Guile process.
194 You shouldn't modify the @code{*features*} variable directly using
195 @code{set!}. Instead, see the procedures that are provided for this
196 purpose in the following subsection.
199 * Feature Manipulation:: Checking for and advertising features.
200 * Common Feature Symbols:: Commonly available features.
204 @node Feature Manipulation
205 @subsubsection Feature Manipulation
207 To check whether a particular feature is available, use the
208 @code{provided?} procedure:
210 @deffn {Scheme Procedure} provided? feature
211 @deffnx {Deprecated Scheme Procedure} feature? feature
212 Return @code{#t} if the specified @var{feature} is available, otherwise
216 To advertise a feature from your own Scheme code, you can use the
217 @code{provide} procedure:
219 @deffn {Scheme Procedure} provide feature
220 Add @var{feature} to the list of available features in this Guile
224 For C code, the equivalent function takes its feature name as a
225 @code{char *} argument for convenience:
227 @deftypefn {C Function} void scm_add_feature (const char *str)
228 Add a symbol with name @var{str} to the list of available features in
233 @node Common Feature Symbols
234 @subsubsection Common Feature Symbols
236 In general, a particular feature may be available for one of two
237 reasons. Either because the Guile library was configured and compiled
238 with that feature enabled --- i.e. the feature is built into the library
239 on your system. Or because some C or Scheme code that was dynamically
240 loaded by Guile has added that feature to the list.
242 In the first category, here are the features that the current version of
243 Guile may define (depending on how it is built), and what they mean.
247 Indicates support for arrays (@pxref{Arrays}).
250 Indicates availability of @code{array-for-each} and other array mapping
251 procedures (@pxref{Arrays}).
254 Indicates that the @code{char-ready?} function is available
258 Indicates support for complex numbers.
261 Indicates availability of time-related functions: @code{times},
262 @code{get-internal-run-time} and so on (@pxref{Time}).
264 @item debug-extensions
265 Indicates that the debugging evaluator is available, together with the
266 options for controlling it.
269 Indicates support for promises (@pxref{Delayed Evaluation}).
272 Indicates that the @code{geteuid} and @code{getegid} really return
273 effective user and group IDs (@pxref{Processes}).
276 Indicates support for inexact numbers.
279 Indicates availability of the following extended I/O procedures:
280 @code{ftell}, @code{redirect-port}, @code{dup->fdes}, @code{dup2},
281 @code{fileno}, @code{isatty?}, @code{fdopen},
282 @code{primitive-move->fdes} and @code{fdes->ports} (@pxref{Ports and
286 Indicates availability of network database functions:
287 @code{scm_gethost}, @code{scm_getnet}, @code{scm_getproto},
288 @code{scm_getserv}, @code{scm_sethost}, @code{scm_setnet}, @code{scm_setproto},
289 @code{scm_setserv}, and their `byXXX' variants (@pxref{Network
293 Indicates support for POSIX functions: @code{pipe}, @code{getgroups},
294 @code{kill}, @code{execl} and so on (@pxref{POSIX}).
297 Indicates availability of random number generation functions:
298 @code{random}, @code{copy-random-state}, @code{random-uniform} and so on
302 Indicates that Guile was built with important checks omitted --- you
303 should never see this!
306 Indicates support for POSIX regular expressions using
307 @code{make-regexp}, @code{regexp-exec} and friends (@pxref{Regexp
311 Indicates availability of socket-related functions: @code{socket},
312 @code{bind}, @code{connect} and so on (@pxref{Network Sockets and
316 Indicates availability of sorting and merging functions
320 Indicates that the @code{system} function is available
324 Indicates support for multithreading (@pxref{Threads}).
327 Indicates support for multiple return values using @code{values} and
328 @code{call-with-values} (@pxref{Multiple Values}).
331 Available features in the second category depend, by definition, on what
332 additional code your Guile process has loaded in. The following table
333 lists features that you might encounter for this reason.
337 Indicates that the @code{defmacro} macro is available (@pxref{Macros}).
340 Indicates that the @code{(oop goops describe)} module has been loaded,
341 which provides a procedure for describing the contents of GOOPS
345 Indicates that Guile has loaded in Readline support, for command line
346 editing (@pxref{Readline Support}).
349 Indicates support for record definition using @code{make-record-type}
350 and friends (@pxref{Records}).
353 Although these tables may seem exhaustive, it is probably unwise in
354 practice to rely on them, as the correspondences between feature symbols
355 and available procedures/behaviour are not strictly defined. If you are
356 writing code that needs to check for the existence of some procedure, it
357 is probably safer to do so directly using the @code{defined?} procedure
358 than to test for the corresponding feature using @code{provided?}.
361 @node Runtime Options
362 @subsection Runtime Options
364 Guile's runtime behaviour can be modified by setting options. For
365 example, is the language that Guile accepts case sensitive, or should
366 the debugger automatically show a backtrace on error?
368 Guile has two levels of interface for managing options: a low-level
369 control interface, and a user-level interface which allows the enabling
370 or disabling of options.
372 Moreover, the options are classified in groups according to whether they
373 configure @emph{reading}, @emph{printing}, @emph{debugging} or
377 * Low level options interfaces::
378 * User level options interfaces::
382 * Evaluator options::
383 * Evaluator trap options::
384 * Examples of option use::
388 @node Low level options interfaces
389 @subsubsection Low Level Options Interfaces
391 @deffn {Scheme Procedure} read-options-interface [setting]
392 @deffnx {Scheme Procedure} eval-options-interface [setting]
393 @deffnx {Scheme Procedure} print-options-interface [setting]
394 @deffnx {Scheme Procedure} debug-options-interface [setting]
395 @deffnx {Scheme Procedure} evaluator-traps-interface [setting]
396 @deffnx {C Function} scm_read_options (setting)
397 @deffnx {C Function} scm_eval_options_interface (setting)
398 @deffnx {C Function} scm_print_options (setting)
399 @deffnx {C Function} scm_debug_options (setting)
400 @deffnx {C Function} scm_evaluator_traps (setting)
401 If one of these procedures is called with no arguments (or with
402 @code{setting == SCM_UNDEFINED} in C code), it returns a list describing
403 the current setting of the read, eval, print, debug or evaluator traps
404 options respectively. The setting of a boolean option is indicated
405 simply by the presence or absence of the option symbol in the list. The
406 setting of a non-boolean option is indicated by the presence of the
407 option symbol immediately followed by the option's current value.
409 If called with a list argument, these procedures interpret the list as
410 an option setting and modify the relevant options accordingly. [FIXME
411 --- this glosses over a lot of details!]
413 If called with any other argument, such as @code{'help}, these
414 procedures return a list of entries like @code{(@var{OPTION-SYMBOL}
415 @var{DEFAULT-VALUE} @var{DOC-STRING})}, with each entry giving the
416 default value and documentation for each option symbol in the relevant
421 @node User level options interfaces
422 @subsubsection User Level Options Interfaces
424 @c @deftp {Data type} scm_option
425 @c @code{scm_option} is used to represent run time options. It can be a
426 @c @emph{boolean} type, in which case the option will be set by the strings
427 @c @code{"yes"} and @code{"no"}. It can be a
431 @deffn {Scheme Procedure} <group>-options [arg]
432 @deffnx {Scheme Procedure} read-options [arg]
433 @deffnx {Scheme Procedure} print-options [arg]
434 @deffnx {Scheme Procedure} debug-options [arg]
435 @deffnx {Scheme Procedure} traps [arg]
436 These functions list the options in their group. The optional argument
437 @var{arg} is a symbol which modifies the form in which the options are
440 With no arguments, @code{<group>-options} returns the values of the
441 options in that particular group. If @var{arg} is @code{'help}, a
442 description of each option is given. If @var{arg} is @code{'full},
443 programmers' options are also shown.
445 @var{arg} can also be a list representing the state of all options. In
446 this case, the list contains single symbols (for enabled boolean
447 options) and symbols followed by values.
449 [FIXME: I don't think 'full is ever any different from 'help. What's
453 @deffn {Scheme Procedure} <group>-enable option-symbol
454 @deffnx {Scheme Procedure} read-enable option-symbol
455 @deffnx {Scheme Procedure} print-enable option-symbol
456 @deffnx {Scheme Procedure} debug-enable option-symbol
457 @deffnx {Scheme Procedure} trap-enable option-symbol
458 These functions set the specified @var{option-symbol} in their options
459 group. They only work if the option is boolean, and throw an error
464 @deffn {Scheme Procedure} <group>-disable option-symbol
465 @deffnx {Scheme Procedure} read-disable option-symbol
466 @deffnx {Scheme Procedure} print-disable option-symbol
467 @deffnx {Scheme Procedure} debug-disable option-symbol
468 @deffnx {Scheme Procedure} trap-disable option-symbol
469 These functions turn off the specified @var{option-symbol} in their
470 options group. They only work if the option is boolean, and throw an
475 @deffn syntax <group>-set! option-symbol value
476 @deffnx syntax read-set! option-symbol value
477 @deffnx syntax print-set! option-symbol value
478 @deffnx syntax debug-set! option-symbol value
479 @deffnx syntax trap-set! option-symbol value
480 These functions set a non-boolean @var{option-symbol} to the specified
486 @subsubsection Reader options
487 @cindex options - read
490 Here is the list of reader options generated by typing
491 @code{(read-options 'full)} in Guile. You can also see the default
495 keywords #f Style of keyword recognition: #f, 'prefix or 'postfix
496 case-insensitive no Convert symbols to lower case.
497 positions yes Record positions of source code expressions.
498 copy no Copy source code expressions.
501 Notice that while Standard Scheme is case insensitive, to ease
502 translation of other Lisp dialects, notably Emacs Lisp, into Guile,
503 Guile is case-sensitive by default.
505 To make Guile case insensitive, you can type
508 (read-enable 'case-insensitive)
511 @node Printing options
512 @subsubsection Printing options
514 Here is the list of print options generated by typing
515 @code{(print-options 'full)} in Guile. You can also see the default
519 quote-keywordish-symbols reader How to print symbols that have a colon
520 as their first or last character. The
521 value '#f' does not quote the colons;
522 '#t' quotes them; 'reader' quotes
523 them when the reader option
524 'keywords' is not '#f'.
526 highlight-prefix @{ The string to print before highlighted values.
527 highlight-suffix @} The string to print after highlighted values.
529 source no Print closures with source.
530 closure-hook #f Hook for printing closures.
534 @node Evaluator options
535 @subsubsection Evaluator options
537 These are the evaluator options with their default values, as they are
538 printed by typing @code{(eval-options 'full)} in Guile.
541 stack 22000 Size of thread stacks (in machine words).
545 @node Evaluator trap options
546 @subsubsection Evaluator trap options
547 [FIXME: These flags, together with their corresponding handlers, are not
548 user level options. Probably this entire section should be moved to the
549 documentation about the low-level programmer debugging interface.]
551 Here is the list of evaluator trap options generated by typing
552 @code{(traps 'full)} in Guile. You can also see the default values.
555 exit-frame no Trap when exiting eval or apply.
556 apply-frame no Trap when entering apply.
557 enter-frame no Trap when eval enters new frame.
558 memoize-symbol no Trap when eval memoizes a symbol's value
559 traps yes Enable evaluator traps.
562 @deffn apply-frame-handler key cont tailp
563 Called when a procedure is being applied.
569 evaluator traps are enabled [traps interface], and
574 @code{apply-frame} is enabled [traps interface], or
576 trace mode is on [debug-options interface], and the procedure being
577 called has the trace property enabled.
581 @var{cont} is a ``debug object'', which means that it can be passed to
582 @code{make-stack} to discover the stack at the point of the trap. The
583 apply frame handler's code can capture a restartable continuation if it
584 wants to by using @code{call-with-current-continuation} in the usual way.
586 @var{tailp} is true if this is a tail call
589 @deffn exit-frame-handler key cont retval
590 Called when a value is returned from a procedure.
596 evaluator traps are enabled [traps interface], and
601 @code{exit-frame} is enabled [traps interface], or
603 trace mode is on [debug-options interface], and the procedure being
604 called has the trace property enabled.
608 @var{cont} is a ``debug object'', which means that it can be passed to
609 @code{make-stack} to discover the stack at the point of the trap. The
610 exit frame handler's code can capture a restartable continuation if it
611 wants to by using @code{call-with-current-continuation} in the usual
614 @var{retval} is the return value.
617 @deffn memoize-symbol-handler key cont expression env
618 Called when the evaluator memoizes the value of a procedure symbol
620 @var{cont} is a ``debug object'', which means that it can be passed to
621 @code{make-stack} to discover the stack at the point of the trap. The
622 exit frame handler's code can capture a restartable continuation if it
623 wants to by using @code{call-with-current-continuation} in the usual
626 @var{retval} is the return value.
629 @deffn {Scheme Procedure} with-traps thunk
630 @deffnx {C Function} scm_with_traps (thunk)
631 Call @var{thunk} with traps enabled.
634 @deffn {Scheme Procedure} debug-object? obj
635 @deffnx {C Function} scm_debug_object_p (obj)
636 Return @code{#t} if @var{obj} is a debug object.
640 @node Debugger options
641 @subsubsection Debugger options
643 Here is the list of print options generated by typing
644 @code{(debug-options 'full)} in Guile. You can also see the default
648 stack 20000 Stack size limit (0 = no check).
649 debug yes Use the debugging evaluator.
650 backtrace no Show backtrace on error.
651 depth 20 Maximal length of printed backtrace.
652 maxdepth 1000 Maximal number of stored backtrace frames.
653 frames 3 Maximum number of tail-recursive frames in backtrace.
654 indent 10 Maximal indentation in backtrace.
655 backwards no Display backtrace in anti-chronological order.
656 procnames yes Record procedure names at definition.
657 trace no *Trace mode.
658 breakpoints no *Check for breakpoints.
659 cheap yes *This option is now obsolete. Setting it has no effect.
662 @subsubheading Stack overflow
664 @cindex overflow, stack
665 @cindex stack overflow
666 Stack overflow errors are caused by a computation trying to use more
667 stack space than has been enabled by the @code{stack} option. They are
671 (non-tail-recursive-factorial 500)
673 ERROR: Stack overflow
674 ABORT: (stack-overflow)
677 If you get an error like this, you can either try rewriting your code to
678 use less stack space, or increase the maximum stack size. To increase
679 the maximum stack size, use @code{debug-set!}, for example:
682 (debug-set! stack 200000)
684 (show-file-name #t stack 200000 debug backtrace depth 20
685 maxdepth 1000 frames 3 indent 10 width 79 procnames cheap)
687 (non-tail-recursive-factorial 500)
689 122013682599111006870123878542304692625357434@dots{}
692 If you prefer to try rewriting your code, you may be able to save stack
693 space by making some of your procedures @dfn{tail recursive}
694 (@pxref{Tail Calls}).
697 @node Examples of option use
698 @subsubsection Examples of option use
700 Here is an example of a session in which some read and debug option
701 handling procedures are used. In this example, the user
705 Notices that the symbols @code{abc} and @code{aBc} are not the same
707 Examines the @code{read-options}, and sees that @code{case-insensitive}
710 Enables @code{case-insensitive}
712 Verifies that now @code{aBc} and @code{abc} are the same
714 Disables @code{case-insensitive} and enables debugging @code{backtrace}
716 Reproduces the error of displaying @code{aBc} with backtracing enabled
717 [FIXME: this last example is lame because there is no depth in the
718 backtrace. Need to give a better example, possibly putting debugging
719 option examples in a separate session.]
723 guile> (define abc "hello")
727 ERROR: In expression aBc:
728 ERROR: Unbound variable: aBc
731 Type "(backtrace)" to get more information.
732 guile> (read-options 'help)
733 keywords #f Style of keyword recognition: #f, 'prefix or 'postfix
734 case-insensitive no Convert symbols to lower case.
735 positions yes Record positions of source code expressions.
736 copy no Copy source code expressions.
737 guile> (debug-options 'help)
738 stack 20000 Stack size limit (0 = no check).
739 debug yes Use the debugging evaluator.
740 backtrace no Show backtrace on error.
741 depth 20 Maximal length of printed backtrace.
742 maxdepth 1000 Maximal number of stored backtrace frames.
743 frames 3 Maximum number of tail-recursive frames in backtrace.
744 indent 10 Maximal indentation in backtrace.
745 backwards no Display backtrace in anti-chronological order.
746 procnames yes Record procedure names at definition.
747 trace no *Trace mode.
748 breakpoints no *Check for breakpoints.
749 cheap yes *This option is now obsolete. Setting it has no effect.
750 guile> (read-enable 'case-insensitive)
751 (keywords #f case-insensitive positions)
754 guile> (read-disable 'case-insensitive)
755 (keywords #f positions)
756 guile> (debug-enable 'backtrace)
757 (stack 20000 debug backtrace depth 20 maxdepth 1000 frames 3 indent 10 procnames cheap)
763 ERROR: In expression aBc:
764 ERROR: Unbound variable: aBc
771 @c TeX-master: "guile.texi"