2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2006,
4 @c 2008, 2009, 2010, 2011, 2012, 2013
5 @c Free Software Foundation, Inc.
6 @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/2.2/}
66 (version) @result{} "2.2.0"
67 (effective-version) @result{} "2.2"
68 (major-version) @result{} "2"
69 (minor-version) @result{} "2"
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/@var{GUILE_EFFECTIVE_VERSION}} or
87 @file{/usr/share/guile/@var{GUILE_EFFECTIVE_VERSION}};
90 for example @file{/usr/local/share/guile/2.2}.
93 @deffn {Scheme Procedure} %site-dir
94 @deffnx {C Function} scm_sys_site_dir ()
95 Return the name of the directory where Guile Scheme files specific to
96 your site should be installed. On Unix-like systems, this is usually
97 @file{/usr/local/share/guile/site} or @file{/usr/share/guile/site}.
100 @deffn {Scheme Procedure} %site-ccache-dir
101 @deffnx {C Function} scm_sys_site_ccache_dir ()
102 Return the directory where users should install compiled @code{.go}
103 files for use with this version of Guile. Might look something like
104 @file{/usr/lib/guile/@value{EFFECTIVE-VERSION}/site-ccache}.
107 @defvar %guile-build-info
108 Alist of information collected during the building of a particular
109 Guile. Entries can be grouped into one of several categories:
110 directories, env vars, and versioning info.
112 Briefly, here are the keys in @code{%guile-build-info}, by group:
114 @cindex @code{srcdir}
115 @cindex @code{top_srcdir}
116 @cindex @code{prefix}
117 @cindex @code{exec_prefix}
118 @cindex @code{bindir}
119 @cindex @code{sbindir}
120 @cindex @code{libexecdir}
121 @cindex @code{datadir}
122 @cindex @code{sysconfdir}
123 @cindex @code{sharedstatedir}
124 @cindex @code{localstatedir}
125 @cindex @code{libdir}
126 @cindex @code{infodir}
127 @cindex @code{mandir}
128 @cindex @code{includedir}
129 @cindex @code{pkgdatadir}
130 @cindex @code{pkglibdir}
131 @cindex @code{pkgincludedir}
134 srcdir, top_srcdir, prefix, exec_prefix, bindir, sbindir, libexecdir,
135 datadir, sysconfdir, sharedstatedir, localstatedir, libdir, infodir,
136 mandir, includedir, pkgdatadir, pkglibdir, pkgincludedir
140 @cindex @code{guileversion}
141 @cindex @code{libguileinterface}
142 @cindex @code{buildstamp}
143 @item versioning info
144 guileversion, libguileinterface, buildstamp
147 Values are all strings. The value for @code{LIBS} is typically found
148 also as a part of @code{pkg-config --libs
149 guile-@value{EFFECTIVE-VERSION}} output. The value for
150 @code{guileversion} has form X.Y.Z, and should be the same as returned
151 by @code{(version)}. The value for @code{libguileinterface} is libtool
152 compatible and has form CURRENT:REVISION:AGE (@pxref{Versioning,,
153 Library interface versions, libtool, GNU Libtool}). The value for
154 @code{buildstamp} is the output of the command @samp{date -u +'%Y-%m-%d
157 In the source, @code{%guile-build-info} is initialized from
158 libguile/libpath.h, which is completely generated, so deleting this file
159 before a build guarantees up-to-date values for that build.
163 @cindex canonical host type
166 The canonical host type (GNU triplet) of the host Guile was configured
167 for, e.g., @code{"x86_64-unknown-linux-gnu"} (@pxref{Canonicalizing,,,
168 autoconf, The GNU Autoconf Manual}).
171 @node Feature Tracking
172 @subsection Feature Tracking
174 Guile has a Scheme level variable @code{*features*} that keeps track to
175 some extent of the features that are available in a running Guile.
176 @code{*features*} is a list of symbols, for example @code{threads}, each
177 of which describes a feature of the running Guile process.
180 A list of symbols describing available features of the Guile process.
183 You shouldn't modify the @code{*features*} variable directly using
184 @code{set!}. Instead, see the procedures that are provided for this
185 purpose in the following subsection.
188 * Feature Manipulation:: Checking for and advertising features.
189 * Common Feature Symbols:: Commonly available features.
193 @node Feature Manipulation
194 @subsubsection Feature Manipulation
196 To check whether a particular feature is available, use the
197 @code{provided?} procedure:
199 @deffn {Scheme Procedure} provided? feature
200 @deffnx {Deprecated Scheme Procedure} feature? feature
201 Return @code{#t} if the specified @var{feature} is available, otherwise
205 To advertise a feature from your own Scheme code, you can use the
206 @code{provide} procedure:
208 @deffn {Scheme Procedure} provide feature
209 Add @var{feature} to the list of available features in this Guile
213 For C code, the equivalent function takes its feature name as a
214 @code{char *} argument for convenience:
216 @deftypefn {C Function} void scm_add_feature (const char *str)
217 Add a symbol with name @var{str} to the list of available features in
222 @node Common Feature Symbols
223 @subsubsection Common Feature Symbols
225 In general, a particular feature may be available for one of two
226 reasons. Either because the Guile library was configured and compiled
227 with that feature enabled --- i.e.@: the feature is built into the library
228 on your system. Or because some C or Scheme code that was dynamically
229 loaded by Guile has added that feature to the list.
231 In the first category, here are the features that the current version of
232 Guile may define (depending on how it is built), and what they mean.
236 Indicates support for arrays (@pxref{Arrays}).
239 Indicates availability of @code{array-for-each} and other array mapping
240 procedures (@pxref{Arrays}).
243 Indicates that the @code{char-ready?} function is available
247 Indicates support for complex numbers.
250 Indicates availability of time-related functions: @code{times},
251 @code{get-internal-run-time} and so on (@pxref{Time}).
253 @item debug-extensions
254 Indicates that the debugging evaluator is available, together with the
255 options for controlling it.
258 Indicates support for promises (@pxref{Delayed Evaluation}).
261 Indicates that the @code{geteuid} and @code{getegid} really return
262 effective user and group IDs (@pxref{Processes}).
265 Indicates support for inexact numbers.
268 Indicates availability of the following extended I/O procedures:
269 @code{ftell}, @code{redirect-port}, @code{dup->fdes}, @code{dup2},
270 @code{fileno}, @code{isatty?}, @code{fdopen},
271 @code{primitive-move->fdes} and @code{fdes->ports} (@pxref{Ports and
275 Indicates availability of network database functions:
276 @code{scm_gethost}, @code{scm_getnet}, @code{scm_getproto},
277 @code{scm_getserv}, @code{scm_sethost}, @code{scm_setnet}, @code{scm_setproto},
278 @code{scm_setserv}, and their `byXXX' variants (@pxref{Network
282 Indicates support for POSIX functions: @code{pipe}, @code{getgroups},
283 @code{kill}, @code{execl} and so on (@pxref{POSIX}).
286 Indicates support for the POSIX @code{fork} function (@pxref{Processes,
287 @code{primitive-fork}}). This is a prerequisite for the @code{(ice-9
288 popen)} module (@pxref{Pipes}).
291 Indicates availability of random number generation functions:
292 @code{random}, @code{copy-random-state}, @code{random-uniform} and so on
296 Indicates that Guile was built with important checks omitted --- you
297 should never see this!
300 Indicates support for POSIX regular expressions using
301 @code{make-regexp}, @code{regexp-exec} and friends (@pxref{Regexp
305 Indicates availability of socket-related functions: @code{socket},
306 @code{bind}, @code{connect} and so on (@pxref{Network Sockets and
310 Indicates availability of sorting and merging functions
314 Indicates that the @code{system} function is available
318 Indicates support for multithreading (@pxref{Threads}).
321 Indicates support for multiple return values using @code{values} and
322 @code{call-with-values} (@pxref{Multiple Values}).
325 Available features in the second category depend, by definition, on what
326 additional code your Guile process has loaded in. The following table
327 lists features that you might encounter for this reason.
331 Indicates that the @code{defmacro} macro is available (@pxref{Macros}).
334 Indicates that the @code{(oop goops describe)} module has been loaded,
335 which provides a procedure for describing the contents of GOOPS
339 Indicates that Guile has loaded in Readline support, for command line
340 editing (@pxref{Readline Support}).
343 Indicates support for record definition using @code{make-record-type}
344 and friends (@pxref{Records}).
347 Although these tables may seem exhaustive, it is probably unwise in
348 practice to rely on them, as the correspondences between feature symbols
349 and available procedures/behaviour are not strictly defined. If you are
350 writing code that needs to check for the existence of some procedure, it
351 is probably safer to do so directly using the @code{defined?} procedure
352 than to test for the corresponding feature using @code{provided?}.
355 @node Runtime Options
356 @subsection Runtime Options
358 There are a number of runtime options available for paramaterizing
359 built-in procedures, like @code{read}, and built-in behavior, like what
360 happens on an uncaught error.
362 For more information on reader options, @xref{Scheme Read}.
364 For more information on print options, @xref{Scheme Write}.
366 Finally, for more information on debugger options, @xref{Debug
369 @subsubsection Examples of option use
371 Here is an example of a session in which some read and debug option
372 handling procedures are used. In this example, the user
376 Notices that the symbols @code{abc} and @code{aBc} are not the same
378 Examines the @code{read-options}, and sees that @code{case-insensitive}
381 Enables @code{case-insensitive}
383 Quits the recursive prompt
385 Verifies that now @code{aBc} and @code{abc} are the same
389 scheme@@(guile-user)> (define abc "hello")
390 scheme@@(guile-user)> abc
392 scheme@@(guile-user)> aBc
393 <unknown-location>: warning: possibly unbound variable `aBc'
394 ERROR: In procedure module-lookup:
395 ERROR: Unbound variable: aBc
396 Entering a new prompt. Type `,bt' for a backtrace or `,q' to continue.
397 scheme@@(guile-user) [1]> (read-options 'help)
398 copy no Copy source code expressions.
399 positions yes Record positions of source code expressions.
400 case-insensitive no Convert symbols to lower case.
401 keywords #f Style of keyword recognition: #f, 'prefix or 'postfix.
402 r6rs-hex-escapes no Use R6RS variable-length character and string hex escapes.
403 square-brackets yes Treat `[' and `]' as parentheses, for R6RS compatibility.
404 hungry-eol-escapes no In strings, consume leading whitespace after an
406 curly-infix no Support SRFI-105 curly infix expressions.
407 scheme@@(guile-user) [1]> (read-enable 'case-insensitive)
408 $2 = (square-brackets keywords #f case-insensitive positions)
409 scheme@@(guile-user) [1]> ,q
410 scheme@@(guile-user)> aBc
416 @c TeX-master: "guile.texi"