Configuration, Features and Runtime Options
===========================================

Why is my Guile different from your Guile?  There are three kinds of possible variation:

  * build differences --- different versions of the Guile source code, installation directories, configuration flags that control pieces of functionality being included or left out, etc.

  * differences in dynamically loaded code --- behaviour and features provided by modules that can be dynamically loaded into a running Guile

  * different runtime options --- some of the options that are provided for controlling Guile's behaviour may be set differently.

Guile provides ``introspective'' variables and procedures to query all of these possible variations at runtime.  For runtime options, it also provides procedures to change the settings of options and to obtain documentation on what the options mean.

Configuration, Build and Installation
-------------------------------------

The following procedures and variables provide information about how Guile was configured, built and installed on your system.

 -- Scheme Procedure: version
 -- Scheme Procedure: effective-version
 -- Scheme Procedure: major-version
 -- Scheme Procedure: minor-version
 -- Scheme Procedure: micro-version
 -- C Function: scm_version ()
 -- C Function: scm_effective_version ()
 -- C Function: scm_major_version ()
 -- C Function: scm_minor_version ()
 -- C Function: scm_micro_version ()
     Return a string describing Guile's full version number, effective version number, major, minor or micro version number, respectively. The effective-version function returns the version name that should remain unchanged during a stable series.  Currently that means that it omits the micro version.  The effective version should be used for items like the versioned share directory name i.e. /usr/share/guile/1.6/

          (version) => "1.6.0"
          (effective-version) => "1.6"
          (major-version) => "1"
          (minor-version) => "6"
          (micro-version) => "0"

 -- Scheme Procedure: %package-data-dir
 -- C Function: scm_sys_package_data_dir ()
     Return the name of the directory under which Guile Scheme files in general are stored.  On Unix-like systems, this is usually /usr/local/share/guile or /usr/share/guile.

 -- Scheme Procedure: %library-dir
 -- C Function: scm_sys_library_dir ()
     Return the name of the directory where the Guile Scheme files that belong to the core Guile installation (as opposed to files from a 3rd party package) are installed.  On Unix-like systems this is usually /usr/local/share/guile/<GUILE_EFFECTIVE_VERSION> or /usr/share/guile/<GUILE_EFFECTIVE_VERSION>;

     for example /usr/local/share/guile/1.6.

 -- Scheme Procedure: %site-dir
 -- C Function: scm_sys_site_dir ()
     Return the name of the directory where Guile Scheme files specific to your site should be installed.  On Unix-like systems, this is usually /usr/local/share/guile/site or /usr/share/guile/site.

 -- Variable: %load-path
     List of directories which should be searched for Scheme modules and libraries.  %load-path is initialized when Guile starts up to (list (%site-dir) (%library-dir) (%package-data-dir)), prepended with the contents of the GUILE_LOAD_PATH environment variable, if it is set.

 -- Scheme Procedure: parse-path path [tail]
 -- C Function: scm_parse_path (path, tail)
     Parse PATH, which is expected to be a colon-separated string, into a list and return the resulting list with TAIL appended. If PATH is #f, TAIL is returned.

 -- Scheme Procedure: search-path path filename [extensions [require-exts?]]
 -- C Function: scm_search_path (path, filename, rest)
     Search PATH for a directory containing a file named FILENAME. The file must be readable, and not a directory. If we find one, return its full filename; otherwise, return #f.  If FILENAME is absolute, return it unchanged. If given, EXTENSIONS is a list of strings; for each directory in PATH, we search for FILENAME concatenated with each EXTENSION.  If REQUIRE-EXTS? is true, require that the returned file name have one of the given extensions; if REQUIRE-EXTS? is not given, it defaults to #f.

     For compatibility with Guile 1.8 and earlier, the C function takes only three arguments

 -- Variable: %guile-build-info
     Alist of information collected during the building of a particular Guile.  Entries can be grouped into one of several categories: directories, env vars, and versioning info.

     Briefly, here are the keys in %guile-build-info, by group:

     directories
          srcdir, top_srcdir, prefix, exec_prefix, bindir, sbindir, libexecdir, datadir, sysconfdir, sharedstatedir, localstatedir, libdir, infodir, mandir, includedir, pkgdatadir, pkglibdir, pkgincludedir

     env vars
          LIBS

     versioning info
          guileversion, libguileinterface, buildstamp

     Values are all strings.  The value for LIBS is typically found also as a part of "guile-config link" output.  The value for guileversion has form X.Y.Z, and should be the same as returned by (version).  The value for libguileinterface is libtool compatible and has form CURRENT:REVISION:AGE (see Library interface versions (GNU Libtool)).  The value for buildstamp is the output of the command date -u +'%Y-%m-%d %T' (UTC).

     In the source, %guile-build-info is initialized from libguile/libpath.h, which is completely generated, so deleting this file before a build guarantees up-to-date values for that build.

 -- Variable: %host-type
     The canonical host type (GNU triplet) of the host Guile was configured for, e.g., "x86_64-unknown-linux-gnu" (see Canonicalizing (The GNU Autoconf Manual)).

Feature Tracking
----------------

Guile has a Scheme level variable *features* that keeps track to some extent of the features that are available in a running Guile. *features* is a list of symbols, for example threads, each of which describes a feature of the running Guile process.

 -- Variable: *features*
     A list of symbols describing available features of the Guile process.

You shouldn't modify the *features* variable directly using set!.  Instead, see the procedures that are provided for this purpose in the following subsection.

Feature Manipulation
....................

To check whether a particular feature is available, use the provided? procedure:

 -- Scheme Procedure: provided? feature
 -- Deprecated Scheme Procedure: feature? feature
     Return #t if the specified FEATURE is available, otherwise #f.

To advertise a feature from your own Scheme code, you can use the provide procedure:

 -- Scheme Procedure: provide feature
     Add FEATURE to the list of available features in this Guile process.

For C code, the equivalent function takes its feature name as a char * argument for convenience:

 -- C Function: void scm_add_feature (const char *str)
     Add a symbol with name STR to the list of available features in this Guile process.

Common Feature Symbols
......................

In general, a particular feature may be available for one of two reasons.  Either because the Guile library was configured and compiled with that feature enabled --- i.e. the feature is built into the library on your system.  Or because some C or Scheme code that was dynamically loaded by Guile has added that feature to the list.

In the first category, here are the features that the current version of Guile may define (depending on how it is built), and what they mean.

array
     Indicates support for arrays (see Arrays).

array-for-each
     Indicates availability of array-for-each and other array mapping procedures (see Arrays).

char-ready?
     Indicates that the char-ready? function is available (see Reading).

complex
     Indicates support for complex numbers.

current-time
     Indicates availability of time-related functions: times, get-internal-run-time and so on (see Time).

debug-extensions
     Indicates that the debugging evaluator is available, together with the options for controlling it.

delay
     Indicates support for promises (see Delayed Evaluation).

EIDs
     Indicates that the geteuid and getegid really return effective user and group IDs (see Processes).

inexact
     Indicates support for inexact numbers.

i/o-extensions
     Indicates availability of the following extended I/O procedures: ftell, redirect-port, dup->fdes, dup2, fileno, isatty?, fdopen, primitive-move->fdes and fdes->ports (see Ports and File Descriptors).

net-db
     Indicates availability of network database functions: scm_gethost, scm_getnet, scm_getproto, scm_getserv, scm_sethost, scm_setnet, scm_setproto, scm_setserv, and their `byXXX' variants (see Network Databases).

posix
     Indicates support for POSIX functions: pipe, getgroups, kill, execl and so on (see POSIX).

random
     Indicates availability of random number generation functions: random, copy-random-state, random-uniform and so on (see Random).

reckless
     Indicates that Guile was built with important checks omitted --- you should never see this!

regex
     Indicates support for POSIX regular expressions using make-regexp, regexp-exec and friends (see Regexp Functions).

socket
     Indicates availability of socket-related functions: socket, bind, connect and so on (see Network Sockets and Communication).

sort
     Indicates availability of sorting and merging functions (see Sorting).

system
     Indicates that the system function is available (see Processes).

threads
     Indicates support for multithreading (see Threads).

values
     Indicates support for multiple return values using values and call-with-values (see Multiple Values).

Available features in the second category depend, by definition, on what additional code your Guile process has loaded in.  The following table lists features that you might encounter for this reason.

defmacro
     Indicates that the defmacro macro is available (see Macros).

describe
     Indicates that the (oop goops describe) module has been loaded, which provides a procedure for describing the contents of GOOPS instances.

readline
     Indicates that Guile has loaded in Readline support, for command line editing (see Readline Support).

record
     Indicates support for record definition using make-record-type and friends (see Records).

Although these tables may seem exhaustive, it is probably unwise in practice to rely on them, as the correspondences between feature symbols and available procedures/behaviour are not strictly defined.  If you are writing code that needs to check for the existence of some procedure, it is probably safer to do so directly using the defined? procedure than to test for the corresponding feature using provided?.

Runtime Options
---------------

Guile's runtime behaviour can be modified by setting options.  For example, is the language that Guile accepts case sensitive, or should the debugger automatically show a backtrace on error?

Guile has two levels of interface for managing options: a low-level control interface, and a user-level interface which allows the enabling or disabling of options.

Moreover, the options are classified in groups according to whether they configure reading, printing, debugging or evaluating.

Low Level Options Interfaces
............................

 -- Scheme Procedure: read-options-interface [setting]
 -- Scheme Procedure: print-options-interface [setting]
 -- Scheme Procedure: debug-options-interface [setting]
 -- C Function: scm_read_options (setting)
 -- C Function: scm_print_options (setting)
 -- C Function: scm_debug_options (setting)
     If one of these procedures is called with no arguments (or with setting == SCM_UNDEFINED in C code), it returns a list describing the current setting of the read, eval, print, debug or evaluator traps options respectively.  The setting of a boolean option is indicated simply by the presence or absence of the option symbol in the list.  The setting of a non-boolean option is indicated by the presence of the option symbol immediately followed by the option's current value.

     If called with a list argument, these procedures interpret the list as an option setting and modify the relevant options accordingly.  [FIXME --- this glosses over a lot of details!]

     If called with any other argument, such as 'help, these procedures return a list of entries like (OPTION-SYMBOL DEFAULT-VALUE DOC-STRING), with each entry giving the default value and documentation for each option symbol in the relevant set of options.

User Level Options Interfaces
.............................

 -- Scheme Procedure: <group>-options [arg]
 -- Scheme Procedure: read-options [arg]
 -- Scheme Procedure: print-options [arg]
 -- Scheme Procedure: debug-options [arg]
     These functions list the options in their group.  The optional argument ARG is a symbol which modifies the form in which the options are presented.

     With no arguments, <group>-options returns the values of the options in that particular group.  If ARG is 'help, a description of each option is given.  If ARG is 'full, programmers' options are also shown.

     ARG can also be a list representing the state of all options.  In this case, the list contains single symbols (for enabled boolean options) and symbols followed by values.

[FIXME: I don't think 'full is ever any different from 'help.  What's up?]

 -- Scheme Procedure: <group>-enable option-symbol
 -- Scheme Procedure: read-enable option-symbol
 -- Scheme Procedure: print-enable option-symbol
 -- Scheme Procedure: debug-enable option-symbol
     These functions set the specified OPTION-SYMBOL in their options group.  They only work if the option is boolean, and throw an error otherwise.

 -- Scheme Procedure: <group>-disable option-symbol
 -- Scheme Procedure: read-disable option-symbol
 -- Scheme Procedure: print-disable option-symbol
 -- Scheme Procedure: debug-disable option-symbol
     These functions turn off the specified OPTION-SYMBOL in their options group.  They only work if the option is boolean, and throw an error otherwise.

 -- syntax: <group>-set! option-symbol value
 -- syntax: read-set! option-symbol value
 -- syntax: print-set! option-symbol value
 -- syntax: debug-set! option-symbol value
     These functions set a non-boolean OPTION-SYMBOL to the specified VALUE.

Reader options
..............

Here is the list of reader options generated by typing (read-options 'full) in Guile.  You can also see the default values.

     copy              no    Copy source code expressions.
     positions         yes   Record positions of source code expressions.
     case-insensitive  no    Convert symbols to lower case.
     keywords          #f    Style of keyword recognition: #f, 'prefix or 'postfix.
     r6rs-hex-escapes  no    Use R6RS variable-length character and string hex escapes.
     square-brackets   yes   Treat `[' and `]' as parentheses, for R6RS compatibility.

Historically, many Scheme implementations have been case-insensitive, treating foo and FOO as the same symbol. Guile has always defaulted to case-sensitivity, as allowed since the R4RS and codified in the R6RS.

Guile also has a reader option to fold all symbols to their lower case. To enable this option, perhaps for compatibility with older Scheme code, you can enter

     (read-enable 'case-insensitive)

For more information on the effect of the r6rs-hex-escapes option, see (see String Syntax).

Printing options
................

Here is the list of print options generated by typing (print-options 'full) in Guile.  You can also see the default values.

     quote-keywordish-symbols reader How to print symbols that have a colon
                                     as their first or last character. The
                                     value '#f' does not quote the colons;
                                     '#t' quotes them; 'reader' quotes
                                     them when the reader option
                                     'keywords' is not '#f'.

     highlight-prefix         {      The string to print before highlighted values.
     highlight-suffix         }      The string to print after highlighted values.

Debugger options
................

Here is the list of print options generated by typing (debug-options 'full) in Guile.  You can also see the default values.

     warn-deprecated	no	Warn when deprecated features are used.
     show-file-name	#t	Show file names and line numbers in backtraces
                             when not `#f'.  A value of `base' displays only
                             base names, while `#t' displays full names.
     stack		1048576	Stack size limit (measured in words; 0 = no check).
     backtrace	yes	Show backtrace on error.
     depth		20	Maximal length of printed backtrace.
     width		79	Maximal width of backtrace.
     backwards	no	Display backtrace in anti-chronological order.

Stack overflow
..............

Stack overflow errors are caused by a computation trying to use more stack space than has been enabled by the stack option.  They are reported like this:

     (non-tail-recursive-factorial 500)
     -|
     ERROR: Stack overflow
     ABORT: (stack-overflow)

If you get an error like this, you can either try rewriting your code to use less stack space, or increase the maximum stack size.  To increase the maximum stack size, use debug-set!, for example:

     (debug-set! stack 200000)
     =>
     (show-file-name #t stack 200000 debug backtrace depth 20
        maxdepth 1000 frames 3 indent 10 width 79 procnames cheap)

     (non-tail-recursive-factorial 500)
     =>
     122013682599111006870123878542304692625357434...

If you prefer to try rewriting your code, you may be able to save stack space by making some of your procedures tail recursive (see Tail Calls).

Examples of option use
......................

Here is an example of a session in which some read and debug option handling procedures are used.  In this example, the user

 1. Notices that the symbols abc and aBc are not the same

 2. Examines the read-options, and sees that case-insensitive is set to ``no''.

 3. Enables case-insensitive

 4. Verifies that now aBc and abc are the same

 5. Disables case-insensitive and enables debugging backtrace

 6. Reproduces the error of displaying aBc with backtracing enabled [FIXME: this last example is lame because there is no depth in the backtrace.  Need to give a better example, possibly putting debugging option examples in a separate session.]

     guile> (define abc "hello")
     guile> abc
     "hello"
     guile> aBc
     ERROR: In expression aBc:
     ERROR: Unbound variable: aBc
     ABORT: (misc-error)

     Type "(backtrace)" to get more information.
     guile> (read-options 'help)
     keywords	#f	Style of keyword recognition: #f, 'prefix or 'postfix
     case-insensitive	no	Convert symbols to lower case.
     positions	yes	Record positions of source code expressions.
     copy		no	Copy source code expressions.
     guile> (debug-options 'help)
     stack		20000	Stack size limit (0 = no check).
     backtrace	no	Show backtrace on error.
     depth		20	Maximal length of printed backtrace.
     backwards	no	Display backtrace in anti-chronological order.
     guile> (read-enable 'case-insensitive)
     (keywords #f case-insensitive positions)
     guile> aBc
     "hello"
     guile> (read-disable 'case-insensitive)
     (keywords #f positions)
     guile> (debug-enable 'backtrace)
     (stack 20000 debug backtrace depth 20 maxdepth 1000 frames 3 indent 10 procnames cheap)
     guile> aBc

     Backtrace:
     0* aBc

     ERROR: In expression aBc:
     ERROR: Unbound variable: aBc
     ABORT: (misc-error)
     guile>