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,
   4 @c   2008, 2009, 2010, 2011, 2012, 2013
   5 @c   Free Software Foundation, Inc.
   6 @c See the file guile.texi for copying conditions.
   7
   8 @node Options and Config
   9 @section Configuration, Features and Runtime Options
  10
  11 Why is my Guile different from your Guile?  There are three kinds of
  12 possible variation:
  13
  14 @itemize @bullet
  15 @item
  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.
  19
  20 @item
  21 differences in dynamically loaded code --- behaviour and features
  22 provided by modules that can be dynamically loaded into a running Guile
  23
  24 @item
  25 different runtime options --- some of the options that are provided for
  26 controlling Guile's behaviour may be set differently.
  27 @end itemize
  28
  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.
  33
  34 @menu
  35 * Build Config::                Build and installation configuration.
  36 * Feature Tracking::            Available features in the Guile process.
  37 * Runtime Options::             Controlling Guile's runtime behaviour.
  38 @end menu
  39
  40
  41 @node Build Config
  42 @subsection Configuration, Build and Installation
  43
  44 The following procedures and variables provide information about how
  45 Guile was configured, built and installed on your system.
  46
  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.0/}
  64
  65 @lisp
  66 (version) @result{} "2.0.4"
  67 (effective-version) @result{} "2.0"
  68 (major-version) @result{} "2"
  69 (minor-version) @result{} "0"
  70 (micro-version) @result{} "4"
  71 @end lisp
  72 @end deffn
  73
  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}.
  79 @end deffn
  80
  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}};
  88
  89 @noindent
  90 for example @file{/usr/local/share/guile/2.0}.
  91 @end deffn
  92
  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}.
  98 @end deffn
  99
 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}.
 105 @end deffn
 106
 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.
 111
 112 Briefly, here are the keys in @code{%guile-build-info}, by group:
 113
 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}
 132 @table @asis
 133 @item   directories
 134 srcdir, top_srcdir, prefix, exec_prefix, bindir, sbindir, libexecdir,
 135 datadir, sysconfdir, sharedstatedir, localstatedir, libdir, infodir,
 136 mandir, includedir, pkgdatadir, pkglibdir, pkgincludedir
 137 @cindex @code{LIBS}
 138 @item   env vars
 139 LIBS
 140 @cindex @code{guileversion}
 141 @cindex @code{libguileinterface}
 142 @cindex @code{buildstamp}
 143 @item   versioning info
 144 guileversion, libguileinterface, buildstamp
 145 @end table
 146
 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
 155 %T'} (UTC).
 156
 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.
 160 @end defvar
 161
 162 @cindex GNU triplet
 163 @cindex canonical host type
 164
 165 @defvar %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}).
 169 @end defvar
 170
 171 @node Feature Tracking
 172 @subsection Feature Tracking
 173
 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.
 178
 179 @defvar *features*
 180 A list of symbols describing available features of the Guile process.
 181 @end defvar
 182
 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.
 186
 187 @menu
 188 * Feature Manipulation::        Checking for and advertising features.
 189 * Common Feature Symbols::      Commonly available features.
 190 @end menu
 191
 192
 193 @node Feature Manipulation
 194 @subsubsection Feature Manipulation
 195
 196 To check whether a particular feature is available, use the
 197 @code{provided?} procedure:
 198
 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
 202 @code{#f}.
 203 @end deffn
 204
 205 To advertise a feature from your own Scheme code, you can use the
 206 @code{provide} procedure:
 207
 208 @deffn {Scheme Procedure} provide feature
 209 Add @var{feature} to the list of available features in this Guile
 210 process.
 211 @end deffn
 212
 213 For C code, the equivalent function takes its feature name as a
 214 @code{char *} argument for convenience:
 215
 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
 218 this Guile process.
 219 @end deftypefn
 220
 221
 222 @node Common Feature Symbols
 223 @subsubsection Common Feature Symbols
 224
 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.
 230
 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.
 233
 234 @table @code
 235 @item array
 236 Indicates support for arrays (@pxref{Arrays}).
 237
 238 @item array-for-each
 239 Indicates availability of @code{array-for-each} and other array mapping
 240 procedures (@pxref{Arrays}).
 241
 242 @item char-ready?
 243 Indicates that the @code{char-ready?} function is available
 244 (@pxref{Reading}).
 245
 246 @item complex
 247 Indicates support for complex numbers.
 248
 249 @item current-time
 250 Indicates availability of time-related functions: @code{times},
 251 @code{get-internal-run-time} and so on (@pxref{Time}).
 252
 253 @item debug-extensions
 254 Indicates that the debugging evaluator is available, together with the
 255 options for controlling it.
 256
 257 @item delay
 258 Indicates support for promises (@pxref{Delayed Evaluation}).
 259
 260 @item EIDs
 261 Indicates that the @code{geteuid} and @code{getegid} really return
 262 effective user and group IDs (@pxref{Processes}).
 263
 264 @item inexact
 265 Indicates support for inexact numbers.
 266
 267 @item i/o-extensions
 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
 272 File Descriptors}).
 273
 274 @item net-db
 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
 279 Databases}).
 280
 281 @item posix
 282 Indicates support for POSIX functions: @code{pipe}, @code{getgroups},
 283 @code{kill}, @code{execl} and so on (@pxref{POSIX}).
 284
 285 @item fork
 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}).
 289
 290 @item random
 291 Indicates availability of random number generation functions:
 292 @code{random}, @code{copy-random-state}, @code{random-uniform} and so on
 293 (@pxref{Random}).
 294
 295 @item reckless
 296 Indicates that Guile was built with important checks omitted --- you
 297 should never see this!
 298
 299 @item regex
 300 Indicates support for POSIX regular expressions using
 301 @code{make-regexp}, @code{regexp-exec} and friends (@pxref{Regexp
 302 Functions}).
 303
 304 @item socket
 305 Indicates availability of socket-related functions: @code{socket},
 306 @code{bind}, @code{connect} and so on (@pxref{Network Sockets and
 307 Communication}).
 308
 309 @item sort
 310 Indicates availability of sorting and merging functions
 311 (@pxref{Sorting}).
 312
 313 @item system
 314 Indicates that the @code{system} function is available
 315 (@pxref{Processes}).
 316
 317 @item threads
 318 Indicates support for multithreading (@pxref{Threads}).
 319
 320 @item values
 321 Indicates support for multiple return values using @code{values} and
 322 @code{call-with-values} (@pxref{Multiple Values}).
 323 @end table
 324
 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.
 328
 329 @table @code
 330 @item defmacro
 331 Indicates that the @code{defmacro} macro is available (@pxref{Macros}).
 332
 333 @item describe
 334 Indicates that the @code{(oop goops describe)} module has been loaded,
 335 which provides a procedure for describing the contents of GOOPS
 336 instances.
 337
 338 @item readline
 339 Indicates that Guile has loaded in Readline support, for command line
 340 editing (@pxref{Readline Support}).
 341
 342 @item record
 343 Indicates support for record definition using @code{make-record-type}
 344 and friends (@pxref{Records}).
 345 @end table
 346
 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?}.
 353
 354
 355 @node Runtime Options
 356 @subsection Runtime Options
 357
 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.
 361
 362 For more information on reader options, @xref{Scheme Read}.
 363
 364 For more information on print options, @xref{Scheme Write}.
 365
 366 Finally, for more information on debugger options, @xref{Debug
 367 Options}.
 368
 369 @subsubsection Examples of option use
 370
 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
 373
 374 @enumerate
 375 @item
 376 Notices that the symbols @code{abc} and @code{aBc} are not the same
 377 @item
 378 Examines the @code{read-options}, and sees that @code{case-insensitive}
 379 is set to ``no''.
 380 @item
 381 Enables @code{case-insensitive}
 382 @item
 383 Quits the recursive prompt
 384 @item
 385 Verifies that now @code{aBc} and @code{abc} are the same
 386 @end enumerate
 387
 388 @smalllisp
 389 scheme@@(guile-user)> (define abc "hello")
 390 scheme@@(guile-user)> abc
 391 $1 = "hello"
 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
 405                         escaped end-of-line.
 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
 411 $3 = "hello"
 412 @end smalllisp
 413
 414
 415 @c Local Variables:
 416 @c TeX-master: "guile.texi"
 417 @c End: