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, 2009, 2010
4 @c Free Software Foundation, Inc.
5 @c See the file guile.texi for copying conditions.
7 @node Options and Config
8 @section Configuration, Features and Runtime Options
10 Why is my Guile different from your Guile? There are three kinds of
15 build differences --- different versions of the Guile source code,
16 installation directories, configuration flags that control pieces of
17 functionality being included or left out, etc.
20 differences in dynamically loaded code --- behaviour and features
21 provided by modules that can be dynamically loaded into a running Guile
24 different runtime options --- some of the options that are provided for
25 controlling Guile's behaviour may be set differently.
28 Guile provides ``introspective'' variables and procedures to query all
29 of these possible variations at runtime. For runtime options, it also
30 provides procedures to change the settings of options and to obtain
31 documentation on what the options mean.
34 * Build Config:: Build and installation configuration.
35 * Feature Tracking:: Available features in the Guile process.
36 * Runtime Options:: Controlling Guile's runtime behaviour.
41 @subsection Configuration, Build and Installation
43 The following procedures and variables provide information about how
44 Guile was configured, built and installed on your system.
46 @deffn {Scheme Procedure} version
47 @deffnx {Scheme Procedure} effective-version
48 @deffnx {Scheme Procedure} major-version
49 @deffnx {Scheme Procedure} minor-version
50 @deffnx {Scheme Procedure} micro-version
51 @deffnx {C Function} scm_version ()
52 @deffnx {C Function} scm_effective_version ()
53 @deffnx {C Function} scm_major_version ()
54 @deffnx {C Function} scm_minor_version ()
55 @deffnx {C Function} scm_micro_version ()
56 Return a string describing Guile's full version number, effective
57 version number, major, minor or micro version number, respectively.
58 The @code{effective-version} function returns the version name that
59 should remain unchanged during a stable series. Currently that means
60 that it omits the micro version. The effective version should be used
61 for items like the versioned share directory name
62 i.e. @file{/usr/share/guile/1.6/}
65 (version) @result{} "1.6.0"
66 (effective-version) @result{} "1.6"
67 (major-version) @result{} "1"
68 (minor-version) @result{} "6"
69 (micro-version) @result{} "0"
73 @deffn {Scheme Procedure} %package-data-dir
74 @deffnx {C Function} scm_sys_package_data_dir ()
75 Return the name of the directory under which Guile Scheme files in
76 general are stored. On Unix-like systems, this is usually
77 @file{/usr/local/share/guile} or @file{/usr/share/guile}.
80 @deffn {Scheme Procedure} %library-dir
81 @deffnx {C Function} scm_sys_library_dir ()
82 Return the name of the directory where the Guile Scheme files that
83 belong to the core Guile installation (as opposed to files from a 3rd
84 party package) are installed. On Unix-like systems this is usually
85 @file{/usr/local/share/guile/<GUILE_EFFECTIVE_VERSION>} or
86 @file{/usr/share/guile/<GUILE_EFFECTIVE_VERSION>};
88 @noindent for example @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 [require-exts?]]
116 @deffnx {C Function} scm_search_path (path, filename, rest)
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}. If @var{require-exts?}
124 is true, require that the returned file name have one of the
125 given extensions; if @var{require-exts?} is not given, it
126 defaults to @code{#f}.
128 For compatibility with Guile 1.8 and earlier, the C function takes only
132 @defvar %guile-build-info
133 Alist of information collected during the building of a particular
134 Guile. Entries can be grouped into one of several categories:
135 directories, env vars, and versioning info.
137 Briefly, here are the keys in @code{%guile-build-info}, by group:
139 @cindex @code{srcdir}
140 @cindex @code{top_srcdir}
141 @cindex @code{prefix}
142 @cindex @code{exec_prefix}
143 @cindex @code{bindir}
144 @cindex @code{sbindir}
145 @cindex @code{libexecdir}
146 @cindex @code{datadir}
147 @cindex @code{sysconfdir}
148 @cindex @code{sharedstatedir}
149 @cindex @code{localstatedir}
150 @cindex @code{libdir}
151 @cindex @code{infodir}
152 @cindex @code{mandir}
153 @cindex @code{includedir}
154 @cindex @code{pkgdatadir}
155 @cindex @code{pkglibdir}
156 @cindex @code{pkgincludedir}
159 srcdir, top_srcdir, prefix, exec_prefix, bindir, sbindir, libexecdir,
160 datadir, sysconfdir, sharedstatedir, localstatedir, libdir, infodir,
161 mandir, includedir, pkgdatadir, pkglibdir, pkgincludedir
165 @cindex @code{guileversion}
166 @cindex @code{libguileinterface}
167 @cindex @code{buildstamp}
168 @item versioning info
169 guileversion, libguileinterface, buildstamp
172 Values are all strings. The value for @code{LIBS} is typically found
173 also as a part of "guile-config link" output. The value for
174 @code{guileversion} has form X.Y.Z, and should be the same as returned
175 by @code{(version)}. The value for @code{libguileinterface} is
176 libtool compatible and has form CURRENT:REVISION:AGE
177 (@pxref{Versioning,, Library interface versions, libtool, GNU
178 Libtool}). The value for @code{buildstamp} is the output of the
179 command @samp{date -u +'%Y-%m-%d %T'} (UTC).
181 In the source, @code{%guile-build-info} is initialized from
182 libguile/libpath.h, which is completely generated, so deleting this file
183 before a build guarantees up-to-date values for that build.
187 @cindex canonical host type
190 The canonical host type (GNU triplet) of the host Guile was configured
191 for, e.g., @code{"x86_64-unknown-linux-gnu"} (@pxref{Canonicalizing,,,
192 autoconf, The GNU Autoconf Manual}).
195 @node Feature Tracking
196 @subsection Feature Tracking
198 Guile has a Scheme level variable @code{*features*} that keeps track to
199 some extent of the features that are available in a running Guile.
200 @code{*features*} is a list of symbols, for example @code{threads}, each
201 of which describes a feature of the running Guile process.
204 A list of symbols describing available features of the Guile process.
207 You shouldn't modify the @code{*features*} variable directly using
208 @code{set!}. Instead, see the procedures that are provided for this
209 purpose in the following subsection.
212 * Feature Manipulation:: Checking for and advertising features.
213 * Common Feature Symbols:: Commonly available features.
217 @node Feature Manipulation
218 @subsubsection Feature Manipulation
220 To check whether a particular feature is available, use the
221 @code{provided?} procedure:
223 @deffn {Scheme Procedure} provided? feature
224 @deffnx {Deprecated Scheme Procedure} feature? feature
225 Return @code{#t} if the specified @var{feature} is available, otherwise
229 To advertise a feature from your own Scheme code, you can use the
230 @code{provide} procedure:
232 @deffn {Scheme Procedure} provide feature
233 Add @var{feature} to the list of available features in this Guile
237 For C code, the equivalent function takes its feature name as a
238 @code{char *} argument for convenience:
240 @deftypefn {C Function} void scm_add_feature (const char *str)
241 Add a symbol with name @var{str} to the list of available features in
246 @node Common Feature Symbols
247 @subsubsection Common Feature Symbols
249 In general, a particular feature may be available for one of two
250 reasons. Either because the Guile library was configured and compiled
251 with that feature enabled --- i.e. the feature is built into the library
252 on your system. Or because some C or Scheme code that was dynamically
253 loaded by Guile has added that feature to the list.
255 In the first category, here are the features that the current version of
256 Guile may define (depending on how it is built), and what they mean.
260 Indicates support for arrays (@pxref{Arrays}).
263 Indicates availability of @code{array-for-each} and other array mapping
264 procedures (@pxref{Arrays}).
267 Indicates that the @code{char-ready?} function is available
271 Indicates support for complex numbers.
274 Indicates availability of time-related functions: @code{times},
275 @code{get-internal-run-time} and so on (@pxref{Time}).
277 @item debug-extensions
278 Indicates that the debugging evaluator is available, together with the
279 options for controlling it.
282 Indicates support for promises (@pxref{Delayed Evaluation}).
285 Indicates that the @code{geteuid} and @code{getegid} really return
286 effective user and group IDs (@pxref{Processes}).
289 Indicates support for inexact numbers.
292 Indicates availability of the following extended I/O procedures:
293 @code{ftell}, @code{redirect-port}, @code{dup->fdes}, @code{dup2},
294 @code{fileno}, @code{isatty?}, @code{fdopen},
295 @code{primitive-move->fdes} and @code{fdes->ports} (@pxref{Ports and
299 Indicates availability of network database functions:
300 @code{scm_gethost}, @code{scm_getnet}, @code{scm_getproto},
301 @code{scm_getserv}, @code{scm_sethost}, @code{scm_setnet}, @code{scm_setproto},
302 @code{scm_setserv}, and their `byXXX' variants (@pxref{Network
306 Indicates support for POSIX functions: @code{pipe}, @code{getgroups},
307 @code{kill}, @code{execl} and so on (@pxref{POSIX}).
310 Indicates availability of random number generation functions:
311 @code{random}, @code{copy-random-state}, @code{random-uniform} and so on
315 Indicates that Guile was built with important checks omitted --- you
316 should never see this!
319 Indicates support for POSIX regular expressions using
320 @code{make-regexp}, @code{regexp-exec} and friends (@pxref{Regexp
324 Indicates availability of socket-related functions: @code{socket},
325 @code{bind}, @code{connect} and so on (@pxref{Network Sockets and
329 Indicates availability of sorting and merging functions
333 Indicates that the @code{system} function is available
337 Indicates support for multithreading (@pxref{Threads}).
340 Indicates support for multiple return values using @code{values} and
341 @code{call-with-values} (@pxref{Multiple Values}).
344 Available features in the second category depend, by definition, on what
345 additional code your Guile process has loaded in. The following table
346 lists features that you might encounter for this reason.
350 Indicates that the @code{defmacro} macro is available (@pxref{Macros}).
353 Indicates that the @code{(oop goops describe)} module has been loaded,
354 which provides a procedure for describing the contents of GOOPS
358 Indicates that Guile has loaded in Readline support, for command line
359 editing (@pxref{Readline Support}).
362 Indicates support for record definition using @code{make-record-type}
363 and friends (@pxref{Records}).
366 Although these tables may seem exhaustive, it is probably unwise in
367 practice to rely on them, as the correspondences between feature symbols
368 and available procedures/behaviour are not strictly defined. If you are
369 writing code that needs to check for the existence of some procedure, it
370 is probably safer to do so directly using the @code{defined?} procedure
371 than to test for the corresponding feature using @code{provided?}.
374 @node Runtime Options
375 @subsection Runtime Options
377 Guile's runtime behaviour can be modified by setting options. For
378 example, is the language that Guile accepts case sensitive, or should
379 the debugger automatically show a backtrace on error?
381 Guile has two levels of interface for managing options: a low-level
382 control interface, and a user-level interface which allows the enabling
383 or disabling of options.
385 Moreover, the options are classified in groups according to whether they
386 configure @emph{reading}, @emph{printing}, @emph{debugging} or
390 * Low level options interfaces::
391 * User level options interfaces::
395 * Evaluator options::
396 * Evaluator trap options::
397 * Examples of option use::
401 @node Low level options interfaces
402 @subsubsection Low Level Options Interfaces
404 @deffn {Scheme Procedure} read-options-interface [setting]
405 @deffnx {Scheme Procedure} eval-options-interface [setting]
406 @deffnx {Scheme Procedure} print-options-interface [setting]
407 @deffnx {Scheme Procedure} debug-options-interface [setting]
408 @deffnx {Scheme Procedure} evaluator-traps-interface [setting]
409 @deffnx {C Function} scm_read_options (setting)
410 @deffnx {C Function} scm_eval_options_interface (setting)
411 @deffnx {C Function} scm_print_options (setting)
412 @deffnx {C Function} scm_debug_options (setting)
413 @deffnx {C Function} scm_evaluator_traps (setting)
414 If one of these procedures is called with no arguments (or with
415 @code{setting == SCM_UNDEFINED} in C code), it returns a list describing
416 the current setting of the read, eval, print, debug or evaluator traps
417 options respectively. The setting of a boolean option is indicated
418 simply by the presence or absence of the option symbol in the list. The
419 setting of a non-boolean option is indicated by the presence of the
420 option symbol immediately followed by the option's current value.
422 If called with a list argument, these procedures interpret the list as
423 an option setting and modify the relevant options accordingly. [FIXME
424 --- this glosses over a lot of details!]
426 If called with any other argument, such as @code{'help}, these
427 procedures return a list of entries like @code{(@var{OPTION-SYMBOL}
428 @var{DEFAULT-VALUE} @var{DOC-STRING})}, with each entry giving the
429 default value and documentation for each option symbol in the relevant
434 @node User level options interfaces
435 @subsubsection User Level Options Interfaces
437 @c @deftp {Data type} scm_option
438 @c @code{scm_option} is used to represent run time options. It can be a
439 @c @emph{boolean} type, in which case the option will be set by the strings
440 @c @code{"yes"} and @code{"no"}. It can be a
444 @deffn {Scheme Procedure} <group>-options [arg]
445 @deffnx {Scheme Procedure} read-options [arg]
446 @deffnx {Scheme Procedure} print-options [arg]
447 @deffnx {Scheme Procedure} debug-options [arg]
448 @deffnx {Scheme Procedure} traps [arg]
449 These functions list the options in their group. The optional argument
450 @var{arg} is a symbol which modifies the form in which the options are
453 With no arguments, @code{<group>-options} returns the values of the
454 options in that particular group. If @var{arg} is @code{'help}, a
455 description of each option is given. If @var{arg} is @code{'full},
456 programmers' options are also shown.
458 @var{arg} can also be a list representing the state of all options. In
459 this case, the list contains single symbols (for enabled boolean
460 options) and symbols followed by values.
462 [FIXME: I don't think 'full is ever any different from 'help. What's
466 @deffn {Scheme Procedure} <group>-enable option-symbol
467 @deffnx {Scheme Procedure} read-enable option-symbol
468 @deffnx {Scheme Procedure} print-enable option-symbol
469 @deffnx {Scheme Procedure} debug-enable option-symbol
470 @deffnx {Scheme Procedure} trap-enable option-symbol
471 These functions set the specified @var{option-symbol} in their options
472 group. They only work if the option is boolean, and throw an error
477 @deffn {Scheme Procedure} <group>-disable option-symbol
478 @deffnx {Scheme Procedure} read-disable option-symbol
479 @deffnx {Scheme Procedure} print-disable option-symbol
480 @deffnx {Scheme Procedure} debug-disable option-symbol
481 @deffnx {Scheme Procedure} trap-disable option-symbol
482 These functions turn off the specified @var{option-symbol} in their
483 options group. They only work if the option is boolean, and throw an
488 @deffn syntax <group>-set! option-symbol value
489 @deffnx syntax read-set! option-symbol value
490 @deffnx syntax print-set! option-symbol value
491 @deffnx syntax debug-set! option-symbol value
492 @deffnx syntax trap-set! option-symbol value
493 These functions set a non-boolean @var{option-symbol} to the specified
499 @subsubsection Reader options
500 @cindex options - read
503 Here is the list of reader options generated by typing
504 @code{(read-options 'full)} in Guile. You can also see the default
508 keywords #f Style of keyword recognition: #f, 'prefix or 'postfix
509 case-insensitive no Convert symbols to lower case.
510 positions yes Record positions of source code expressions.
511 copy no Copy source code expressions.
512 r6rs-hex-escapes no Use R6RS-style string and character hex escapes
515 Notice that while Standard Scheme is case insensitive, to ease
516 translation of other Lisp dialects, notably Emacs Lisp, into Guile,
517 Guile is case-sensitive by default.
519 To make Guile case insensitive, you can type
522 (read-enable 'case-insensitive)
525 For more information on the effect of the @code{r6rs-hex-escapes} option, see
526 (@pxref{Characters}) and (@pxref{String Syntax}).
528 @node Printing options
529 @subsubsection Printing options
531 Here is the list of print options generated by typing
532 @code{(print-options 'full)} in Guile. You can also see the default
536 quote-keywordish-symbols reader How to print symbols that have a colon
537 as their first or last character. The
538 value '#f' does not quote the colons;
539 '#t' quotes them; 'reader' quotes
540 them when the reader option
541 'keywords' is not '#f'.
543 highlight-prefix @{ The string to print before highlighted values.
544 highlight-suffix @} The string to print after highlighted values.
546 source no Print closures with source.
547 closure-hook #f Hook for printing closures.
551 @node Evaluator options
552 @subsubsection Evaluator options
554 These are the evaluator options with their default values, as they are
555 printed by typing @code{(eval-options 'full)} in Guile.
558 stack 22000 Size of thread stacks (in machine words).
562 @node Evaluator trap options
563 @subsubsection Evaluator trap options
564 [FIXME: These flags, together with their corresponding handlers, are not
565 user level options. Probably this entire section should be moved to the
566 documentation about the low-level programmer debugging interface.]
568 Here is the list of evaluator trap options generated by typing
569 @code{(traps 'full)} in Guile. You can also see the default values.
572 exit-frame no Trap when exiting eval or apply.
573 apply-frame no Trap when entering apply.
574 enter-frame no Trap when eval enters new frame.
575 memoize-symbol no Trap when eval memoizes a symbol's value
576 traps yes Enable evaluator traps.
579 @deffn apply-frame-handler key cont tailp
580 Called when a procedure is being applied.
586 evaluator traps are enabled [traps interface], and
591 @code{apply-frame} is enabled [traps interface], or
593 trace mode is on [debug-options interface], and the procedure being
594 called has the trace property enabled.
598 @var{cont} is a ``debug object'', which means that it can be passed to
599 @code{make-stack} to discover the stack at the point of the trap. The
600 apply frame handler's code can capture a restartable continuation if it
601 wants to by using @code{call-with-current-continuation} in the usual way.
603 @var{tailp} is true if this is a tail call
606 @deffn exit-frame-handler key cont retval
607 Called when a value is returned from a procedure.
613 evaluator traps are enabled [traps interface], and
618 @code{exit-frame} is enabled [traps interface], or
620 trace mode is on [debug-options interface], and the procedure being
621 called has the trace property enabled.
625 @var{cont} is a ``debug object'', which means that it can be passed to
626 @code{make-stack} to discover the stack at the point of the trap. The
627 exit frame handler's code can capture a restartable continuation if it
628 wants to by using @code{call-with-current-continuation} in the usual
631 @var{retval} is the return value.
634 @deffn memoize-symbol-handler key cont expression env
635 Called when the evaluator memoizes the value of a procedure symbol
637 @var{cont} is a ``debug object'', which means that it can be passed to
638 @code{make-stack} to discover the stack at the point of the trap. The
639 exit frame handler's code can capture a restartable continuation if it
640 wants to by using @code{call-with-current-continuation} in the usual
643 @var{retval} is the return value.
646 @deffn {Scheme Procedure} with-traps thunk
647 @deffnx {C Function} scm_with_traps (thunk)
648 Call @var{thunk} with traps enabled.
651 @deffn {Scheme Procedure} debug-object? obj
652 @deffnx {C Function} scm_debug_object_p (obj)
653 Return @code{#t} if @var{obj} is a debug object.
657 @node Debugger options
658 @subsubsection Debugger options
660 Here is the list of print options generated by typing
661 @code{(debug-options 'full)} in Guile. You can also see the default
665 stack 20000 Stack size limit (0 = no check).
666 debug yes Use the debugging evaluator.
667 backtrace no Show backtrace on error.
668 depth 20 Maximal length of printed backtrace.
669 maxdepth 1000 Maximal number of stored backtrace frames.
670 frames 3 Maximum number of tail-recursive frames in backtrace.
671 indent 10 Maximal indentation in backtrace.
672 backwards no Display backtrace in anti-chronological order.
673 procnames yes Record procedure names at definition.
674 trace no *Trace mode.
675 breakpoints no *Check for breakpoints.
676 cheap yes *This option is now obsolete. Setting it has no effect.
679 @subsubheading Stack overflow
681 @cindex overflow, stack
682 @cindex stack overflow
683 Stack overflow errors are caused by a computation trying to use more
684 stack space than has been enabled by the @code{stack} option. They are
688 (non-tail-recursive-factorial 500)
690 ERROR: Stack overflow
691 ABORT: (stack-overflow)
694 If you get an error like this, you can either try rewriting your code to
695 use less stack space, or increase the maximum stack size. To increase
696 the maximum stack size, use @code{debug-set!}, for example:
699 (debug-set! stack 200000)
701 (show-file-name #t stack 200000 debug backtrace depth 20
702 maxdepth 1000 frames 3 indent 10 width 79 procnames cheap)
704 (non-tail-recursive-factorial 500)
706 122013682599111006870123878542304692625357434@dots{}
709 If you prefer to try rewriting your code, you may be able to save stack
710 space by making some of your procedures @dfn{tail recursive}
711 (@pxref{Tail Calls}).
714 @node Examples of option use
715 @subsubsection Examples of option use
717 Here is an example of a session in which some read and debug option
718 handling procedures are used. In this example, the user
722 Notices that the symbols @code{abc} and @code{aBc} are not the same
724 Examines the @code{read-options}, and sees that @code{case-insensitive}
727 Enables @code{case-insensitive}
729 Verifies that now @code{aBc} and @code{abc} are the same
731 Disables @code{case-insensitive} and enables debugging @code{backtrace}
733 Reproduces the error of displaying @code{aBc} with backtracing enabled
734 [FIXME: this last example is lame because there is no depth in the
735 backtrace. Need to give a better example, possibly putting debugging
736 option examples in a separate session.]
740 guile> (define abc "hello")
744 ERROR: In expression aBc:
745 ERROR: Unbound variable: aBc
748 Type "(backtrace)" to get more information.
749 guile> (read-options 'help)
750 keywords #f Style of keyword recognition: #f, 'prefix or 'postfix
751 case-insensitive no Convert symbols to lower case.
752 positions yes Record positions of source code expressions.
753 copy no Copy source code expressions.
754 guile> (debug-options 'help)
755 stack 20000 Stack size limit (0 = no check).
756 debug yes Use the debugging evaluator.
757 backtrace no Show backtrace on error.
758 depth 20 Maximal length of printed backtrace.
759 maxdepth 1000 Maximal number of stored backtrace frames.
760 frames 3 Maximum number of tail-recursive frames in backtrace.
761 indent 10 Maximal indentation in backtrace.
762 backwards no Display backtrace in anti-chronological order.
763 procnames yes Record procedure names at definition.
764 trace no *Trace mode.
765 breakpoints no *Check for breakpoints.
766 cheap yes *This option is now obsolete. Setting it has no effect.
767 guile> (read-enable 'case-insensitive)
768 (keywords #f case-insensitive positions)
771 guile> (read-disable 'case-insensitive)
772 (keywords #f positions)
773 guile> (debug-enable 'backtrace)
774 (stack 20000 debug backtrace depth 20 maxdepth 1000 frames 3 indent 10 procnames cheap)
780 ERROR: In expression aBc:
781 ERROR: Unbound variable: aBc
788 @c TeX-master: "guile.texi"