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
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 @cindex canonical host type
185 The canonical host type (GNU triplet) of the host Guile was configured
186 for, e.g., @code{"x86_64-unknown-linux-gnu"} (@pxref{Canonicalizing,,,
187 autoconf, The GNU Autoconf Manual}).
190 @node Feature Tracking
191 @subsection Feature Tracking
193 Guile has a Scheme level variable @code{*features*} that keeps track to
194 some extent of the features that are available in a running Guile.
195 @code{*features*} is a list of symbols, for example @code{threads}, each
196 of which describes a feature of the running Guile process.
199 A list of symbols describing available features of the Guile process.
202 You shouldn't modify the @code{*features*} variable directly using
203 @code{set!}. Instead, see the procedures that are provided for this
204 purpose in the following subsection.
207 * Feature Manipulation:: Checking for and advertising features.
208 * Common Feature Symbols:: Commonly available features.
212 @node Feature Manipulation
213 @subsubsection Feature Manipulation
215 To check whether a particular feature is available, use the
216 @code{provided?} procedure:
218 @deffn {Scheme Procedure} provided? feature
219 @deffnx {Deprecated Scheme Procedure} feature? feature
220 Return @code{#t} if the specified @var{feature} is available, otherwise
224 To advertise a feature from your own Scheme code, you can use the
225 @code{provide} procedure:
227 @deffn {Scheme Procedure} provide feature
228 Add @var{feature} to the list of available features in this Guile
232 For C code, the equivalent function takes its feature name as a
233 @code{char *} argument for convenience:
235 @deftypefn {C Function} void scm_add_feature (const char *str)
236 Add a symbol with name @var{str} to the list of available features in
241 @node Common Feature Symbols
242 @subsubsection Common Feature Symbols
244 In general, a particular feature may be available for one of two
245 reasons. Either because the Guile library was configured and compiled
246 with that feature enabled --- i.e. the feature is built into the library
247 on your system. Or because some C or Scheme code that was dynamically
248 loaded by Guile has added that feature to the list.
250 In the first category, here are the features that the current version of
251 Guile may define (depending on how it is built), and what they mean.
255 Indicates support for arrays (@pxref{Arrays}).
258 Indicates availability of @code{array-for-each} and other array mapping
259 procedures (@pxref{Arrays}).
262 Indicates that the @code{char-ready?} function is available
266 Indicates support for complex numbers.
269 Indicates availability of time-related functions: @code{times},
270 @code{get-internal-run-time} and so on (@pxref{Time}).
272 @item debug-extensions
273 Indicates that the debugging evaluator is available, together with the
274 options for controlling it.
277 Indicates support for promises (@pxref{Delayed Evaluation}).
280 Indicates that the @code{geteuid} and @code{getegid} really return
281 effective user and group IDs (@pxref{Processes}).
284 Indicates support for inexact numbers.
287 Indicates availability of the following extended I/O procedures:
288 @code{ftell}, @code{redirect-port}, @code{dup->fdes}, @code{dup2},
289 @code{fileno}, @code{isatty?}, @code{fdopen},
290 @code{primitive-move->fdes} and @code{fdes->ports} (@pxref{Ports and
294 Indicates availability of network database functions:
295 @code{scm_gethost}, @code{scm_getnet}, @code{scm_getproto},
296 @code{scm_getserv}, @code{scm_sethost}, @code{scm_setnet}, @code{scm_setproto},
297 @code{scm_setserv}, and their `byXXX' variants (@pxref{Network
301 Indicates support for POSIX functions: @code{pipe}, @code{getgroups},
302 @code{kill}, @code{execl} and so on (@pxref{POSIX}).
305 Indicates availability of random number generation functions:
306 @code{random}, @code{copy-random-state}, @code{random-uniform} and so on
310 Indicates that Guile was built with important checks omitted --- you
311 should never see this!
314 Indicates support for POSIX regular expressions using
315 @code{make-regexp}, @code{regexp-exec} and friends (@pxref{Regexp
319 Indicates availability of socket-related functions: @code{socket},
320 @code{bind}, @code{connect} and so on (@pxref{Network Sockets and
324 Indicates availability of sorting and merging functions
328 Indicates that the @code{system} function is available
332 Indicates support for multithreading (@pxref{Threads}).
335 Indicates support for multiple return values using @code{values} and
336 @code{call-with-values} (@pxref{Multiple Values}).
339 Available features in the second category depend, by definition, on what
340 additional code your Guile process has loaded in. The following table
341 lists features that you might encounter for this reason.
345 Indicates that the @code{defmacro} macro is available (@pxref{Macros}).
348 Indicates that the @code{(oop goops describe)} module has been loaded,
349 which provides a procedure for describing the contents of GOOPS
353 Indicates that Guile has loaded in Readline support, for command line
354 editing (@pxref{Readline Support}).
357 Indicates support for record definition using @code{make-record-type}
358 and friends (@pxref{Records}).
361 Although these tables may seem exhaustive, it is probably unwise in
362 practice to rely on them, as the correspondences between feature symbols
363 and available procedures/behaviour are not strictly defined. If you are
364 writing code that needs to check for the existence of some procedure, it
365 is probably safer to do so directly using the @code{defined?} procedure
366 than to test for the corresponding feature using @code{provided?}.
369 @node Runtime Options
370 @subsection Runtime Options
372 Guile's runtime behaviour can be modified by setting options. For
373 example, is the language that Guile accepts case sensitive, or should
374 the debugger automatically show a backtrace on error?
376 Guile has two levels of interface for managing options: a low-level
377 control interface, and a user-level interface which allows the enabling
378 or disabling of options.
380 Moreover, the options are classified in groups according to whether they
381 configure @emph{reading}, @emph{printing}, @emph{debugging} or
385 * Low level options interfaces::
386 * User level options interfaces::
390 * Evaluator options::
391 * Evaluator trap options::
392 * Examples of option use::
396 @node Low level options interfaces
397 @subsubsection Low Level Options Interfaces
399 @deffn {Scheme Procedure} read-options-interface [setting]
400 @deffnx {Scheme Procedure} eval-options-interface [setting]
401 @deffnx {Scheme Procedure} print-options-interface [setting]
402 @deffnx {Scheme Procedure} debug-options-interface [setting]
403 @deffnx {Scheme Procedure} evaluator-traps-interface [setting]
404 @deffnx {C Function} scm_read_options (setting)
405 @deffnx {C Function} scm_eval_options_interface (setting)
406 @deffnx {C Function} scm_print_options (setting)
407 @deffnx {C Function} scm_debug_options (setting)
408 @deffnx {C Function} scm_evaluator_traps (setting)
409 If one of these procedures is called with no arguments (or with
410 @code{setting == SCM_UNDEFINED} in C code), it returns a list describing
411 the current setting of the read, eval, print, debug or evaluator traps
412 options respectively. The setting of a boolean option is indicated
413 simply by the presence or absence of the option symbol in the list. The
414 setting of a non-boolean option is indicated by the presence of the
415 option symbol immediately followed by the option's current value.
417 If called with a list argument, these procedures interpret the list as
418 an option setting and modify the relevant options accordingly. [FIXME
419 --- this glosses over a lot of details!]
421 If called with any other argument, such as @code{'help}, these
422 procedures return a list of entries like @code{(@var{OPTION-SYMBOL}
423 @var{DEFAULT-VALUE} @var{DOC-STRING})}, with each entry giving the
424 default value and documentation for each option symbol in the relevant
429 @node User level options interfaces
430 @subsubsection User Level Options Interfaces
432 @c @deftp {Data type} scm_option
433 @c @code{scm_option} is used to represent run time options. It can be a
434 @c @emph{boolean} type, in which case the option will be set by the strings
435 @c @code{"yes"} and @code{"no"}. It can be a
439 @deffn {Scheme Procedure} <group>-options [arg]
440 @deffnx {Scheme Procedure} read-options [arg]
441 @deffnx {Scheme Procedure} print-options [arg]
442 @deffnx {Scheme Procedure} debug-options [arg]
443 @deffnx {Scheme Procedure} traps [arg]
444 These functions list the options in their group. The optional argument
445 @var{arg} is a symbol which modifies the form in which the options are
448 With no arguments, @code{<group>-options} returns the values of the
449 options in that particular group. If @var{arg} is @code{'help}, a
450 description of each option is given. If @var{arg} is @code{'full},
451 programmers' options are also shown.
453 @var{arg} can also be a list representing the state of all options. In
454 this case, the list contains single symbols (for enabled boolean
455 options) and symbols followed by values.
457 [FIXME: I don't think 'full is ever any different from 'help. What's
461 @deffn {Scheme Procedure} <group>-enable option-symbol
462 @deffnx {Scheme Procedure} read-enable option-symbol
463 @deffnx {Scheme Procedure} print-enable option-symbol
464 @deffnx {Scheme Procedure} debug-enable option-symbol
465 @deffnx {Scheme Procedure} trap-enable option-symbol
466 These functions set the specified @var{option-symbol} in their options
467 group. They only work if the option is boolean, and throw an error
472 @deffn {Scheme Procedure} <group>-disable option-symbol
473 @deffnx {Scheme Procedure} read-disable option-symbol
474 @deffnx {Scheme Procedure} print-disable option-symbol
475 @deffnx {Scheme Procedure} debug-disable option-symbol
476 @deffnx {Scheme Procedure} trap-disable option-symbol
477 These functions turn off the specified @var{option-symbol} in their
478 options group. They only work if the option is boolean, and throw an
483 @deffn syntax <group>-set! option-symbol value
484 @deffnx syntax read-set! option-symbol value
485 @deffnx syntax print-set! option-symbol value
486 @deffnx syntax debug-set! option-symbol value
487 @deffnx syntax trap-set! option-symbol value
488 These functions set a non-boolean @var{option-symbol} to the specified
494 @subsubsection Reader options
495 @cindex options - read
498 Here is the list of reader options generated by typing
499 @code{(read-options 'full)} in Guile. You can also see the default
503 keywords #f Style of keyword recognition: #f, 'prefix or 'postfix
504 case-insensitive no Convert symbols to lower case.
505 positions yes Record positions of source code expressions.
506 copy no Copy source code expressions.
509 Notice that while Standard Scheme is case insensitive, to ease
510 translation of other Lisp dialects, notably Emacs Lisp, into Guile,
511 Guile is case-sensitive by default.
513 To make Guile case insensitive, you can type
516 (read-enable 'case-insensitive)
519 @node Printing options
520 @subsubsection Printing options
522 Here is the list of print options generated by typing
523 @code{(print-options 'full)} in Guile. You can also see the default
527 quote-keywordish-symbols reader How to print symbols that have a colon
528 as their first or last character. The
529 value '#f' does not quote the colons;
530 '#t' quotes them; 'reader' quotes
531 them when the reader option
532 'keywords' is not '#f'.
534 highlight-prefix @{ The string to print before highlighted values.
535 highlight-suffix @} The string to print after highlighted values.
537 source no Print closures with source.
538 closure-hook #f Hook for printing closures.
542 @node Evaluator options
543 @subsubsection Evaluator options
545 These are the evaluator options with their default values, as they are
546 printed by typing @code{(eval-options 'full)} in Guile.
549 stack 22000 Size of thread stacks (in machine words).
553 @node Evaluator trap options
554 @subsubsection Evaluator trap options
555 [FIXME: These flags, together with their corresponding handlers, are not
556 user level options. Probably this entire section should be moved to the
557 documentation about the low-level programmer debugging interface.]
559 Here is the list of evaluator trap options generated by typing
560 @code{(traps 'full)} in Guile. You can also see the default values.
563 exit-frame no Trap when exiting eval or apply.
564 apply-frame no Trap when entering apply.
565 enter-frame no Trap when eval enters new frame.
566 memoize-symbol no Trap when eval memoizes a symbol's value
567 traps yes Enable evaluator traps.
570 @deffn apply-frame-handler key cont tailp
571 Called when a procedure is being applied.
577 evaluator traps are enabled [traps interface], and
582 @code{apply-frame} is enabled [traps interface], or
584 trace mode is on [debug-options interface], and the procedure being
585 called has the trace property enabled.
589 @var{cont} is a ``debug object'', which means that it can be passed to
590 @code{make-stack} to discover the stack at the point of the trap. The
591 apply frame handler's code can capture a restartable continuation if it
592 wants to by using @code{call-with-current-continuation} in the usual way.
594 @var{tailp} is true if this is a tail call
597 @deffn exit-frame-handler key cont retval
598 Called when a value is returned from a procedure.
604 evaluator traps are enabled [traps interface], and
609 @code{exit-frame} is enabled [traps interface], or
611 trace mode is on [debug-options interface], and the procedure being
612 called has the trace property enabled.
616 @var{cont} is a ``debug object'', which means that it can be passed to
617 @code{make-stack} to discover the stack at the point of the trap. The
618 exit frame handler's code can capture a restartable continuation if it
619 wants to by using @code{call-with-current-continuation} in the usual
622 @var{retval} is the return value.
625 @deffn memoize-symbol-handler key cont expression env
626 Called when the evaluator memoizes the value of a procedure symbol
628 @var{cont} is a ``debug object'', which means that it can be passed to
629 @code{make-stack} to discover the stack at the point of the trap. The
630 exit frame handler's code can capture a restartable continuation if it
631 wants to by using @code{call-with-current-continuation} in the usual
634 @var{retval} is the return value.
637 @deffn {Scheme Procedure} with-traps thunk
638 @deffnx {C Function} scm_with_traps (thunk)
639 Call @var{thunk} with traps enabled.
642 @deffn {Scheme Procedure} debug-object? obj
643 @deffnx {C Function} scm_debug_object_p (obj)
644 Return @code{#t} if @var{obj} is a debug object.
648 @node Debugger options
649 @subsubsection Debugger options
651 Here is the list of print options generated by typing
652 @code{(debug-options 'full)} in Guile. You can also see the default
656 stack 20000 Stack size limit (0 = no check).
657 debug yes Use the debugging evaluator.
658 backtrace no Show backtrace on error.
659 depth 20 Maximal length of printed backtrace.
660 maxdepth 1000 Maximal number of stored backtrace frames.
661 frames 3 Maximum number of tail-recursive frames in backtrace.
662 indent 10 Maximal indentation in backtrace.
663 backwards no Display backtrace in anti-chronological order.
664 procnames yes Record procedure names at definition.
665 trace no *Trace mode.
666 breakpoints no *Check for breakpoints.
667 cheap yes *This option is now obsolete. Setting it has no effect.
670 @subsubheading Stack overflow
672 @cindex overflow, stack
673 @cindex stack overflow
674 Stack overflow errors are caused by a computation trying to use more
675 stack space than has been enabled by the @code{stack} option. They are
679 (non-tail-recursive-factorial 500)
681 ERROR: Stack overflow
682 ABORT: (stack-overflow)
685 If you get an error like this, you can either try rewriting your code to
686 use less stack space, or increase the maximum stack size. To increase
687 the maximum stack size, use @code{debug-set!}, for example:
690 (debug-set! stack 200000)
692 (show-file-name #t stack 200000 debug backtrace depth 20
693 maxdepth 1000 frames 3 indent 10 width 79 procnames cheap)
695 (non-tail-recursive-factorial 500)
697 122013682599111006870123878542304692625357434@dots{}
700 If you prefer to try rewriting your code, you may be able to save stack
701 space by making some of your procedures @dfn{tail recursive}
702 (@pxref{Tail Calls}).
705 @node Examples of option use
706 @subsubsection Examples of option use
708 Here is an example of a session in which some read and debug option
709 handling procedures are used. In this example, the user
713 Notices that the symbols @code{abc} and @code{aBc} are not the same
715 Examines the @code{read-options}, and sees that @code{case-insensitive}
718 Enables @code{case-insensitive}
720 Verifies that now @code{aBc} and @code{abc} are the same
722 Disables @code{case-insensitive} and enables debugging @code{backtrace}
724 Reproduces the error of displaying @code{aBc} with backtracing enabled
725 [FIXME: this last example is lame because there is no depth in the
726 backtrace. Need to give a better example, possibly putting debugging
727 option examples in a separate session.]
731 guile> (define abc "hello")
735 ERROR: In expression aBc:
736 ERROR: Unbound variable: aBc
739 Type "(backtrace)" to get more information.
740 guile> (read-options 'help)
741 keywords #f Style of keyword recognition: #f, 'prefix or 'postfix
742 case-insensitive no Convert symbols to lower case.
743 positions yes Record positions of source code expressions.
744 copy no Copy source code expressions.
745 guile> (debug-options 'help)
746 stack 20000 Stack size limit (0 = no check).
747 debug yes Use the debugging evaluator.
748 backtrace no Show backtrace on error.
749 depth 20 Maximal length of printed backtrace.
750 maxdepth 1000 Maximal number of stored backtrace frames.
751 frames 3 Maximum number of tail-recursive frames in backtrace.
752 indent 10 Maximal indentation in backtrace.
753 backwards no Display backtrace in anti-chronological order.
754 procnames yes Record procedure names at definition.
755 trace no *Trace mode.
756 breakpoints no *Check for breakpoints.
757 cheap yes *This option is now obsolete. Setting it has no effect.
758 guile> (read-enable 'case-insensitive)
759 (keywords #f case-insensitive positions)
762 guile> (read-disable 'case-insensitive)
763 (keywords #f positions)
764 guile> (debug-enable 'backtrace)
765 (stack 20000 debug backtrace depth 20 maxdepth 1000 frames 3 indent 10 procnames cheap)
771 ERROR: In expression aBc:
772 ERROR: Unbound variable: aBc
779 @c TeX-master: "guile.texi"