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