1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
|
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2010, 2011,
@c 2012 Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@raisesections
@node Hello Guile!
@section Hello Guile!
This chapter presents a quick tour of all the ways that Guile can be
used. There are additional examples in the @file{examples/}
directory in the Guile source distribution. It also explains how best to report
any problems that you find.
The following examples assume that Guile has been installed in
@code{/usr/local/}.
@menu
* Running Guile Interactively::
* Running Guile Scripts::
* Linking Guile into Programs::
* Writing Guile Extensions::
* Using the Guile Module System::
* Reporting Bugs::
@end menu
@node Running Guile Interactively
@subsection Running Guile Interactively
In its simplest form, Guile acts as an interactive interpreter for the
Scheme programming language, reading and evaluating Scheme expressions
the user enters from the terminal. Here is a sample interaction between
Guile and a user; the user's input appears after the @code{$} and
@code{scheme@@(guile-user)>} prompts:
@example
$ guile
scheme@@(guile-user)> (+ 1 2 3) ; add some numbers
$1 = 6
scheme@@(guile-user)> (define (factorial n) ; define a function
(if (zero? n) 1 (* n (factorial (- n 1)))))
scheme@@(guile-user)> (factorial 20)
$2 = 2432902008176640000
scheme@@(guile-user)> (getpwnam "root") ; look in /etc/passwd
$3 = #("root" "x" 0 0 "root" "/root" "/bin/bash")
scheme@@(guile-user)> @kbd{C-d}
$
@end example
@node Running Guile Scripts
@subsection Running Guile Scripts
Like AWK, Perl, or any shell, Guile can interpret script files. A Guile
script is simply a file of Scheme code with some extra information at
the beginning which tells the operating system how to invoke Guile, and
then tells Guile how to handle the Scheme code.
Here is a trivial Guile script. @xref{Guile Scripting}, for more details.
@example
#!/usr/local/bin/guile -s
!#
(display "Hello, world!")
(newline)
@end example
@node Linking Guile into Programs
@subsection Linking Guile into Programs
The Guile interpreter is available as an object library, to be linked
into applications using Scheme as a configuration or extension
language.
Here is @file{simple-guile.c}, source code for a program that will
produce a complete Guile interpreter. In addition to all usual
functions provided by Guile, it will also offer the function
@code{my-hostname}.
@example
#include <stdlib.h>
#include <libguile.h>
static SCM
my_hostname (void)
@{
char *s = getenv ("HOSTNAME");
if (s == NULL)
return SCM_BOOL_F;
else
return scm_from_locale_string (s);
@}
static void
inner_main (void *data, int argc, char **argv)
@{
scm_c_define_gsubr ("my-hostname", 0, 0, 0, my_hostname);
scm_shell (argc, argv);
@}
int
main (int argc, char **argv)
@{
scm_boot_guile (argc, argv, inner_main, 0);
return 0; /* never reached */
@}
@end example
When Guile is correctly installed on your system, the above program
can be compiled and linked like this:
@example
$ gcc -o simple-guile simple-guile.c \
`pkg-config --cflags --libs guile-@value{EFFECTIVE-VERSION}`
@end example
When it is run, it behaves just like the @code{guile} program except
that you can also call the new @code{my-hostname} function.
@example
$ ./simple-guile
scheme@@(guile-user)> (+ 1 2 3)
$1 = 6
scheme@@(guile-user)> (my-hostname)
"burns"
@end example
@node Writing Guile Extensions
@subsection Writing Guile Extensions
You can link Guile into your program and make Scheme available to the
users of your program. You can also link your library into Guile and
make its functionality available to all users of Guile.
A library that is linked into Guile is called an @dfn{extension}, but it
really just is an ordinary object library.
The following example shows how to write a simple extension for Guile
that makes the @code{j0} function available to Scheme code.
@smallexample
#include <math.h>
#include <libguile.h>
SCM
j0_wrapper (SCM x)
@{
return scm_from_double (j0 (scm_to_double (x)));
@}
void
init_bessel ()
@{
scm_c_define_gsubr ("j0", 1, 0, 0, j0_wrapper);
@}
@end smallexample
This C source file needs to be compiled into a shared library. Here is
how to do it on GNU/Linux:
@smallexample
gcc `pkg-config --cflags guile-@value{EFFECTIVE-VERSION}` \
-shared -o libguile-bessel.so -fPIC bessel.c
@end smallexample
For creating shared libraries portably, we recommend the use of GNU
Libtool (@pxref{Top, , Introduction, libtool, GNU Libtool}).
A shared library can be loaded into a running Guile process with the
function @code{load-extension}. The @code{j0} is then immediately
available:
@smallexample
$ guile
scheme@@(guile-user)> (load-extension "./libguile-bessel" "init_bessel")
scheme@@(guile-user)> (j0 2)
$1 = 0.223890779141236
@end smallexample
For more on how to install your extension, @pxref{Installing Site
Packages}.
@node Using the Guile Module System
@subsection Using the Guile Module System
Guile has support for dividing a program into @dfn{modules}. By using
modules, you can group related code together and manage the
composition of complete programs from largely independent parts.
For more details on the module system beyond this introductory material,
@xref{Modules}.
@menu
* Using Modules::
* Writing new Modules::
* Putting Extensions into Modules::
@end menu
@node Using Modules
@subsubsection Using Modules
Guile comes with a lot of useful modules, for example for string
processing or command line parsing. Additionally, there exist many
Guile modules written by other Guile hackers, but which have to be
installed manually.
Here is a sample interactive session that shows how to use the
@code{(ice-9 popen)} module which provides the means for communicating
with other processes over pipes together with the @code{(ice-9
rdelim)} module that provides the function @code{read-line}.
@smallexample
$ guile
scheme@@(guile-user)> (use-modules (ice-9 popen))
scheme@@(guile-user)> (use-modules (ice-9 rdelim))
scheme@@(guile-user)> (define p (open-input-pipe "ls -l"))
scheme@@(guile-user)> (read-line p)
$1 = "total 30"
scheme@@(guile-user)> (read-line p)
$2 = "drwxr-sr-x 2 mgrabmue mgrabmue 1024 Mar 29 19:57 CVS"
@end smallexample
@node Writing new Modules
@subsubsection Writing new Modules
You can create new modules using the syntactic form
@code{define-module}. All definitions following this form until the
next @code{define-module} are placed into the new module.
One module is usually placed into one file, and that file is installed
in a location where Guile can automatically find it. The following
session shows a simple example.
@smallexample
$ cat /usr/local/share/guile/site/foo/bar.scm
(define-module (foo bar)
#:export (frob))
(define (frob x) (* 2 x))
$ guile
scheme@@(guile-user)> (use-modules (foo bar))
scheme@@(guile-user)> (frob 12)
$1 = 24
@end smallexample
For more on how to install your module, @pxref{Installing Site
Packages}.
@node Putting Extensions into Modules
@subsubsection Putting Extensions into Modules
In addition to Scheme code you can also put things that are defined in
C into a module.
You do this by writing a small Scheme file that defines the module and
call @code{load-extension} directly in the body of the module.
@smallexample
$ cat /usr/local/share/guile/site/math/bessel.scm
(define-module (math bessel)
#:export (j0))
(load-extension "libguile-bessel" "init_bessel")
$ file /usr/local/lib/guile/@value{EFFECTIVE-VERSION}/extensions/libguile-bessel.so
@dots{} ELF 32-bit LSB shared object @dots{}
$ guile
scheme@@(guile-user)> (use-modules (math bessel))
scheme@@(guile-user)> (j0 2)
$1 = 0.223890779141236
@end smallexample
@xref{Modules and Extensions}, for more information.
@lowersections
@node Reporting Bugs
@section Reporting Bugs
Any problems with the installation should be reported to
@email{bug-guile@@gnu.org}.
If you find a bug in Guile, please report it to the Guile developers, so
they can fix it. They may also be able to suggest workarounds when it
is not possible for you to apply the bug-fix or install a new version of
Guile yourself.
Before sending in bug reports, please check with the following list that
you really have found a bug.
@itemize @bullet
@item
Whenever documentation and actual behavior differ, you have certainly
found a bug, either in the documentation or in the program.
@item
When Guile crashes, it is a bug.
@item
When Guile hangs or takes forever to complete a task, it is a bug.
@item
When calculations produce wrong results, it is a bug.
@item
When Guile signals an error for valid Scheme programs, it is a bug.
@item
When Guile does not signal an error for invalid Scheme programs, it may
be a bug, unless this is explicitly documented.
@item
When some part of the documentation is not clear and does not make sense
to you even after re-reading the section, it is a bug.
@end itemize
Before reporting the bug, check whether any programs you have loaded
into Guile, including your @file{.guile} file, set any variables that
may affect the functioning of Guile. Also, see whether the problem
happens in a freshly started Guile without loading your @file{.guile}
file (start Guile with the @code{-q} switch to prevent loading the init
file). If the problem does @emph{not} occur then, you must report the
precise contents of any programs that you must load into Guile in order
to cause the problem to occur.
When you write a bug report, please make sure to include as much of the
information described below in the report. If you can't figure out some
of the items, it is not a problem, but the more information we get, the
more likely we can diagnose and fix the bug.
@itemize @bullet
@item
The version number of Guile. You can get this information from invoking
@samp{guile --version} at your shell, or calling @code{(version)} from
within Guile.
@item
Your machine type, as determined by the @code{config.guess} shell
script. If you have a Guile checkout, this file is located in
@code{build-aux}; otherwise you can fetch the latest version from
@uref{http://git.savannah.gnu.org/gitweb/?p=config.git;a=blob_plain;f=config.guess;hb=HEAD}.
@example
$ build-aux/config.guess
x86_64-unknown-linux-gnu
@end example
@item
If you installed Guile from a binary package, the version of that
package. On systems that use RPM, use @code{rpm -qa | grep guile}. On systems
that use DPKG, @code{dpkg -l | grep guile}.
@item
If you built Guile yourself, the build configuration that you used:
@example
$ ./config.status --config
'--enable-error-on-warning' '--disable-deprecated'...
@end example
@item
A complete description of how to reproduce the bug.
If you have a Scheme program that produces the bug, please include it in
the bug report. If your program is too big to include. please try to
reduce your code to a minimal test case.
If you can reproduce your problem at the REPL, that is best. Give a
transcript of the expressions you typed at the REPL.
@item
A description of the incorrect behavior. For example, "The Guile
process gets a fatal signal," or, "The resulting output is as follows,
which I think is wrong."
If the manifestation of the bug is a Guile error message, it is
important to report the precise text of the error message, and a
backtrace showing how the Scheme program arrived at the error. This can
be done using the @code{,backtrace} command in Guile's debugger.
@end itemize
If your bug causes Guile to crash, additional information from a
low-level debugger such as GDB might be helpful. If you have built Guile
yourself, you can run Guile under GDB via the
@code{meta/gdb-uninstalled-guile} script. Instead of invoking Guile as
usual, invoke the wrapper script, type @code{run} to start the process,
then @code{backtrace} when the crash comes. Include that backtrace in
your report.
@c Local Variables:
@c TeX-master: "guile.texi"
@c End:
|