Commit | Line | Data |
---|---|---|
07d83abe MV |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Guile Reference Manual. | |
d7a22073 | 3 | @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2008, 2009 |
07d83abe MV |
4 | @c Free Software Foundation, Inc. |
5 | @c See the file guile.texi for copying conditions. | |
6 | ||
7 | @page | |
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/1.6/} | |
64 | ||
65 | @lisp | |
66 | (version) @result{} "1.6.0" | |
67 | (effective-version) @result{} "1.6" | |
68 | (major-version) @result{} "1" | |
69 | (minor-version) @result{} "6" | |
70 | (micro-version) @result{} "0" | |
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 | |
45867c2a | 85 | party package) are installed. On Unix-like systems this is usually |
07d83abe | 86 | @file{/usr/local/share/guile/<GUILE_EFFECTIVE_VERSION>} or |
45867c2a NJ |
87 | @file{/usr/share/guile/<GUILE_EFFECTIVE_VERSION>}; |
88 | ||
89 | @noindent for example @file{/usr/local/share/guile/1.6}. | |
07d83abe MV |
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 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 | |
8370b00b | 103 | @code{(list (%site-dir) (%library-dir) (%package-data-dir))}, |
07d83abe MV |
104 | prepended with the contents of the 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 | ||
88cbb421 LC |
116 | @deffn {Scheme Procedure} search-path path filename [extensions [require-exts?]] |
117 | @deffnx {C Function} scm_search_path (path, filename, rest) | |
07d83abe MV |
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} | |
88cbb421 LC |
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 | |
07d83abe MV |
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 | |
73e46534 KR |
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 | date(1) command. | |
07d83abe MV |
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 | ||
d7a22073 LC |
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 | |
07d83abe MV |
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 | |
40499598 | 265 | procedures (@pxref{Arrays}). |
07d83abe MV |
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 | Guile's runtime behaviour can be modified by setting options. For | |
379 | example, is the language that Guile accepts case sensitive, or should | |
380 | the debugger automatically show a backtrace on error? | |
381 | ||
382 | Guile has two levels of interface for managing options: a low-level | |
383 | control interface, and a user-level interface which allows the enabling | |
384 | or disabling of options. | |
385 | ||
386 | Moreover, the options are classified in groups according to whether they | |
387 | configure @emph{reading}, @emph{printing}, @emph{debugging} or | |
388 | @emph{evaluating}. | |
389 | ||
390 | @menu | |
391 | * Low level options interfaces:: | |
392 | * User level options interfaces:: | |
393 | * Reader options:: | |
394 | * Printing options:: | |
395 | * Debugger options:: | |
396 | * Evaluator options:: | |
397 | * Evaluator trap options:: | |
398 | * Examples of option use:: | |
399 | @end menu | |
400 | ||
401 | ||
402 | @node Low level options interfaces | |
403 | @subsubsection Low Level Options Interfaces | |
404 | ||
405 | @deffn {Scheme Procedure} read-options-interface [setting] | |
406 | @deffnx {Scheme Procedure} eval-options-interface [setting] | |
407 | @deffnx {Scheme Procedure} print-options-interface [setting] | |
408 | @deffnx {Scheme Procedure} debug-options-interface [setting] | |
409 | @deffnx {Scheme Procedure} evaluator-traps-interface [setting] | |
410 | @deffnx {C Function} scm_read_options (setting) | |
411 | @deffnx {C Function} scm_eval_options_interface (setting) | |
412 | @deffnx {C Function} scm_print_options (setting) | |
413 | @deffnx {C Function} scm_debug_options (setting) | |
414 | @deffnx {C Function} scm_evaluator_traps (setting) | |
415 | If one of these procedures is called with no arguments (or with | |
416 | @code{setting == SCM_UNDEFINED} in C code), it returns a list describing | |
417 | the current setting of the read, eval, print, debug or evaluator traps | |
418 | options respectively. The setting of a boolean option is indicated | |
419 | simply by the presence or absence of the option symbol in the list. The | |
420 | setting of a non-boolean option is indicated by the presence of the | |
421 | option symbol immediately followed by the option's current value. | |
422 | ||
423 | If called with a list argument, these procedures interpret the list as | |
424 | an option setting and modify the relevant options accordingly. [FIXME | |
425 | --- this glosses over a lot of details!] | |
426 | ||
427 | If called with any other argument, such as @code{'help}, these | |
428 | procedures return a list of entries like @code{(@var{OPTION-SYMBOL} | |
429 | @var{DEFAULT-VALUE} @var{DOC-STRING})}, with each entry giving the | |
430 | default value and documentation for each option symbol in the relevant | |
431 | set of options. | |
432 | @end deffn | |
433 | ||
434 | ||
435 | @node User level options interfaces | |
436 | @subsubsection User Level Options Interfaces | |
437 | ||
438 | @c @deftp {Data type} scm_option | |
439 | @c @code{scm_option} is used to represent run time options. It can be a | |
440 | @c @emph{boolean} type, in which case the option will be set by the strings | |
441 | @c @code{"yes"} and @code{"no"}. It can be a | |
442 | @c @end deftp | |
443 | ||
444 | @c NJFIXME | |
445 | @deffn {Scheme Procedure} <group>-options [arg] | |
446 | @deffnx {Scheme Procedure} read-options [arg] | |
447 | @deffnx {Scheme Procedure} print-options [arg] | |
448 | @deffnx {Scheme Procedure} debug-options [arg] | |
449 | @deffnx {Scheme Procedure} traps [arg] | |
450 | These functions list the options in their group. The optional argument | |
451 | @var{arg} is a symbol which modifies the form in which the options are | |
452 | presented. | |
453 | ||
454 | With no arguments, @code{<group>-options} returns the values of the | |
455 | options in that particular group. If @var{arg} is @code{'help}, a | |
456 | description of each option is given. If @var{arg} is @code{'full}, | |
457 | programmers' options are also shown. | |
458 | ||
459 | @var{arg} can also be a list representing the state of all options. In | |
460 | this case, the list contains single symbols (for enabled boolean | |
461 | options) and symbols followed by values. | |
462 | @end deffn | |
463 | [FIXME: I don't think 'full is ever any different from 'help. What's | |
464 | up?] | |
465 | ||
466 | @c NJFIXME | |
467 | @deffn {Scheme Procedure} <group>-enable option-symbol | |
468 | @deffnx {Scheme Procedure} read-enable option-symbol | |
469 | @deffnx {Scheme Procedure} print-enable option-symbol | |
470 | @deffnx {Scheme Procedure} debug-enable option-symbol | |
471 | @deffnx {Scheme Procedure} trap-enable option-symbol | |
472 | These functions set the specified @var{option-symbol} in their options | |
473 | group. They only work if the option is boolean, and throw an error | |
474 | otherwise. | |
475 | @end deffn | |
476 | ||
477 | @c NJFIXME | |
478 | @deffn {Scheme Procedure} <group>-disable option-symbol | |
479 | @deffnx {Scheme Procedure} read-disable option-symbol | |
480 | @deffnx {Scheme Procedure} print-disable option-symbol | |
481 | @deffnx {Scheme Procedure} debug-disable option-symbol | |
482 | @deffnx {Scheme Procedure} trap-disable option-symbol | |
483 | These functions turn off the specified @var{option-symbol} in their | |
484 | options group. They only work if the option is boolean, and throw an | |
485 | error otherwise. | |
486 | @end deffn | |
487 | ||
488 | @c NJFIXME | |
489 | @deffn syntax <group>-set! option-symbol value | |
490 | @deffnx syntax read-set! option-symbol value | |
491 | @deffnx syntax print-set! option-symbol value | |
492 | @deffnx syntax debug-set! option-symbol value | |
493 | @deffnx syntax trap-set! option-symbol value | |
494 | These functions set a non-boolean @var{option-symbol} to the specified | |
495 | @var{value}. | |
496 | @end deffn | |
497 | ||
498 | ||
499 | @node Reader options | |
500 | @subsubsection Reader options | |
501 | @cindex options - read | |
502 | @cindex read options | |
503 | ||
504 | Here is the list of reader options generated by typing | |
505 | @code{(read-options 'full)} in Guile. You can also see the default | |
506 | values. | |
507 | ||
508 | @smalllisp | |
ef4cbc08 | 509 | keywords #f Style of keyword recognition: #f, 'prefix or 'postfix |
07d83abe MV |
510 | case-insensitive no Convert symbols to lower case. |
511 | positions yes Record positions of source code expressions. | |
512 | copy no Copy source code expressions. | |
513 | @end smalllisp | |
514 | ||
515 | Notice that while Standard Scheme is case insensitive, to ease | |
516 | translation of other Lisp dialects, notably Emacs Lisp, into Guile, | |
517 | Guile is case-sensitive by default. | |
518 | ||
519 | To make Guile case insensitive, you can type | |
520 | ||
aba0dff5 | 521 | @lisp |
07d83abe | 522 | (read-enable 'case-insensitive) |
aba0dff5 | 523 | @end lisp |
07d83abe MV |
524 | |
525 | @node Printing options | |
526 | @subsubsection Printing options | |
527 | ||
528 | Here is the list of print options generated by typing | |
529 | @code{(print-options 'full)} in Guile. You can also see the default | |
530 | values. | |
531 | ||
532 | @smallexample | |
227eafdb MV |
533 | quote-keywordish-symbols reader How to print symbols that have a colon |
534 | as their first or last character. The | |
535 | value '#f' does not quote the colons; | |
536 | '#t' quotes them; 'reader' quotes | |
537 | them when the reader option | |
538 | 'keywords' is not '#f'. | |
539 | ||
540 | highlight-prefix @{ The string to print before highlighted values. | |
541 | highlight-suffix @} The string to print after highlighted values. | |
542 | ||
543 | source no Print closures with source. | |
544 | closure-hook #f Hook for printing closures. | |
07d83abe MV |
545 | @end smallexample |
546 | ||
547 | ||
548 | @node Evaluator options | |
549 | @subsubsection Evaluator options | |
550 | ||
551 | These are the evaluator options with their default values, as they are | |
552 | printed by typing @code{(eval-options 'full)} in Guile. | |
553 | ||
554 | @smallexample | |
555 | stack 22000 Size of thread stacks (in machine words). | |
556 | @end smallexample | |
557 | ||
558 | ||
559 | @node Evaluator trap options | |
560 | @subsubsection Evaluator trap options | |
561 | [FIXME: These flags, together with their corresponding handlers, are not | |
562 | user level options. Probably this entire section should be moved to the | |
563 | documentation about the low-level programmer debugging interface.] | |
564 | ||
565 | Here is the list of evaluator trap options generated by typing | |
566 | @code{(traps 'full)} in Guile. You can also see the default values. | |
567 | ||
568 | @smallexample | |
569 | exit-frame no Trap when exiting eval or apply. | |
570 | apply-frame no Trap when entering apply. | |
571 | enter-frame no Trap when eval enters new frame. | |
19ab431e | 572 | memoize-symbol no Trap when eval memoizes a symbol's value |
07d83abe MV |
573 | traps yes Enable evaluator traps. |
574 | @end smallexample | |
575 | ||
576 | @deffn apply-frame-handler key cont tailp | |
577 | Called when a procedure is being applied. | |
578 | ||
579 | Called if: | |
580 | ||
581 | @itemize @bullet | |
582 | @item | |
583 | evaluator traps are enabled [traps interface], and | |
584 | @item | |
585 | either | |
586 | @itemize @minus | |
587 | @item | |
588 | @code{apply-frame} is enabled [traps interface], or | |
589 | @item | |
590 | trace mode is on [debug-options interface], and the procedure being | |
591 | called has the trace property enabled. | |
592 | @end itemize | |
593 | @end itemize | |
594 | ||
31e2cc50 NJ |
595 | @var{cont} is a ``debug object'', which means that it can be passed to |
596 | @code{make-stack} to discover the stack at the point of the trap. The | |
597 | apply frame handler's code can capture a restartable continuation if it | |
598 | wants to by using @code{call-with-current-continuation} in the usual way. | |
07d83abe MV |
599 | |
600 | @var{tailp} is true if this is a tail call | |
601 | @end deffn | |
602 | ||
603 | @deffn exit-frame-handler key cont retval | |
604 | Called when a value is returned from a procedure. | |
605 | ||
606 | Called if: | |
607 | ||
608 | @itemize @bullet | |
609 | @item | |
610 | evaluator traps are enabled [traps interface], and | |
611 | @item | |
612 | either | |
613 | @itemize @minus | |
614 | @item | |
615 | @code{exit-frame} is enabled [traps interface], or | |
616 | @item | |
617 | trace mode is on [debug-options interface], and the procedure being | |
618 | called has the trace property enabled. | |
619 | @end itemize | |
620 | @end itemize | |
621 | ||
31e2cc50 NJ |
622 | @var{cont} is a ``debug object'', which means that it can be passed to |
623 | @code{make-stack} to discover the stack at the point of the trap. The | |
624 | exit frame handler's code can capture a restartable continuation if it | |
625 | wants to by using @code{call-with-current-continuation} in the usual | |
626 | way. | |
07d83abe MV |
627 | |
628 | @var{retval} is the return value. | |
629 | @end deffn | |
630 | ||
19ab431e HWN |
631 | @deffn memoize-symbol-handler key cont expression env |
632 | Called when the evaluator memoizes the value of a procedure symbol | |
633 | ||
634 | @var{cont} is a ``debug object'', which means that it can be passed to | |
635 | @code{make-stack} to discover the stack at the point of the trap. The | |
636 | exit frame handler's code can capture a restartable continuation if it | |
637 | wants to by using @code{call-with-current-continuation} in the usual | |
638 | way. | |
639 | ||
640 | @var{retval} is the return value. | |
641 | @end deffn | |
642 | ||
24dbb5ed NJ |
643 | @deffn {Scheme Procedure} with-traps thunk |
644 | @deffnx {C Function} scm_with_traps (thunk) | |
645 | Call @var{thunk} with traps enabled. | |
646 | @end deffn | |
647 | ||
648 | @deffn {Scheme Procedure} debug-object? obj | |
649 | @deffnx {C Function} scm_debug_object_p (obj) | |
650 | Return @code{#t} if @var{obj} is a debug object. | |
651 | @end deffn | |
652 | ||
19ab431e | 653 | |
07d83abe MV |
654 | @node Debugger options |
655 | @subsubsection Debugger options | |
656 | ||
657 | Here is the list of print options generated by typing | |
658 | @code{(debug-options 'full)} in Guile. You can also see the default | |
659 | values. | |
660 | ||
661 | @smallexample | |
662 | stack 20000 Stack size limit (0 = no check). | |
663 | debug yes Use the debugging evaluator. | |
664 | backtrace no Show backtrace on error. | |
665 | depth 20 Maximal length of printed backtrace. | |
666 | maxdepth 1000 Maximal number of stored backtrace frames. | |
667 | frames 3 Maximum number of tail-recursive frames in backtrace. | |
668 | indent 10 Maximal indentation in backtrace. | |
669 | backwards no Display backtrace in anti-chronological order. | |
670 | procnames yes Record procedure names at definition. | |
671 | trace no *Trace mode. | |
672 | breakpoints no *Check for breakpoints. | |
31e2cc50 | 673 | cheap yes *This option is now obsolete. Setting it has no effect. |
07d83abe MV |
674 | @end smallexample |
675 | ||
676 | @subsubheading Stack overflow | |
677 | ||
678 | @cindex overflow, stack | |
679 | @cindex stack overflow | |
680 | Stack overflow errors are caused by a computation trying to use more | |
681 | stack space than has been enabled by the @code{stack} option. They are | |
682 | reported like this: | |
683 | ||
684 | @lisp | |
685 | (non-tail-recursive-factorial 500) | |
686 | @print{} | |
687 | ERROR: Stack overflow | |
688 | ABORT: (stack-overflow) | |
689 | @end lisp | |
690 | ||
691 | If you get an error like this, you can either try rewriting your code to | |
692 | use less stack space, or increase the maximum stack size. To increase | |
693 | the maximum stack size, use @code{debug-set!}, for example: | |
694 | ||
695 | @lisp | |
696 | (debug-set! stack 200000) | |
697 | @result{} | |
45867c2a NJ |
698 | (show-file-name #t stack 200000 debug backtrace depth 20 |
699 | maxdepth 1000 frames 3 indent 10 width 79 procnames cheap) | |
07d83abe MV |
700 | |
701 | (non-tail-recursive-factorial 500) | |
702 | @result{} | |
703 | 122013682599111006870123878542304692625357434@dots{} | |
704 | @end lisp | |
705 | ||
706 | If you prefer to try rewriting your code, you may be able to save stack | |
bfc083ec KR |
707 | space by making some of your procedures @dfn{tail recursive} |
708 | (@pxref{Tail Calls}). | |
07d83abe MV |
709 | |
710 | ||
711 | @node Examples of option use | |
712 | @subsubsection Examples of option use | |
713 | ||
714 | Here is an example of a session in which some read and debug option | |
715 | handling procedures are used. In this example, the user | |
716 | ||
717 | @enumerate | |
718 | @item | |
719 | Notices that the symbols @code{abc} and @code{aBc} are not the same | |
720 | @item | |
721 | Examines the @code{read-options}, and sees that @code{case-insensitive} | |
722 | is set to ``no''. | |
723 | @item | |
724 | Enables @code{case-insensitive} | |
725 | @item | |
726 | Verifies that now @code{aBc} and @code{abc} are the same | |
727 | @item | |
728 | Disables @code{case-insensitive} and enables debugging @code{backtrace} | |
729 | @item | |
730 | Reproduces the error of displaying @code{aBc} with backtracing enabled | |
731 | [FIXME: this last example is lame because there is no depth in the | |
732 | backtrace. Need to give a better example, possibly putting debugging | |
733 | option examples in a separate session.] | |
734 | @end enumerate | |
735 | ||
07d83abe MV |
736 | @smalllisp |
737 | guile> (define abc "hello") | |
738 | guile> abc | |
739 | "hello" | |
740 | guile> aBc | |
741 | ERROR: In expression aBc: | |
742 | ERROR: Unbound variable: aBc | |
743 | ABORT: (misc-error) | |
744 | ||
745 | Type "(backtrace)" to get more information. | |
746 | guile> (read-options 'help) | |
ef4cbc08 | 747 | keywords #f Style of keyword recognition: #f, 'prefix or 'postfix |
07d83abe MV |
748 | case-insensitive no Convert symbols to lower case. |
749 | positions yes Record positions of source code expressions. | |
750 | copy no Copy source code expressions. | |
751 | guile> (debug-options 'help) | |
752 | stack 20000 Stack size limit (0 = no check). | |
753 | debug yes Use the debugging evaluator. | |
754 | backtrace no Show backtrace on error. | |
755 | depth 20 Maximal length of printed backtrace. | |
756 | maxdepth 1000 Maximal number of stored backtrace frames. | |
757 | frames 3 Maximum number of tail-recursive frames in backtrace. | |
758 | indent 10 Maximal indentation in backtrace. | |
759 | backwards no Display backtrace in anti-chronological order. | |
760 | procnames yes Record procedure names at definition. | |
761 | trace no *Trace mode. | |
762 | breakpoints no *Check for breakpoints. | |
31e2cc50 | 763 | cheap yes *This option is now obsolete. Setting it has no effect. |
07d83abe MV |
764 | guile> (read-enable 'case-insensitive) |
765 | (keywords #f case-insensitive positions) | |
766 | guile> aBc | |
767 | "hello" | |
768 | guile> (read-disable 'case-insensitive) | |
769 | (keywords #f positions) | |
770 | guile> (debug-enable 'backtrace) | |
771 | (stack 20000 debug backtrace depth 20 maxdepth 1000 frames 3 indent 10 procnames cheap) | |
772 | guile> aBc | |
773 | ||
774 | Backtrace: | |
775 | 0* aBc | |
776 | ||
777 | ERROR: In expression aBc: | |
778 | ERROR: Unbound variable: aBc | |
779 | ABORT: (misc-error) | |
780 | guile> | |
781 | @end smalllisp | |
782 | ||
783 | ||
784 | @c Local Variables: | |
785 | @c TeX-master: "guile.texi" | |
786 | @c End: |