Commit | Line | Data |
---|---|---|
07d83abe MV |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Guile Reference Manual. | |
df3d365a LC |
3 | @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2006, |
4 | @c 2008, 2009, 2010, 2011, 2012, 2013 | |
07d83abe MV |
5 | @c Free Software Foundation, Inc. |
6 | @c See the file guile.texi for copying conditions. | |
7 | ||
07d83abe MV |
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 | |
f88e9510 | 63 | i.e.@: @file{/usr/share/guile/2.2/} |
07d83abe MV |
64 | |
65 | @lisp | |
f88e9510 AW |
66 | (version) @result{} "2.2.0" |
67 | (effective-version) @result{} "2.2" | |
0740cb49 | 68 | (major-version) @result{} "2" |
f88e9510 AW |
69 | (minor-version) @result{} "2" |
70 | (micro-version) @result{} "0" | |
07d83abe MV |
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 |
1a1ce64d RW |
86 | @file{/usr/local/share/guile/@var{GUILE_EFFECTIVE_VERSION}} or |
87 | @file{/usr/share/guile/@var{GUILE_EFFECTIVE_VERSION}}; | |
45867c2a | 88 | |
1a1ce64d | 89 | @noindent |
f88e9510 | 90 | for example @file{/usr/local/share/guile/2.2}. |
07d83abe MV |
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 | ||
988ca6b2 JE |
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 | ||
07d83abe MV |
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 | |
097a793b AW |
148 | also as a part of @code{pkg-config --libs |
149 | guile-@value{EFFECTIVE-VERSION}} output. The value for | |
07d83abe | 150 | @code{guileversion} has form X.Y.Z, and should be the same as returned |
097a793b AW |
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). | |
07d83abe MV |
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 | ||
d7a22073 LC |
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 | |
07d83abe MV |
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 | |
679cceed | 227 | with that feature enabled --- i.e.@: the feature is built into the library |
07d83abe MV |
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 | |
40499598 | 240 | procedures (@pxref{Arrays}). |
07d83abe MV |
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 | ||
df3d365a LC |
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 | ||
07d83abe MV |
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 | ||
1cfdb1bb AW |
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. | |
07d83abe | 361 | |
1cfdb1bb | 362 | For more information on reader options, @xref{Scheme Read}. |
07d83abe | 363 | |
1cfdb1bb | 364 | For more information on print options, @xref{Scheme Write}. |
07d83abe | 365 | |
659c1e29 AW |
366 | Finally, for more information on debugger options, @xref{Debug |
367 | Options}. | |
07d83abe | 368 | |
07d83abe MV |
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 | |
1cfdb1bb | 383 | Quits the recursive prompt |
07d83abe | 384 | @item |
1cfdb1bb | 385 | Verifies that now @code{aBc} and @code{abc} are the same |
07d83abe MV |
386 | @end enumerate |
387 | ||
07d83abe | 388 | @smalllisp |
1cfdb1bb AW |
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: | |
07d83abe | 395 | ERROR: Unbound variable: aBc |
1cfdb1bb AW |
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. | |
c869f0c1 AW |
404 | hungry-eol-escapes no In strings, consume leading whitespace after an |
405 | escaped end-of-line. | |
bf9eb54a | 406 | curly-infix no Support SRFI-105 curly infix expressions. |
1cfdb1bb AW |
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" | |
07d83abe MV |
412 | @end smalllisp |
413 | ||
414 | ||
415 | @c Local Variables: | |
416 | @c TeX-master: "guile.texi" | |
417 | @c End: |