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>}, for example:
88 @file{/usr/local/share/guile/1.6}.
91 @deffn {Scheme Procedure} %site-dir
92 @deffnx {C Function} scm_sys_site_dir ()
93 Return the name of the directory where Guile Scheme files specific to
94 your site should be installed. On Unix-like systems, this is usually
95 @file{/usr/local/share/guile/site} or @file{/usr/share/guile/site}.
98 @cindex GUILE_LOAD_PATH
100 List of directories which should be searched for Scheme modules and
101 libraries. @code{%load-path} is initialized when Guile starts up to
102 @code{(list (%site-dir) (%library-dir) (%package-data-dir) ".")},
103 prepended with the contents of the GUILE_LOAD_PATH environment variable,
107 @deffn {Scheme Procedure} parse-path path [tail]
108 @deffnx {C Function} scm_parse_path (path, tail)
109 Parse @var{path}, which is expected to be a colon-separated
110 string, into a list and return the resulting list with
111 @var{tail} appended. If @var{path} is @code{#f}, @var{tail}
115 @deffn {Scheme Procedure} search-path path filename [extensions]
116 @deffnx {C Function} scm_search_path (path, filename, extensions)
117 Search @var{path} for a directory containing a file named
118 @var{filename}. The file must be readable, and not a directory.
119 If we find one, return its full filename; otherwise, return
120 @code{#f}. If @var{filename} is absolute, return it unchanged.
121 If given, @var{extensions} is a list of strings; for each
122 directory in @var{path}, we search for @var{filename}
123 concatenated with each @var{extension}.
126 @defvar %guile-build-info
127 Alist of information collected during the building of a particular
128 Guile. Entries can be grouped into one of several categories:
129 directories, env vars, and versioning info.
131 Briefly, here are the keys in @code{%guile-build-info}, by group:
133 @cindex @code{srcdir}
134 @cindex @code{top_srcdir}
135 @cindex @code{prefix}
136 @cindex @code{exec_prefix}
137 @cindex @code{bindir}
138 @cindex @code{sbindir}
139 @cindex @code{libexecdir}
140 @cindex @code{datadir}
141 @cindex @code{sysconfdir}
142 @cindex @code{sharedstatedir}
143 @cindex @code{localstatedir}
144 @cindex @code{libdir}
145 @cindex @code{infodir}
146 @cindex @code{mandir}
147 @cindex @code{includedir}
148 @cindex @code{pkgdatadir}
149 @cindex @code{pkglibdir}
150 @cindex @code{pkgincludedir}
153 srcdir, top_srcdir, prefix, exec_prefix, bindir, sbindir, libexecdir,
154 datadir, sysconfdir, sharedstatedir, localstatedir, libdir, infodir,
155 mandir, includedir, pkgdatadir, pkglibdir, pkgincludedir
159 @cindex @code{guileversion}
160 @cindex @code{libguileinterface}
161 @cindex @code{buildstamp}
162 @item versioning info
163 guileversion, libguileinterface, buildstamp
166 Values are all strings. The value for @code{LIBS} is typically found
167 also as a part of "guile-config link" output. The value for
168 @code{guileversion} has form X.Y.Z, and should be the same as returned
169 by @code{(version)}. The value for @code{libguileinterface} is
170 libtool compatible and has form CURRENT:REVISION:AGE
171 (@pxref{Versioning,, Library interface versions, libtool, GNU
172 Libtool}). The value for @code{buildstamp} is the output of the
175 In the source, @code{%guile-build-info} is initialized from
176 libguile/libpath.h, which is completely generated, so deleting this file
177 before a build guarantees up-to-date values for that build.
181 @node Feature Tracking
182 @subsection Feature Tracking
184 Guile has a Scheme level variable @code{*features*} that keeps track to
185 some extent of the features that are available in a running Guile.
186 @code{*features*} is a list of symbols, for example @code{threads}, each
187 of which describes a feature of the running Guile process.
190 A list of symbols describing available features of the Guile process.
193 You shouldn't modify the @code{*features*} variable directly using
194 @code{set!}. Instead, see the procedures that are provided for this
195 purpose in the following subsection.
198 * Feature Manipulation:: Checking for and advertising features.
199 * Common Feature Symbols:: Commonly available features.
203 @node Feature Manipulation
204 @subsubsection Feature Manipulation
206 To check whether a particular feature is available, use the
207 @code{provided?} procedure:
209 @deffn {Scheme Procedure} provided? feature
210 @deffnx {Deprecated Scheme Procedure} feature? feature
211 Return @code{#t} if the specified @var{feature} is available, otherwise
215 To advertise a feature from your own Scheme code, you can use the
216 @code{provide} procedure:
218 @deffn {Scheme Procedure} provide feature
219 Add @var{feature} to the list of available features in this Guile
223 For C code, the equivalent function takes its feature name as a
224 @code{char *} argument for convenience:
226 @deftypefn {C Function} void scm_add_feature (const char *str)
227 Add a symbol with name @var{str} to the list of available features in
232 @node Common Feature Symbols
233 @subsubsection Common Feature Symbols
235 In general, a particular feature may be available for one of two
236 reasons. Either because the Guile library was configured and compiled
237 with that feature enabled --- i.e. the feature is built into the library
238 on your system. Or because some C or Scheme code that was dynamically
239 loaded by Guile has added that feature to the list.
241 In the first category, here are the features that the current version of
242 Guile may define (depending on how it is built), and what they mean.
246 Indicates support for arrays (@pxref{Arrays}).
249 Indicates availability of @code{array-for-each} and other array mapping
250 procedures (@pxref{Arrays}).
253 Indicates that the @code{char-ready?} function is available
257 Indicates support for complex numbers.
260 Indicates availability of time-related functions: @code{times},
261 @code{get-internal-run-time} and so on (@pxref{Time}).
263 @item debug-extensions
264 Indicates that the debugging evaluator is available, together with the
265 options for controlling it.
268 Indicates support for promises (@pxref{Delayed Evaluation}).
271 Indicates that the @code{geteuid} and @code{getegid} really return
272 effective user and group IDs (@pxref{Processes}).
275 Indicates support for inexact numbers.
278 Indicates availability of the following extended I/O procedures:
279 @code{ftell}, @code{redirect-port}, @code{dup->fdes}, @code{dup2},
280 @code{fileno}, @code{isatty?}, @code{fdopen},
281 @code{primitive-move->fdes} and @code{fdes->ports} (@pxref{Ports and
285 Indicates availability of network database functions:
286 @code{scm_gethost}, @code{scm_getnet}, @code{scm_getproto},
287 @code{scm_getserv}, @code{scm_sethost}, @code{scm_setnet}, @code{scm_setproto},
288 @code{scm_setserv}, and their `byXXX' variants (@pxref{Network
292 Indicates support for POSIX functions: @code{pipe}, @code{getgroups},
293 @code{kill}, @code{execl} and so on (@pxref{POSIX}).
296 Indicates availability of random number generation functions:
297 @code{random}, @code{copy-random-state}, @code{random-uniform} and so on
301 Indicates that Guile was built with important checks omitted --- you
302 should never see this!
305 Indicates support for POSIX regular expressions using
306 @code{make-regexp}, @code{regexp-exec} and friends (@pxref{Regexp
310 Indicates availability of socket-related functions: @code{socket},
311 @code{bind}, @code{connect} and so on (@pxref{Network Sockets and
315 Indicates availability of sorting and merging functions
319 Indicates that the @code{system} function is available
323 Indicates support for multithreading (@pxref{Threads}).
326 Indicates support for multiple return values using @code{values} and
327 @code{call-with-values} (@pxref{Multiple Values}).
330 Available features in the second category depend, by definition, on what
331 additional code your Guile process has loaded in. The following table
332 lists features that you might encounter for this reason.
336 Indicates that the @code{defmacro} macro is available (@pxref{Macros}).
339 Indicates that the @code{(oop goops describe)} module has been loaded,
340 which provides a procedure for describing the contents of GOOPS
344 Indicates that Guile has loaded in Readline support, for command line
345 editing (@pxref{Readline Support}).
348 Indicates support for record definition using @code{make-record-type}
349 and friends (@pxref{Records}).
352 Although these tables may seem exhaustive, it is probably unwise in
353 practice to rely on them, as the correspondences between feature symbols
354 and available procedures/behaviour are not strictly defined. If you are
355 writing code that needs to check for the existence of some procedure, it
356 is probably safer to do so directly using the @code{defined?} procedure
357 than to test for the corresponding feature using @code{provided?}.
360 @node Runtime Options
361 @subsection Runtime Options
363 Guile's runtime behaviour can be modified by setting options. For
364 example, is the language that Guile accepts case sensitive, or should
365 the debugger automatically show a backtrace on error?
367 Guile has two levels of interface for managing options: a low-level
368 control interface, and a user-level interface which allows the enabling
369 or disabling of options.
371 Moreover, the options are classified in groups according to whether they
372 configure @emph{reading}, @emph{printing}, @emph{debugging} or
376 * Low level options interfaces::
377 * User level options interfaces::
381 * Evaluator options::
382 * Evaluator trap options::
383 * Examples of option use::
387 @node Low level options interfaces
388 @subsubsection Low Level Options Interfaces
390 @deffn {Scheme Procedure} read-options-interface [setting]
391 @deffnx {Scheme Procedure} eval-options-interface [setting]
392 @deffnx {Scheme Procedure} print-options-interface [setting]
393 @deffnx {Scheme Procedure} debug-options-interface [setting]
394 @deffnx {Scheme Procedure} evaluator-traps-interface [setting]
395 @deffnx {C Function} scm_read_options (setting)
396 @deffnx {C Function} scm_eval_options_interface (setting)
397 @deffnx {C Function} scm_print_options (setting)
398 @deffnx {C Function} scm_debug_options (setting)
399 @deffnx {C Function} scm_evaluator_traps (setting)
400 If one of these procedures is called with no arguments (or with
401 @code{setting == SCM_UNDEFINED} in C code), it returns a list describing
402 the current setting of the read, eval, print, debug or evaluator traps
403 options respectively. The setting of a boolean option is indicated
404 simply by the presence or absence of the option symbol in the list. The
405 setting of a non-boolean option is indicated by the presence of the
406 option symbol immediately followed by the option's current value.
408 If called with a list argument, these procedures interpret the list as
409 an option setting and modify the relevant options accordingly. [FIXME
410 --- this glosses over a lot of details!]
412 If called with any other argument, such as @code{'help}, these
413 procedures return a list of entries like @code{(@var{OPTION-SYMBOL}
414 @var{DEFAULT-VALUE} @var{DOC-STRING})}, with each entry giving the
415 default value and documentation for each option symbol in the relevant
420 @node User level options interfaces
421 @subsubsection User Level Options Interfaces
423 @c @deftp {Data type} scm_option
424 @c @code{scm_option} is used to represent run time options. It can be a
425 @c @emph{boolean} type, in which case the option will be set by the strings
426 @c @code{"yes"} and @code{"no"}. It can be a
430 @deffn {Scheme Procedure} <group>-options [arg]
431 @deffnx {Scheme Procedure} read-options [arg]
432 @deffnx {Scheme Procedure} print-options [arg]
433 @deffnx {Scheme Procedure} debug-options [arg]
434 @deffnx {Scheme Procedure} traps [arg]
435 These functions list the options in their group. The optional argument
436 @var{arg} is a symbol which modifies the form in which the options are
439 With no arguments, @code{<group>-options} returns the values of the
440 options in that particular group. If @var{arg} is @code{'help}, a
441 description of each option is given. If @var{arg} is @code{'full},
442 programmers' options are also shown.
444 @var{arg} can also be a list representing the state of all options. In
445 this case, the list contains single symbols (for enabled boolean
446 options) and symbols followed by values.
448 [FIXME: I don't think 'full is ever any different from 'help. What's
452 @deffn {Scheme Procedure} <group>-enable option-symbol
453 @deffnx {Scheme Procedure} read-enable option-symbol
454 @deffnx {Scheme Procedure} print-enable option-symbol
455 @deffnx {Scheme Procedure} debug-enable option-symbol
456 @deffnx {Scheme Procedure} trap-enable option-symbol
457 These functions set the specified @var{option-symbol} in their options
458 group. They only work if the option is boolean, and throw an error
463 @deffn {Scheme Procedure} <group>-disable option-symbol
464 @deffnx {Scheme Procedure} read-disable option-symbol
465 @deffnx {Scheme Procedure} print-disable option-symbol
466 @deffnx {Scheme Procedure} debug-disable option-symbol
467 @deffnx {Scheme Procedure} trap-disable option-symbol
468 These functions turn off the specified @var{option-symbol} in their
469 options group. They only work if the option is boolean, and throw an
474 @deffn syntax <group>-set! option-symbol value
475 @deffnx syntax read-set! option-symbol value
476 @deffnx syntax print-set! option-symbol value
477 @deffnx syntax debug-set! option-symbol value
478 @deffnx syntax trap-set! option-symbol value
479 These functions set a non-boolean @var{option-symbol} to the specified
485 @subsubsection Reader options
486 @cindex options - read
489 Here is the list of reader options generated by typing
490 @code{(read-options 'full)} in Guile. You can also see the default
494 keywords #f Style of keyword recognition: #f, 'prefix or 'postfix
495 case-insensitive no Convert symbols to lower case.
496 positions yes Record positions of source code expressions.
497 copy no Copy source code expressions.
500 Notice that while Standard Scheme is case insensitive, to ease
501 translation of other Lisp dialects, notably Emacs Lisp, into Guile,
502 Guile is case-sensitive by default.
504 To make Guile case insensitive, you can type
507 (read-enable 'case-insensitive)
510 @node Printing options
511 @subsubsection Printing options
513 Here is the list of print options generated by typing
514 @code{(print-options 'full)} in Guile. You can also see the default
518 quote-keywordish-symbols reader How to print symbols that have a colon
519 as their first or last character. The
520 value '#f' does not quote the colons;
521 '#t' quotes them; 'reader' quotes
522 them when the reader option
523 'keywords' is not '#f'.
525 highlight-prefix @{ The string to print before highlighted values.
526 highlight-suffix @} The string to print after highlighted values.
528 source no Print closures with source.
529 closure-hook #f Hook for printing closures.
533 @node Evaluator options
534 @subsubsection Evaluator options
536 These are the evaluator options with their default values, as they are
537 printed by typing @code{(eval-options 'full)} in Guile.
540 stack 22000 Size of thread stacks (in machine words).
544 @node Evaluator trap options
545 @subsubsection Evaluator trap options
546 [FIXME: These flags, together with their corresponding handlers, are not
547 user level options. Probably this entire section should be moved to the
548 documentation about the low-level programmer debugging interface.]
550 Here is the list of evaluator trap options generated by typing
551 @code{(traps 'full)} in Guile. You can also see the default values.
554 exit-frame no Trap when exiting eval or apply.
555 apply-frame no Trap when entering apply.
556 enter-frame no Trap when eval enters new frame.
557 memoize-symbol no Trap when eval memoizes a symbol's value
558 traps yes Enable evaluator traps.
561 @deffn apply-frame-handler key cont tailp
562 Called when a procedure is being applied.
568 evaluator traps are enabled [traps interface], and
573 @code{apply-frame} is enabled [traps interface], or
575 trace mode is on [debug-options interface], and the procedure being
576 called has the trace property enabled.
580 @var{cont} is a ``debug object'', which means that it can be passed to
581 @code{make-stack} to discover the stack at the point of the trap. The
582 apply frame handler's code can capture a restartable continuation if it
583 wants to by using @code{call-with-current-continuation} in the usual way.
585 @var{tailp} is true if this is a tail call
588 @deffn exit-frame-handler key cont retval
589 Called when a value is returned from a procedure.
595 evaluator traps are enabled [traps interface], and
600 @code{exit-frame} is enabled [traps interface], or
602 trace mode is on [debug-options interface], and the procedure being
603 called has the trace property enabled.
607 @var{cont} is a ``debug object'', which means that it can be passed to
608 @code{make-stack} to discover the stack at the point of the trap. The
609 exit frame handler's code can capture a restartable continuation if it
610 wants to by using @code{call-with-current-continuation} in the usual
613 @var{retval} is the return value.
616 @deffn memoize-symbol-handler key cont expression env
617 Called when the evaluator memoizes the value of a procedure symbol
619 @var{cont} is a ``debug object'', which means that it can be passed to
620 @code{make-stack} to discover the stack at the point of the trap. The
621 exit frame handler's code can capture a restartable continuation if it
622 wants to by using @code{call-with-current-continuation} in the usual
625 @var{retval} is the return value.
628 @deffn {Scheme Procedure} with-traps thunk
629 @deffnx {C Function} scm_with_traps (thunk)
630 Call @var{thunk} with traps enabled.
633 @deffn {Scheme Procedure} debug-object? obj
634 @deffnx {C Function} scm_debug_object_p (obj)
635 Return @code{#t} if @var{obj} is a debug object.
639 @node Debugger options
640 @subsubsection Debugger options
642 Here is the list of print options generated by typing
643 @code{(debug-options 'full)} in Guile. You can also see the default
647 stack 20000 Stack size limit (0 = no check).
648 debug yes Use the debugging evaluator.
649 backtrace no Show backtrace on error.
650 depth 20 Maximal length of printed backtrace.
651 maxdepth 1000 Maximal number of stored backtrace frames.
652 frames 3 Maximum number of tail-recursive frames in backtrace.
653 indent 10 Maximal indentation in backtrace.
654 backwards no Display backtrace in anti-chronological order.
655 procnames yes Record procedure names at definition.
656 trace no *Trace mode.
657 breakpoints no *Check for breakpoints.
658 cheap yes *This option is now obsolete. Setting it has no effect.
661 @subsubheading Stack overflow
663 @cindex overflow, stack
664 @cindex stack overflow
665 Stack overflow errors are caused by a computation trying to use more
666 stack space than has been enabled by the @code{stack} option. They are
670 (non-tail-recursive-factorial 500)
672 ERROR: Stack overflow
673 ABORT: (stack-overflow)
676 If you get an error like this, you can either try rewriting your code to
677 use less stack space, or increase the maximum stack size. To increase
678 the maximum stack size, use @code{debug-set!}, for example:
681 (debug-set! stack 200000)
683 (show-file-name #t stack 200000 debug backtrace depth 20 maxdepth 1000 frames 3 indent 10 width 79 procnames cheap)
685 (non-tail-recursive-factorial 500)
687 122013682599111006870123878542304692625357434@dots{}
690 If you prefer to try rewriting your code, you may be able to save stack
691 space by making some of your procedures @dfn{tail recursive}
692 (@pxref{Tail Calls}).
695 @node Examples of option use
696 @subsubsection Examples of option use
698 Here is an example of a session in which some read and debug option
699 handling procedures are used. In this example, the user
703 Notices that the symbols @code{abc} and @code{aBc} are not the same
705 Examines the @code{read-options}, and sees that @code{case-insensitive}
708 Enables @code{case-insensitive}
710 Verifies that now @code{aBc} and @code{abc} are the same
712 Disables @code{case-insensitive} and enables debugging @code{backtrace}
714 Reproduces the error of displaying @code{aBc} with backtracing enabled
715 [FIXME: this last example is lame because there is no depth in the
716 backtrace. Need to give a better example, possibly putting debugging
717 option examples in a separate session.]
722 guile> (define abc "hello")
726 ERROR: In expression aBc:
727 ERROR: Unbound variable: aBc
730 Type "(backtrace)" to get more information.
731 guile> (read-options 'help)
732 keywords #f Style of keyword recognition: #f, 'prefix or 'postfix
733 case-insensitive no Convert symbols to lower case.
734 positions yes Record positions of source code expressions.
735 copy no Copy source code expressions.
736 guile> (debug-options 'help)
737 stack 20000 Stack size limit (0 = no check).
738 debug yes Use the debugging evaluator.
739 backtrace no Show backtrace on error.
740 depth 20 Maximal length of printed backtrace.
741 maxdepth 1000 Maximal number of stored backtrace frames.
742 frames 3 Maximum number of tail-recursive frames in backtrace.
743 indent 10 Maximal indentation in backtrace.
744 backwards no Display backtrace in anti-chronological order.
745 procnames yes Record procedure names at definition.
746 trace no *Trace mode.
747 breakpoints no *Check for breakpoints.
748 cheap yes *This option is now obsolete. Setting it has no effect.
749 guile> (read-enable 'case-insensitive)
750 (keywords #f case-insensitive positions)
753 guile> (read-disable 'case-insensitive)
754 (keywords #f positions)
755 guile> (debug-enable 'backtrace)
756 (stack 20000 debug backtrace depth 20 maxdepth 1000 frames 3 indent 10 procnames cheap)
762 ERROR: In expression aBc:
763 ERROR: Unbound variable: aBc
770 @c TeX-master: "guile.texi"