diff options
Diffstat (limited to 'doc/ref/scheme-options.texi')
-rw-r--r-- | doc/ref/scheme-options.texi | 688 |
1 files changed, 366 insertions, 322 deletions
diff --git a/doc/ref/scheme-options.texi b/doc/ref/scheme-options.texi index 63b7a2c57..0492ce9ed 100644 --- a/doc/ref/scheme-options.texi +++ b/doc/ref/scheme-options.texi @@ -1,10 +1,330 @@ @page @node Options and Config -@chapter Runtime Options and Configuration +@chapter Configuration, Features and Runtime Options -Guile's behaviour can be modified by setting options. For example, is -the language that Guile accepts case sensitive, or should the debugger -automatically show a backtrace on error? +Why is my Guile different from your Guile? There are three kinds of +possible variation: + +@itemize @bullet +@item +build differences --- different versions of the Guile source code, +installation directories, configuration flags that control pieces of +functionality being included or left out, etc. + +@item +differences in dynamically loaded code --- behaviour and features +provided by modules that can be dynamically loaded into a running Guile + +@item +different runtime options --- some of the options that are provided for +controlling Guile's behaviour may be set differently. +@end itemize + +Guile provides ``introspective'' variables and procedures to query all +of these possible variations at runtime. For runtime options, it also +provides procedures to change the settings of options and to obtain +documentation on what the options mean. + +@menu +* Build Config:: Build and installation configuration. +* Feature Tracking:: Available features in the Guile process. +* Runtime Options:: Controlling Guile's runtime behaviour. +@end menu + + +@node Build Config +@section Configuration, Build and Installation + +The following procedures and variables provide information about how +Guile was configured, built and installed on your system. + +@deffn {Scheme Procedure} version +@deffnx {Scheme Procedure} major-version +@deffnx {Scheme Procedure} minor-version +@deffnx {Scheme Procedure} micro-version +@deffnx {C Function} scm_version () +@deffnx {C Function} scm_major_version () +@deffnx {C Function} scm_minor_version () +@deffnx {C Function} scm_micro_version () +Return a string describing Guile's version number, or its major, minor +or micro version number, respectively. + +@lisp +(version) @result{} "1.6.0" +(major-version) @result{} "1" +(minor-version) @result{} "6" +(micro-version) @result{} "0" +@end lisp +@end deffn + +@deffn {Scheme Procedure} %package-data-dir +@deffnx {C Function} scm_sys_package_data_dir () +Return the name of the directory under which Guile Scheme files in +general are stored. On Unix-like systems, this is usually +@file{/usr/local/share/guile} or @file{/usr/share/guile}. +@end deffn + +@deffn {Scheme Procedure} %library-dir +@deffnx {C Function} scm_sys_library_dir () +Return the name of the directory where the Guile Scheme files that +belong to the core Guile installation (as opposed to files from a 3rd +party package) are installed. On Unix-like systems, this is usually +@file{/usr/local/share/guile/<VERSION>} or +@file{/usr/share/guile/<VERSION>}, for example: +@file{/usr/local/share/guile/1.6.0}. +@end deffn + +@deffn {Scheme Procedure} %site-dir +@deffnx {C Function} scm_sys_site_dir () +Return the name of the directory where Guile Scheme files specific to +your site should be installed. On Unix-like systems, this is usually +@file{/usr/local/share/guile/site} or @file{/usr/share/guile/site}. +@end deffn + +@cindex GUILE_LOAD_PATH +@defvar %load-path +List of directories which should be searched for Scheme modules and +libraries. @code{%load-path} is initialized when Guile starts up to +@code{(list (%site-dir) (%library-dir) (%package-data-dir) ".")}, +prepended with the contents of the GUILE_LOAD_PATH environment variable, +if it is set. +@end defvar + +@deffn {Scheme Procedure} parse-path path [tail] +@deffnx {C Function} scm_parse_path (path, tail) +Parse @var{path}, which is expected to be a colon-separated +string, into a list and return the resulting list with +@var{tail} appended. If @var{path} is @code{#f}, @var{tail} +is returned. +@end deffn + +@deffn {Scheme Procedure} search-path path filename [extensions] +@deffnx {C Function} scm_search_path (path, filename, extensions) +Search @var{path} for a directory containing a file named +@var{filename}. The file must be readable, and not a directory. +If we find one, return its full filename; otherwise, return +@code{#f}. If @var{filename} is absolute, return it unchanged. +If given, @var{extensions} is a list of strings; for each +directory in @var{path}, we search for @var{filename} +concatenated with each @var{extension}. +@end deffn + +@defvar %guile-build-info +Alist of information collected during the building of a particular +Guile. Entries can be grouped into one of several categories: +directories, env vars, and versioning info. + +Briefly, here are the keys in @code{%guile-build-info}, by group: + +@table @asis +@item directories +srcdir, top_srcdir, prefix, exec_prefix, bindir, sbindir, libexecdir, +datadir, sysconfdir, sharedstatedir, localstatedir, libdir, infodir, +mandir, includedir, pkgdatadir, pkglibdir, pkgincludedir +@item env vars +LIBS +@item versioning info +guileversion, libguileinterface, buildstamp +@end table + +Values are all strings. The value for @code{LIBS} is typically found +also as a part of "guile-config link" output. The value for +@code{guileversion} has form X.Y.Z, and should be the same as returned +by @code{(version)}. The value for @code{libguileinterface} is libtool +compatible and has form CURRENT:REVISION:AGE. The value for +@code{buildstamp} is the output of the date(1) command. + +In the source, @code{%guile-build-info} is initialized from +libguile/libpath.h, which is completely generated, so deleting this file +before a build guarantees up-to-date values for that build. +@end defvar + + +@node Feature Tracking +@section Feature Tracking + +Guile has a Scheme level variable @code{*features*} that keeps track to +some extent of the features that are available in a running Guile. +@code{*features*} is a list of symbols, for example @code{threads}, each +of which describes a feature of the running Guile process. + +@defvar *features* +A list of symbols describing available features of the Guile process. +@end defvar + +You shouldn't modify the @code{*features*} variable directly using +@code{set!}. Instead, see the procedures that are provided for this +purpose in the following subsection. + +@menu +* Feature Manipulation:: Checking for and advertising features. +* Common Feature Symbols:: Commonly available features. +@end menu + + +@node Feature Manipulation +@subsection Feature Manipulation + +To check whether a particular feature is available, use the +@code{provided?} procedure: + +@deffn {Scheme Procedure} provided? feature +@deffnx {Deprecated Scheme Procedure} feature? feature +Return @code{#t} if the specified @var{feature} is available, otherwise +@code{#f}. +@end deffn + +To advertise a feature from your own Scheme code, you can use the +@code{provide} procedure: + +@deffn {Scheme Procedure} provide feature +Add @var{feature} to the list of available features in this Guile +process. +@end deffn + +For C code, the equivalent function takes its feature name as a +@code{char *} argument for convenience: + +@deftypefn {C Function} void scm_add_feature (const char *str) +Add a symbol with name @var{str} to the list of available features in +this Guile process. +@end deftypefn + + +@node Common Feature Symbols +@subsection Common Feature Symbols + +In general, a particular feature may be available for one of two +reasons. Either because the Guile library was configured and compiled +with that feature enabled --- i.e. the feature is built into the library +on your system. Or because some C or Scheme code that was dynamically +loaded by Guile has added that feature to the list. + +In the first category, here are the features that the current version of +Guile may define (depending on how it is built), and what they mean. + +@table @code +@item array +Indicates support for arrays (@pxref{Arrays}). + +@item array-for-each +Indicates availability of @code{array-for-each} and other array mapping +procedures (@pxref{Array Mapping}). + +@item char-ready? +Indicates that the @code{char-ready?} function is available +(@pxref{Reading}). + +@item complex +Indicates support for complex numbers. + +@item current-time +Indicates availability of time-related functions: @code{times}, +@code{get-internal-run-time} and so on (@pxref{Time}). + +@item debug-extensions +Indicates that the debugging evaluator is available, together with the +options for controlling it. + +@item delay +Indicates support for promises (@pxref{Delayed Evaluation}). + +@item EIDs +Indicates that the @code{geteuid} and @code{getegid} really return +effective user and group IDs (@pxref{Processes}). + +@item inexact +Indicates support for inexact numbers. + +@item i/o-extensions +Indicates availability of the following extended I/O procedures: +@code{ftell}, @code{redirect-port}, @code{dup->fdes}, @code{dup2}, +@code{fileno}, @code{isatty?}, @code{fdopen}, +@code{primitive-move->fdes} and @code{fdes->ports} (@pxref{Ports and +File Descriptors}). + +@item net-db +Indicates availability of network database functions: +@code{scm_gethost}, @code{scm_getnet}, @code{scm_getproto}, +@code{scm_getserv}, @code{scm_sethost}, @code{scm_setnet}, @code{scm_setproto}, +@code{scm_setserv}, and their `byXXX' variants (@pxref{Network +Databases}). + +@item posix +Indicates support for POSIX functions: @code{pipe}, @code{getgroups}, +@code{kill}, @code{execl} and so on (@pxref{POSIX}). + +@item random +Indicates availability of random number generation functions: +@code{random}, @code{copy-random-state}, @code{random-uniform} and so on +(@pxref{Random}). + +@item reckless +Indicates that Guile was built with important checks omitted --- you +should never see this! + +@item regex +Indicates support for POSIX regular expressions using +@code{make-regexp}, @code{regexp-exec} and friends (@pxref{Regexp +Functions}). + +@item socket +Indicates availability of socket-related functions: @code{socket}, +@code{bind}, @code{connect} and so on (@pxref{Network Sockets and +Communication}). + +@item sort +Indicates availability of sorting and merging functions +(@pxref{Sorting}). + +@item system +Indicates that the @code{system} function is available +(@pxref{Processes}). + +@item threads +Indicates support for multithreading (@pxref{Threads}). + +@item values +Indicates support for multiple return values using @code{values} and +@code{call-with-values} (@pxref{Multiple Values}). +@end table + +Available features in the second category depend, by definition, on what +additional code your Guile process has loaded in. The following table +lists features that you might encounter for this reason. + +@table @code +@item defmacro +Indicates that the @code{defmacro} macro is available (@pxref{Macros}). + +@item describe +Indicates that the @code{(oop goops describe)} module has been loaded, +which provides a procedure for describing the contents of GOOPS +instances. + +@item readline +Indicates that Guile has loaded in Readline support, for command line +editing (@pxref{Readline Support}). + +@item record +Indicates support for record definition using @code{make-record-type} +and friends (@pxref{Records}). +@end table + +Although these tables may seem exhaustive, it is probably unwise in +practice to rely on them, as the correspondences between feature symbols +and available procedures/behaviour are not strictly defined. If you are +writing code that needs to check for the existence of some procedure, it +is probably safer to do so directly using the @code{defined?} procedure +than to test for the corresponding feature using @code{feature?}. + + +@node Runtime Options +@section Runtime Options + +Guile's runtime behaviour can be modified by setting options. For +example, is the language that Guile accepts case sensitive, or should +the debugger automatically show a backtrace on error? Guile has two levels of interface for managing options: a low-level control interface, and a user-level interface which allows the enabling @@ -15,43 +335,52 @@ configure @emph{reading}, @emph{printing}, @emph{debugging} or @emph{evaluating}. @menu -* General option interface:: +* Low level options interfaces:: +* User level options interfaces:: * Reader options:: * Printing options:: * Debugger options:: * Evaluator options:: * Evaluator trap options:: * Examples of option use:: -* Install Config:: Installation and configuration data. -* Feature Tracking:: Available features in the Guile process. @end menu -@node General option interface -@section General option interface -We will use the expression @code{<group>} to represent @code{read}, -@code{print}, @code{debug} or @code{evaluator}. - -@subheading Low level - -@c NJFIXME -@deffn {Scheme Procedure} <group>-options-interface -@deffnx {Scheme Procedure} read-options-interface [SOME-INT] -@deffnx {Scheme Procedure} print-options-interface [SOME-INT] -@deffnx {Scheme Procedure} evaluator-traps-interface [SOME-INT] -@deffnx {Scheme Procedure} read-options-interface [SOME-INT] -[FIXME: I have just taken the comments for C routine scm_options that -implements all of these. It needs to be presented better.] - -If scm_options is called without arguments, the current option setting -is returned. If the argument is an option setting, options are altered -and the old setting is returned. If the argument isn't a list, a list -of sublists is returned, where each sublist contains option name, value -and documentation string. +@node Low level options interfaces +@subsection Low Level Options Interfaces + +@deffn {Scheme Procedure} read-options-interface [setting] +@deffnx {Scheme Procedure} eval-options-interface [setting] +@deffnx {Scheme Procedure} print-options-interface [setting] +@deffnx {Scheme Procedure} debug-options-interface [setting] +@deffnx {Scheme Procedure} evaluator-traps-interface [setting] +@deffnx {C Function} scm_read_options (setting) +@deffnx {C Function} scm_eval_options_interface (setting) +@deffnx {C Function} scm_print_options (setting) +@deffnx {C Function} scm_debug_options (setting) +@deffnx {C Function} scm_evaluator_traps (setting) +If one of these procedures is called with no arguments (or with +@code{setting == SCM_UNDEFINED} in C code), it returns a list describing +the current setting of the read, eval, print, debug or evaluator traps +options respectively. The setting of a boolean option is indicated +simply by the presence or absence of the option symbol in the list. The +setting of a non-boolean option is indicated by the presence of the +option symbol immediately followed by the option's current value. + +If called with a list argument, these procedures interpret the list as +an option setting and modify the relevant options accordingly. [FIXME +--- this glosses over a lot of details!] + +If called with any other argument, such as @code{'help}, these +procedures return a list of entries like @code{(@var{OPTION-SYMBOL} +@var{DEFAULT-VALUE} @var{DOC-STRING})}, with each entry giving the +default value and documentation for each option symbol in the relevant +set of options. @end deffn -@subheading User level +@node User level options interfaces +@subsection User Level Options Interfaces @c @deftp {Data type} scm_option @c @code{scm_option} is used to represent run time options. It can be a @@ -115,7 +444,7 @@ These functions set a non-boolean @var{option-symbol} to the specified @node Reader options -@section Reader options +@subsection Reader options @cindex options - read @cindex read options @@ -141,7 +470,7 @@ To make Guile case insensitive, you can type @end smalllisp @node Printing options -@section Printing options +@subsection Printing options Here is the list of print options generated by typing @code{(print-options 'full)} in Guile. You can also see the default @@ -154,7 +483,7 @@ closure-hook #f Hook for printing closures. @node Evaluator options -@section Evaluator options +@subsection Evaluator options These are the evaluator options with their default values, as they are printed by typing @code{(eval-options 'full)} in Guile. @@ -163,8 +492,9 @@ printed by typing @code{(eval-options 'full)} in Guile. stack 22000 Size of thread stacks (in machine words). @end smallexample + @node Evaluator trap options -@section Evaluator trap options +@subsection Evaluator trap options [FIXME: These flags, together with their corresponding handlers, are not user level options. Probably this entire section should be moved to the documentation about the low-level programmer debugging interface.] @@ -230,7 +560,7 @@ debug object, otherwise it is a restartable continuation. @end deffn @node Debugger options -@section Debugger options +@subsection Debugger options Here is the list of print options generated by typing @code{(debug-options 'full)} in Guile. You can also see the default @@ -251,7 +581,7 @@ breakpoints no *Check for breakpoints. cheap yes *Flyweight representation of the stack at traps. @end smallexample -@subsection Stack overflow +@subsubsection Stack overflow @cindex overflow, stack @cindex stack overflow @@ -287,7 +617,7 @@ recursion,,,r5rs,The Revised^5 Report on Scheme}. @node Examples of option use -@section Examples of option use +@subsection Examples of option use Here is an example of a session in which some read and debug option handling procedures are used. In this example, the user @@ -360,292 +690,6 @@ guile> @end smalllisp -@node Install Config -@section Installation and Configuration Data - -It is often useful to have site-specific information about the current -Guile installation. This chapter describes how to find out about -Guile's configuration at run time. - -@deffn {Scheme Procedure} version -@deffnx {Scheme Procedure} major-version -@deffnx {Scheme Procedure} minor-version -@deffnx {Scheme Procedure} micro-version -@deffnx {C Function} scm_version () -@deffnx {C Function} scm_major_version () -@deffnx {C Function} scm_minor_version () -@deffnx {C Function} scm_micro_version () -Return a string describing Guile's version number, or its major, minor -or micro version number, respectively. - -@lisp -(version) @result{} "1.6.0" -(major-version) @result{} "1" -(minor-version) @result{} "6" -(micro-version) @result{} "0" -@end lisp -@end deffn - -@c NJFIXME not in libguile! -@deffn {Scheme Procedure} libguile-config-stamp -Return a string describing the date on which @code{libguile} was -configured. This is used to determine whether the Guile core -interpreter and the ice-9 runtime have grown out of date with one -another. -@end deffn - -@deffn {Scheme Procedure} %package-data-dir -@deffnx {C Function} scm_sys_package_data_dir () -Return the name of the directory where Scheme packages, modules and -libraries are kept. On most Unix systems, this will be -@samp{/usr/local/share/guile}. -@end deffn - -@deffn {Scheme Procedure} %library-dir -@deffnx {C Function} scm_sys_library_dir () -Return the directory where the Guile Scheme library files are installed. -E.g., may return "/usr/share/guile/1.3.5". -@end deffn - -@deffn {Scheme Procedure} %site-dir -@deffnx {C Function} scm_sys_site_dir () -Return the directory where the Guile site files are installed. -E.g., may return "/usr/share/guile/site". -@end deffn - -@deffn {Scheme Procedure} parse-path path [tail] -@deffnx {C Function} scm_parse_path (path, tail) -Parse @var{path}, which is expected to be a colon-separated -string, into a list and return the resulting list with -@var{tail} appended. If @var{path} is @code{#f}, @var{tail} -is returned. -@end deffn - -@deffn {Scheme Procedure} search-path path filename [extensions] -@deffnx {C Function} scm_search_path (path, filename, extensions) -Search @var{path} for a directory containing a file named -@var{filename}. The file must be readable, and not a directory. -If we find one, return its full filename; otherwise, return -@code{#f}. If @var{filename} is absolute, return it unchanged. -If given, @var{extensions} is a list of strings; for each -directory in @var{path}, we search for @var{filename} -concatenated with each @var{extension}. -@end deffn - -@defvar %load-path -List of directories which should be searched for Scheme -modules and libraries. -@end defvar - -@defvar %guile-build-info -Alist of information collected during the building of a particular -@code{guile} program. Entries can be grouped into one of several -categories: directories, env vars, and versioning info. - -Briefly, here are the keys in @code{%guile-build-info}, by group: -@itemize @bullet -@item directories -srcdir, top_srcdir, prefix, exec_prefix, bindir, sbindir, libexecdir, -datadir, sysconfdir, sharedstatedir, localstatedir, libdir, infodir, -mandir, includedir, pkgdatadir, pkglibdir, pkgincludedir -@item env vars -LIBS -@item versioning info -guileversion, libguileinterface, buildstamp -@end itemize - -Values are all strings. The value for @code{LIBS} is typically found also as -a part of "guile-config link" output. The value for @code{guileversion} has -form X.Y.Z, and should be the same as returned by @code{version}. The value -for @code{libguileinterface} is libtool compatible and has form -CURRENT:REVISION:AGE. The value for @code{buildstamp} is the output of the -date(1) command. - -In the source, @code{%guile-build-info} is initialized from -libguile/libpath.h, which is completely generated, so deleting this file -before a build guarantees up-to-date values for that build. -@end defvar - - -@node Feature Tracking -@section Feature Tracking - -Guile has a Scheme level variable @code{*features*} that keeps track to -some extent of the features that are available in a running Guile. -@code{*features*} is a list of symbols, for example @code{threads}, each -of which describes a feature of the running Guile process. - -@defvar *features* -A list of symbols describing available features of the Guile process. -@end defvar - -You shouldn't modify the @code{*features*} variable directly using -@code{set!}. Instead, see the procedures that are provided for this -purpose in the following subsection. - -@menu -* Feature Manipulation:: Checking for and advertising features. -* Common Feature Symbols:: Commonly available features. -@end menu - - -@node Feature Manipulation -@subsection Feature Manipulation - -To check whether a particular feature is available, use the -@code{provided?} procedure: - -@deffn {Scheme Procedure} provided? feature -@deffnx {Deprecated Scheme Procedure} feature? feature -Return @code{#t} if the specified @var{feature} is available, otherwise -@code{#f}. -@end deffn - -To advertise a feature from your own Scheme code, you can use the -@code{provide} procedure: - -@deffn {Scheme Procedure} provide feature -Add @var{feature} to the list of available features in this Guile -process. -@end deffn - -For C code, the equivalent function takes its feature name as a -@code{char *} argument for convenience: - -@deftypefn {C Function} void scm_add_feature (const char *str) -Add a symbol with name @var{str} to the list of available features in -this Guile process. -@end deftypefn - - -@node Common Feature Symbols -@subsection Common Feature Symbols - -In general, a particular feature may be available for one of two -reasons. Either because the Guile library was configured and compiled -with that feature enabled --- i.e. the feature is built into the library -on your system. Or because some C or Scheme code that was dynamically -loaded by Guile has added that feature to the list. - -In the first category, here are the features that the current version of -Guile may define (depending on how it is built), and what they mean. - -@table @code -@item array -Indicates support for arrays (@pxref{Arrays}). - -@item array-for-each -Indicates availability of @code{array-for-each} and other array mapping -procedures (@pxref{Array Mapping}). - -@item char-ready? -Indicates that the @code{char-ready?} function is available -(@pxref{Reading}). - -@item complex -Indicates support for complex numbers. - -@item current-time -Indicates availability of time-related functions: @code{times}, -@code{get-internal-run-time} and so on (@pxref{Time}). - -@item debug-extensions -Indicates that the debugging evaluator is available, together with the -options for controlling it. - -@item delay -Indicates support for promises (@pxref{Delayed Evaluation}). - -@item EIDs -Indicates that the @code{geteuid} and @code{getegid} really return -effective user and group IDs (@pxref{Processes}). - -@item inexact -Indicates support for inexact numbers. - -@item i/o-extensions -Indicates availability of the following extended I/O procedures: -@code{ftell}, @code{redirect-port}, @code{dup->fdes}, @code{dup2}, -@code{fileno}, @code{isatty?}, @code{fdopen}, -@code{primitive-move->fdes} and @code{fdes->ports} (@pxref{Ports and -File Descriptors}). - -@item net-db -Indicates availability of network database functions: -@code{scm_gethost}, @code{scm_getnet}, @code{scm_getproto}, -@code{scm_getserv}, @code{scm_sethost}, @code{scm_setnet}, @code{scm_setproto}, -@code{scm_setserv}, and their `byXXX' variants (@pxref{Network -Databases}). - -@item posix -Indicates support for POSIX functions: @code{pipe}, @code{getgroups}, -@code{kill}, @code{execl} and so on (@pxref{POSIX}). - -@item random -Indicates availability of random number generation functions: -@code{random}, @code{copy-random-state}, @code{random-uniform} and so on -(@pxref{Random}). - -@item reckless -Indicates that Guile was built with important checks omitted --- you -should never see this! - -@item regex -Indicates support for POSIX regular expressions using -@code{make-regexp}, @code{regexp-exec} and friends (@pxref{Regexp -Functions}). - -@item socket -Indicates availability of socket-related functions: @code{socket}, -@code{bind}, @code{connect} and so on (@pxref{Network Sockets and -Communication}). - -@item sort -Indicates availability of sorting and merging functions -(@pxref{Sorting}). - -@item system -Indicates that the @code{system} function is available -(@pxref{Processes}). - -@item threads -Indicates support for multithreading (@pxref{Threads}). - -@item values -Indicates support for multiple return values using @code{values} and -@code{call-with-values} (@pxref{Multiple Values}). -@end table - -Available features in the second category depend, by definition, on what -additional code your Guile process has loaded in. The following table -lists features that you might encounter for this reason. - -@table @code -@item defmacro -Indicates that the @code{defmacro} macro is available (@pxref{Macros}). - -@item describe -Indicates that the @code{(oop goops describe)} module has been loaded, -which provides a procedure for describing the contents of GOOPS -instances. - -@item readline -Indicates that Guile has loaded in Readline support, for command line -editing (@pxref{Readline Support}). - -@item record -Indicates support for record definition using @code{make-record-type} -and friends (@pxref{Records}). -@end table - -Although these tables may seem exhaustive, it is probably unwise in -practice to rely on them, as the correspondences between feature symbols -and available procedures/behaviour are not strictly defined. If you are -writing code that needs to check for the existence of some procedure, it -is probably safer to do so directly using the @code{defined?} procedure -than to test for the corresponding feature using @code{feature?}. - - @c Local Variables: @c TeX-master: "guile.texi" @c End: |