doc/ref/api-options.texi

   1 @c -*-texinfo-*-
   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, 2011
   4 @c   Free Software Foundation, Inc.
   5 @c See the file guile.texi for copying conditions.
   6
   7 @node Options and Config
   8 @section Configuration, Features and Runtime Options
   9
  10 Why is my Guile different from your Guile?  There are three kinds of
  11 possible variation:
  12
  13 @itemize @bullet
  14 @item
  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.
  18
  19 @item
  20 differences in dynamically loaded code --- behaviour and features
  21 provided by modules that can be dynamically loaded into a running Guile
  22
  23 @item
  24 different runtime options --- some of the options that are provided for
  25 controlling Guile's behaviour may be set differently.
  26 @end itemize
  27
  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.
  32
  33 @menu
  34 * Build Config::                Build and installation configuration.
  35 * Feature Tracking::            Available features in the Guile process.
  36 * Runtime Options::             Controlling Guile's runtime behaviour.
  37 @end menu
  38
  39
  40 @node Build Config
  41 @subsection Configuration, Build and Installation
  42
  43 The following procedures and variables provide information about how
  44 Guile was configured, built and installed on your system.
  45
  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/}
  63
  64 @lisp
  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"
  70 @end lisp
  71 @end deffn
  72
  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}.
  78 @end deffn
  79
  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>};
  87
  88 @noindent for example @file{/usr/local/share/guile/1.6}.
  89 @end deffn
  90
  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}.
  96 @end deffn
  97
  98 @cindex @env{GUILE_LOAD_PATH}
  99 @defvar %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 @env{GUILE_LOAD_PATH} environment variable,
 104 if it is set.
 105 @end defvar
 106
 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}
 112 is returned.
 113 @end deffn
 114
 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}.
 127
 128 For compatibility with Guile 1.8 and earlier, the C function takes only
 129 three arguments
 130 @end deffn
 131
 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.
 136
 137 Briefly, here are the keys in @code{%guile-build-info}, by group:
 138
 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}
 157 @table @asis
 158 @item   directories
 159 srcdir, top_srcdir, prefix, exec_prefix, bindir, sbindir, libexecdir,
 160 datadir, sysconfdir, sharedstatedir, localstatedir, libdir, infodir,
 161 mandir, includedir, pkgdatadir, pkglibdir, pkgincludedir
 162 @cindex @code{LIBS}
 163 @item   env vars
 164 LIBS
 165 @cindex @code{guileversion}
 166 @cindex @code{libguileinterface}
 167 @cindex @code{buildstamp}
 168 @item   versioning info
 169 guileversion, libguileinterface, buildstamp
 170 @end table
 171
 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).
 180
 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.
 184 @end defvar
 185
 186 @cindex GNU triplet
 187 @cindex canonical host type
 188
 189 @defvar %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}).
 193 @end defvar
 194
 195 @node Feature Tracking
 196 @subsection Feature Tracking
 197
 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.
 202
 203 @defvar *features*
 204 A list of symbols describing available features of the Guile process.
 205 @end defvar
 206
 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.
 210
 211 @menu
 212 * Feature Manipulation::        Checking for and advertising features.
 213 * Common Feature Symbols::      Commonly available features.
 214 @end menu
 215
 216
 217 @node Feature Manipulation
 218 @subsubsection Feature Manipulation
 219
 220 To check whether a particular feature is available, use the
 221 @code{provided?} procedure:
 222
 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
 226 @code{#f}.
 227 @end deffn
 228
 229 To advertise a feature from your own Scheme code, you can use the
 230 @code{provide} procedure:
 231
 232 @deffn {Scheme Procedure} provide feature
 233 Add @var{feature} to the list of available features in this Guile
 234 process.
 235 @end deffn
 236
 237 For C code, the equivalent function takes its feature name as a
 238 @code{char *} argument for convenience:
 239
 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
 242 this Guile process.
 243 @end deftypefn
 244
 245
 246 @node Common Feature Symbols
 247 @subsubsection Common Feature Symbols
 248
 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.
 254
 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.
 257
 258 @table @code
 259 @item array
 260 Indicates support for arrays (@pxref{Arrays}).
 261
 262 @item array-for-each
 263 Indicates availability of @code{array-for-each} and other array mapping
 264 procedures (@pxref{Arrays}).
 265
 266 @item char-ready?
 267 Indicates that the @code{char-ready?} function is available
 268 (@pxref{Reading}).
 269
 270 @item complex
 271 Indicates support for complex numbers.
 272
 273 @item current-time
 274 Indicates availability of time-related functions: @code{times},
 275 @code{get-internal-run-time} and so on (@pxref{Time}).
 276
 277 @item debug-extensions
 278 Indicates that the debugging evaluator is available, together with the
 279 options for controlling it.
 280
 281 @item delay
 282 Indicates support for promises (@pxref{Delayed Evaluation}).
 283
 284 @item EIDs
 285 Indicates that the @code{geteuid} and @code{getegid} really return
 286 effective user and group IDs (@pxref{Processes}).
 287
 288 @item inexact
 289 Indicates support for inexact numbers.
 290
 291 @item i/o-extensions
 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
 296 File Descriptors}).
 297
 298 @item net-db
 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
 303 Databases}).
 304
 305 @item posix
 306 Indicates support for POSIX functions: @code{pipe}, @code{getgroups},
 307 @code{kill}, @code{execl} and so on (@pxref{POSIX}).
 308
 309 @item random
 310 Indicates availability of random number generation functions:
 311 @code{random}, @code{copy-random-state}, @code{random-uniform} and so on
 312 (@pxref{Random}).
 313
 314 @item reckless
 315 Indicates that Guile was built with important checks omitted --- you
 316 should never see this!
 317
 318 @item regex
 319 Indicates support for POSIX regular expressions using
 320 @code{make-regexp}, @code{regexp-exec} and friends (@pxref{Regexp
 321 Functions}).
 322
 323 @item socket
 324 Indicates availability of socket-related functions: @code{socket},
 325 @code{bind}, @code{connect} and so on (@pxref{Network Sockets and
 326 Communication}).
 327
 328 @item sort
 329 Indicates availability of sorting and merging functions
 330 (@pxref{Sorting}).
 331
 332 @item system
 333 Indicates that the @code{system} function is available
 334 (@pxref{Processes}).
 335
 336 @item threads
 337 Indicates support for multithreading (@pxref{Threads}).
 338
 339 @item values
 340 Indicates support for multiple return values using @code{values} and
 341 @code{call-with-values} (@pxref{Multiple Values}).
 342 @end table
 343
 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.
 347
 348 @table @code
 349 @item defmacro
 350 Indicates that the @code{defmacro} macro is available (@pxref{Macros}).
 351
 352 @item describe
 353 Indicates that the @code{(oop goops describe)} module has been loaded,
 354 which provides a procedure for describing the contents of GOOPS
 355 instances.
 356
 357 @item readline
 358 Indicates that Guile has loaded in Readline support, for command line
 359 editing (@pxref{Readline Support}).
 360
 361 @item record
 362 Indicates support for record definition using @code{make-record-type}
 363 and friends (@pxref{Records}).
 364 @end table
 365
 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?}.
 372
 373
 374 @node Runtime Options
 375 @subsection Runtime Options
 376
 377 There are a number of runtime options available for paramaterizing
 378 built-in procedures, like @code{read}, and built-in behavior, like what
 379 happens on an uncaught error.
 380
 381 For more information on reader options, @xref{Scheme Read}.
 382
 383 For more information on print options, @xref{Scheme Write}.
 384
 385 Finally, for more information on debugger options, @xref{Debug
 386 Options}.
 387
 388 @subsubsection Examples of option use
 389
 390 Here is an example of a session in which some read and debug option
 391 handling procedures are used.  In this example, the user
 392
 393 @enumerate
 394 @item
 395 Notices that the symbols @code{abc} and @code{aBc} are not the same
 396 @item
 397 Examines the @code{read-options}, and sees that @code{case-insensitive}
 398 is set to ``no''.
 399 @item
 400 Enables @code{case-insensitive}
 401 @item
 402 Quits the recursive prompt
 403 @item
 404 Verifies that now @code{aBc} and @code{abc} are the same
 405 @end enumerate
 406
 407 @smalllisp
 408 scheme@@(guile-user)> (define abc "hello")
 409 scheme@@(guile-user)> abc
 410 $1 = "hello"
 411 scheme@@(guile-user)> aBc
 412 <unknown-location>: warning: possibly unbound variable `aBc'
 413 ERROR: In procedure module-lookup:
 414 ERROR: Unbound variable: aBc
 415 Entering a new prompt.  Type `,bt' for a backtrace or `,q' to continue.
 416 scheme@@(guile-user) [1]> (read-options 'help)
 417 copy              no    Copy source code expressions.
 418 positions         yes   Record positions of source code expressions.
 419 case-insensitive  no    Convert symbols to lower case.
 420 keywords          #f    Style of keyword recognition: #f, 'prefix or 'postfix.
 421 r6rs-hex-escapes  no    Use R6RS variable-length character and string hex escapes.
 422 square-brackets   yes   Treat `[' and `]' as parentheses, for R6RS compatibility.
 423 hungry-eol-escapes no   In strings, consume leading whitespace after an
 424                         escaped end-of-line.
 425 scheme@@(guile-user) [1]> (read-enable 'case-insensitive)
 426 $2 = (square-brackets keywords #f case-insensitive positions)
 427 scheme@@(guile-user) [1]> ,q
 428 scheme@@(guile-user)> aBc
 429 $3 = "hello"
 430 @end smalllisp
 431
 432
 433 @c Local Variables:
 434 @c TeX-master: "guile.texi"
 435 @c End: