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/@var{GUILE_EFFECTIVE_VERSION}} or
  86 @file{/usr/share/guile/@var{GUILE_EFFECTIVE_VERSION}};
  87
  88 @noindent
  89 for example @file{/usr/local/share/guile/1.6}.
  90 @end deffn
  91
  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}.
  97 @end deffn
  98
  99 @cindex @env{GUILE_LOAD_PATH}
 100 @defvar %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 @env{GUILE_LOAD_PATH} environment variable,
 105 if it is set.
 106 @end defvar
 107
 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}
 113 is returned.
 114 @end deffn
 115
 116 @deffn {Scheme Procedure} search-path path filename [extensions [require-exts?]]
 117 @deffnx {C Function} scm_search_path (path, filename, rest)
 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}.  If @var{require-exts?}
 125 is true, require that the returned file name have one of the
 126 given extensions; if @var{require-exts?} is not given, it
 127 defaults to @code{#f}.
 128
 129 For compatibility with Guile 1.8 and earlier, the C function takes only
 130 three arguments
 131 @end deffn
 132
 133 @defvar %guile-build-info
 134 Alist of information collected during the building of a particular
 135 Guile.  Entries can be grouped into one of several categories:
 136 directories, env vars, and versioning info.
 137
 138 Briefly, here are the keys in @code{%guile-build-info}, by group:
 139
 140 @cindex @code{srcdir}
 141 @cindex @code{top_srcdir}
 142 @cindex @code{prefix}
 143 @cindex @code{exec_prefix}
 144 @cindex @code{bindir}
 145 @cindex @code{sbindir}
 146 @cindex @code{libexecdir}
 147 @cindex @code{datadir}
 148 @cindex @code{sysconfdir}
 149 @cindex @code{sharedstatedir}
 150 @cindex @code{localstatedir}
 151 @cindex @code{libdir}
 152 @cindex @code{infodir}
 153 @cindex @code{mandir}
 154 @cindex @code{includedir}
 155 @cindex @code{pkgdatadir}
 156 @cindex @code{pkglibdir}
 157 @cindex @code{pkgincludedir}
 158 @table @asis
 159 @item   directories
 160 srcdir, top_srcdir, prefix, exec_prefix, bindir, sbindir, libexecdir,
 161 datadir, sysconfdir, sharedstatedir, localstatedir, libdir, infodir,
 162 mandir, includedir, pkgdatadir, pkglibdir, pkgincludedir
 163 @cindex @code{LIBS}
 164 @item   env vars
 165 LIBS
 166 @cindex @code{guileversion}
 167 @cindex @code{libguileinterface}
 168 @cindex @code{buildstamp}
 169 @item   versioning info
 170 guileversion, libguileinterface, buildstamp
 171 @end table
 172
 173 Values are all strings.  The value for @code{LIBS} is typically found
 174 also as a part of "guile-config link" output.  The value for
 175 @code{guileversion} has form X.Y.Z, and should be the same as returned
 176 by @code{(version)}.  The value for @code{libguileinterface} is
 177 libtool compatible and has form CURRENT:REVISION:AGE
 178 (@pxref{Versioning,, Library interface versions, libtool, GNU
 179 Libtool}).  The value for @code{buildstamp} is the output of the
 180 command @samp{date -u +'%Y-%m-%d %T'} (UTC).
 181
 182 In the source, @code{%guile-build-info} is initialized from
 183 libguile/libpath.h, which is completely generated, so deleting this file
 184 before a build guarantees up-to-date values for that build.
 185 @end defvar
 186
 187 @cindex GNU triplet
 188 @cindex canonical host type
 189
 190 @defvar %host-type
 191 The canonical host type (GNU triplet) of the host Guile was configured
 192 for, e.g., @code{"x86_64-unknown-linux-gnu"} (@pxref{Canonicalizing,,,
 193 autoconf, The GNU Autoconf Manual}).
 194 @end defvar
 195
 196 @node Feature Tracking
 197 @subsection Feature Tracking
 198
 199 Guile has a Scheme level variable @code{*features*} that keeps track to
 200 some extent of the features that are available in a running Guile.
 201 @code{*features*} is a list of symbols, for example @code{threads}, each
 202 of which describes a feature of the running Guile process.
 203
 204 @defvar *features*
 205 A list of symbols describing available features of the Guile process.
 206 @end defvar
 207
 208 You shouldn't modify the @code{*features*} variable directly using
 209 @code{set!}.  Instead, see the procedures that are provided for this
 210 purpose in the following subsection.
 211
 212 @menu
 213 * Feature Manipulation::        Checking for and advertising features.
 214 * Common Feature Symbols::      Commonly available features.
 215 @end menu
 216
 217
 218 @node Feature Manipulation
 219 @subsubsection Feature Manipulation
 220
 221 To check whether a particular feature is available, use the
 222 @code{provided?} procedure:
 223
 224 @deffn {Scheme Procedure} provided? feature
 225 @deffnx {Deprecated Scheme Procedure} feature? feature
 226 Return @code{#t} if the specified @var{feature} is available, otherwise
 227 @code{#f}.
 228 @end deffn
 229
 230 To advertise a feature from your own Scheme code, you can use the
 231 @code{provide} procedure:
 232
 233 @deffn {Scheme Procedure} provide feature
 234 Add @var{feature} to the list of available features in this Guile
 235 process.
 236 @end deffn
 237
 238 For C code, the equivalent function takes its feature name as a
 239 @code{char *} argument for convenience:
 240
 241 @deftypefn {C Function} void scm_add_feature (const char *str)
 242 Add a symbol with name @var{str} to the list of available features in
 243 this Guile process.
 244 @end deftypefn
 245
 246
 247 @node Common Feature Symbols
 248 @subsubsection Common Feature Symbols
 249
 250 In general, a particular feature may be available for one of two
 251 reasons.  Either because the Guile library was configured and compiled
 252 with that feature enabled --- i.e. the feature is built into the library
 253 on your system.  Or because some C or Scheme code that was dynamically
 254 loaded by Guile has added that feature to the list.
 255
 256 In the first category, here are the features that the current version of
 257 Guile may define (depending on how it is built), and what they mean.
 258
 259 @table @code
 260 @item array
 261 Indicates support for arrays (@pxref{Arrays}).
 262
 263 @item array-for-each
 264 Indicates availability of @code{array-for-each} and other array mapping
 265 procedures (@pxref{Arrays}).
 266
 267 @item char-ready?
 268 Indicates that the @code{char-ready?} function is available
 269 (@pxref{Reading}).
 270
 271 @item complex
 272 Indicates support for complex numbers.
 273
 274 @item current-time
 275 Indicates availability of time-related functions: @code{times},
 276 @code{get-internal-run-time} and so on (@pxref{Time}).
 277
 278 @item debug-extensions
 279 Indicates that the debugging evaluator is available, together with the
 280 options for controlling it.
 281
 282 @item delay
 283 Indicates support for promises (@pxref{Delayed Evaluation}).
 284
 285 @item EIDs
 286 Indicates that the @code{geteuid} and @code{getegid} really return
 287 effective user and group IDs (@pxref{Processes}).
 288
 289 @item inexact
 290 Indicates support for inexact numbers.
 291
 292 @item i/o-extensions
 293 Indicates availability of the following extended I/O procedures:
 294 @code{ftell}, @code{redirect-port}, @code{dup->fdes}, @code{dup2},
 295 @code{fileno}, @code{isatty?}, @code{fdopen},
 296 @code{primitive-move->fdes} and @code{fdes->ports} (@pxref{Ports and
 297 File Descriptors}).
 298
 299 @item net-db
 300 Indicates availability of network database functions:
 301 @code{scm_gethost}, @code{scm_getnet}, @code{scm_getproto},
 302 @code{scm_getserv}, @code{scm_sethost}, @code{scm_setnet}, @code{scm_setproto},
 303 @code{scm_setserv}, and their `byXXX' variants (@pxref{Network
 304 Databases}).
 305
 306 @item posix
 307 Indicates support for POSIX functions: @code{pipe}, @code{getgroups},
 308 @code{kill}, @code{execl} and so on (@pxref{POSIX}).
 309
 310 @item random
 311 Indicates availability of random number generation functions:
 312 @code{random}, @code{copy-random-state}, @code{random-uniform} and so on
 313 (@pxref{Random}).
 314
 315 @item reckless
 316 Indicates that Guile was built with important checks omitted --- you
 317 should never see this!
 318
 319 @item regex
 320 Indicates support for POSIX regular expressions using
 321 @code{make-regexp}, @code{regexp-exec} and friends (@pxref{Regexp
 322 Functions}).
 323
 324 @item socket
 325 Indicates availability of socket-related functions: @code{socket},
 326 @code{bind}, @code{connect} and so on (@pxref{Network Sockets and
 327 Communication}).
 328
 329 @item sort
 330 Indicates availability of sorting and merging functions
 331 (@pxref{Sorting}).
 332
 333 @item system
 334 Indicates that the @code{system} function is available
 335 (@pxref{Processes}).
 336
 337 @item threads
 338 Indicates support for multithreading (@pxref{Threads}).
 339
 340 @item values
 341 Indicates support for multiple return values using @code{values} and
 342 @code{call-with-values} (@pxref{Multiple Values}).
 343 @end table
 344
 345 Available features in the second category depend, by definition, on what
 346 additional code your Guile process has loaded in.  The following table
 347 lists features that you might encounter for this reason.
 348
 349 @table @code
 350 @item defmacro
 351 Indicates that the @code{defmacro} macro is available (@pxref{Macros}).
 352
 353 @item describe
 354 Indicates that the @code{(oop goops describe)} module has been loaded,
 355 which provides a procedure for describing the contents of GOOPS
 356 instances.
 357
 358 @item readline
 359 Indicates that Guile has loaded in Readline support, for command line
 360 editing (@pxref{Readline Support}).
 361
 362 @item record
 363 Indicates support for record definition using @code{make-record-type}
 364 and friends (@pxref{Records}).
 365 @end table
 366
 367 Although these tables may seem exhaustive, it is probably unwise in
 368 practice to rely on them, as the correspondences between feature symbols
 369 and available procedures/behaviour are not strictly defined.  If you are
 370 writing code that needs to check for the existence of some procedure, it
 371 is probably safer to do so directly using the @code{defined?} procedure
 372 than to test for the corresponding feature using @code{provided?}.
 373
 374
 375 @node Runtime Options
 376 @subsection Runtime Options
 377
 378 There are a number of runtime options available for paramaterizing
 379 built-in procedures, like @code{read}, and built-in behavior, like what
 380 happens on an uncaught error.
 381
 382 For more information on reader options, @xref{Scheme Read}.
 383
 384 For more information on print options, @xref{Scheme Write}.
 385
 386 Finally, for more information on debugger options, @xref{Debug
 387 Options}.
 388
 389 @subsubsection Examples of option use
 390
 391 Here is an example of a session in which some read and debug option
 392 handling procedures are used.  In this example, the user
 393
 394 @enumerate
 395 @item
 396 Notices that the symbols @code{abc} and @code{aBc} are not the same
 397 @item
 398 Examines the @code{read-options}, and sees that @code{case-insensitive}
 399 is set to ``no''.
 400 @item
 401 Enables @code{case-insensitive}
 402 @item
 403 Quits the recursive prompt
 404 @item
 405 Verifies that now @code{aBc} and @code{abc} are the same
 406 @end enumerate
 407
 408 @smalllisp
 409 scheme@@(guile-user)> (define abc "hello")
 410 scheme@@(guile-user)> abc
 411 $1 = "hello"
 412 scheme@@(guile-user)> aBc
 413 <unknown-location>: warning: possibly unbound variable `aBc'
 414 ERROR: In procedure module-lookup:
 415 ERROR: Unbound variable: aBc
 416 Entering a new prompt.  Type `,bt' for a backtrace or `,q' to continue.
 417 scheme@@(guile-user) [1]> (read-options 'help)
 418 copy              no    Copy source code expressions.
 419 positions         yes   Record positions of source code expressions.
 420 case-insensitive  no    Convert symbols to lower case.
 421 keywords          #f    Style of keyword recognition: #f, 'prefix or 'postfix.
 422 r6rs-hex-escapes  no    Use R6RS variable-length character and string hex escapes.
 423 square-brackets   yes   Treat `[' and `]' as parentheses, for R6RS compatibility.
 424 hungry-eol-escapes no   In strings, consume leading whitespace after an
 425                         escaped end-of-line.
 426 scheme@@(guile-user) [1]> (read-enable 'case-insensitive)
 427 $2 = (square-brackets keywords #f case-insensitive positions)
 428 scheme@@(guile-user) [1]> ,q
 429 scheme@@(guile-user)> aBc
 430 $3 = "hello"
 431 @end smalllisp
 432
 433
 434 @c Local Variables:
 435 @c TeX-master: "guile.texi"
 436 @c End: