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/2.2/

          (version) => "2.2.0"
          (effective-version) => "2.2"
          (major-version) => "2"
          (minor-version) => "2"
          (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/2.2.

 -- 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.

 -- Scheme Procedure: %site-ccache-dir
 -- C Function: scm_sys_site_ccache_dir ()
     Return the directory where users should install compiled .go files for use with this version of Guile.  Might look something like /usr/lib/guile/EFFECTIVE-VERSION/site-ccache.

 -- 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 pkg-config --libs
     guile-EFFECTIVE-VERSION 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 Venerable Port Interfaces).

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).

fork
     Indicates support for the POSIX fork function (see primitive-fork).

popen
     Indicates support for open-pipe in the (ice-9 popen) module (see Pipes).

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
---------------

There are a number of runtime options available for paramaterizing built-in procedures, like read, and built-in behavior, like what happens on an uncaught error.

For more information on reader options, see Scheme Read.

For more information on print options, see Scheme Write.

Finally, for more information on debugger options, see Debug Options.

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. Quits the recursive prompt

 5. Verifies that now aBc and abc are the same

     scheme@(guile-user)> (define abc "hello")
     scheme@(guile-user)> abc
     $1 = "hello"
     scheme@(guile-user)> aBc
     <unknown-location>: warning: possibly unbound variable `aBc'
     ERROR: In procedure module-lookup:
     ERROR: Unbound variable: aBc
     Entering a new prompt.  Type `,bt' for a backtrace or `,q' to continue.
     scheme@(guile-user) [1]> (read-options 'help)
     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.
     hungry-eol-escapes no   In strings, consume leading whitespace after an
                             escaped end-of-line.
     curly-infix       no    Support SRFI-105 curly infix expressions.
     scheme@(guile-user) [1]> (read-enable 'case-insensitive)
     $2 = (square-brackets keywords #f case-insensitive positions)
     scheme@(guile-user) [1]> ,q
     scheme@(guile-user)> aBc
     $3 = "hello"