2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2010
4 @c Free Software Foundation, Inc.
5 @c See the file guile.texi for copying conditions.
12 This chapter presents a quick tour of all the ways that Guile can be
13 used. There are additional examples in the @file{examples/}
14 directory in the Guile source distribution. It also explains how best to report
15 any problems that you find.
17 The following examples assume that Guile has been installed in
21 * Running Guile Interactively::
22 * Running Guile Scripts::
23 * Linking Guile into Programs::
24 * Writing Guile Extensions::
25 * Using the Guile Module System::
30 @node Running Guile Interactively
31 @subsection Running Guile Interactively
33 In its simplest form, Guile acts as an interactive interpreter for the
34 Scheme programming language, reading and evaluating Scheme expressions
35 the user enters from the terminal. Here is a sample interaction between
36 Guile and a user; the user's input appears after the @code{$} and
37 @code{scheme@@(guile-user)>} prompts:
41 scheme@@(guile-user)> (+ 1 2 3) ; add some numbers
43 scheme@@(guile-user)> (define (factorial n) ; define a function
44 (if (zero? n) 1 (* n (factorial (- n 1)))))
45 scheme@@(guile-user)> (factorial 20)
46 $2 = 2432902008176640000
47 scheme@@(guile-user)> (getpwnam "root") ; look in /etc/passwd
48 $3 = #("root" "x" 0 0 "root" "/root" "/bin/bash")
49 scheme@@(guile-user)> @kbd{C-d}
54 @node Running Guile Scripts
55 @subsection Running Guile Scripts
57 Like AWK, Perl, or any shell, Guile can interpret script files. A Guile
58 script is simply a file of Scheme code with some extra information at
59 the beginning which tells the operating system how to invoke Guile, and
60 then tells Guile how to handle the Scheme code.
62 Here is a trivial Guile script. @xref{Guile Scripting}, for more details.
65 #!/usr/local/bin/guile -s
67 (display "Hello, world!")
72 @node Linking Guile into Programs
73 @subsection Linking Guile into Programs
75 The Guile interpreter is available as an object library, to be linked
76 into applications using Scheme as a configuration or extension
79 Here is @file{simple-guile.c}, source code for a program that will
80 produce a complete Guile interpreter. In addition to all usual
81 functions provided by Guile, it will also offer the function
91 char *s = getenv ("HOSTNAME");
95 return scm_from_locale_string (s);
99 inner_main (void *data, int argc, char **argv)
101 scm_c_define_gsubr ("my-hostname", 0, 0, 0, my_hostname);
102 scm_shell (argc, argv);
106 main (int argc, char **argv)
108 scm_boot_guile (argc, argv, inner_main, 0);
109 return 0; /* never reached */
113 When Guile is correctly installed on your system, the above program
114 can be compiled and linked like this:
117 $ gcc -o simple-guile simple-guile.c \
118 `pkg-config --cflags --libs guile-2.0`
121 When it is run, it behaves just like the @code{guile} program except
122 that you can also call the new @code{my-hostname} function.
126 scheme@@(guile-user)> (+ 1 2 3)
128 scheme@@(guile-user)> (my-hostname)
132 @node Writing Guile Extensions
133 @subsection Writing Guile Extensions
135 You can link Guile into your program and make Scheme available to the
136 users of your program. You can also link your library into Guile and
137 make its functionality available to all users of Guile.
139 A library that is linked into Guile is called an @dfn{extension}, but it
140 really just is an ordinary object library.
142 The following example shows how to write a simple extension for Guile
143 that makes the @code{j0} function available to Scheme code.
147 #include <libguile.h>
152 return scm_make_real (j0 (scm_num2dbl (x, "j0")));
158 scm_c_define_gsubr ("j0", 1, 0, 0, j0_wrapper);
162 This C source file needs to be compiled into a shared library. Here is
163 how to do it on GNU/Linux:
166 gcc -shared -o libguile-bessel.so -fPIC bessel.c
169 For creating shared libraries portably, we recommend the use of GNU
170 Libtool (@pxref{Top, , Introduction, libtool, GNU Libtool}).
172 A shared library can be loaded into a running Guile process with the
173 function @code{load-extension}. The @code{j0} is then immediately
178 scheme@@(guile-user)> (load-extension "./libguile-bessel" "init_bessel")
179 scheme@@(guile-user)> (j0 2)
180 $1 = 0.223890779141236
184 @node Using the Guile Module System
185 @subsection Using the Guile Module System
187 Guile has support for dividing a program into @dfn{modules}. By using
188 modules, you can group related code together and manage the
189 composition of complete programs from largely independent parts.
191 For more details on the module system beyond this introductory material,
196 * Writing new Modules::
197 * Putting Extensions into Modules::
202 @subsubsection Using Modules
204 Guile comes with a lot of useful modules, for example for string
205 processing or command line parsing. Additionally, there exist many
206 Guile modules written by other Guile hackers, but which have to be
209 Here is a sample interactive session that shows how to use the
210 @code{(ice-9 popen)} module which provides the means for communicating
211 with other processes over pipes together with the @code{(ice-9
212 rdelim)} module that provides the function @code{read-line}.
216 scheme@@(guile-user)> (use-modules (ice-9 popen))
217 scheme@@(guile-user)> (use-modules (ice-9 rdelim))
218 scheme@@(guile-user)> (define p (open-input-pipe "ls -l"))
219 scheme@@(guile-user)> (read-line p)
221 scheme@@(guile-user)> (read-line p)
222 $2 = "drwxr-sr-x 2 mgrabmue mgrabmue 1024 Mar 29 19:57 CVS"
225 @node Writing new Modules
226 @subsubsection Writing new Modules
228 You can create new modules using the syntactic form
229 @code{define-module}. All definitions following this form until the
230 next @code{define-module} are placed into the new module.
232 One module is usually placed into one file, and that file is installed
233 in a location where Guile can automatically find it. The following
234 session shows a simple example.
237 $ cat /usr/local/share/guile/foo/bar.scm
239 (define-module (foo bar)
242 (define (frob x) (* 2 x))
245 scheme@@(guile-user)> (use-modules (foo bar))
246 scheme@@(guile-user)> (frob 12)
250 @node Putting Extensions into Modules
251 @subsubsection Putting Extensions into Modules
253 In addition to Scheme code you can also put things that are defined in
256 You do this by writing a small Scheme file that defines the module and
257 call @code{load-extension} directly in the body of the module.
260 $ cat /usr/local/share/guile/math/bessel.scm
262 (define-module (math bessel)
265 (load-extension "libguile-bessel" "init_bessel")
267 $ file /usr/local/lib/libguile-bessel.so
268 @dots{} ELF 32-bit LSB shared object @dots{}
270 scheme@@(guile-user)> (use-modules (math bessel))
271 scheme@@(guile-user)> (j0 2)
272 $1 = 0.223890779141236
275 @xref{Modules and Extensions}, for more information.
280 @section Reporting Bugs
282 Any problems with the installation should be reported to
283 @email{bug-guile@@gnu.org}.
285 If you find a bug in Guile, please report it to the Guile developers, so
286 they can fix it. They may also be able to suggest workarounds when it
287 is not possible for you to apply the bug-fix or install a new version of
290 Before sending in bug reports, please check with the following list that
291 you really have found a bug.
295 Whenever documentation and actual behavior differ, you have certainly
296 found a bug, either in the documentation or in the program.
299 When Guile crashes, it is a bug.
302 When Guile hangs or takes forever to complete a task, it is a bug.
305 When calculations produce wrong results, it is a bug.
308 When Guile signals an error for valid Scheme programs, it is a bug.
311 When Guile does not signal an error for invalid Scheme programs, it may
312 be a bug, unless this is explicitly documented.
315 When some part of the documentation is not clear and does not make sense
316 to you even after re-reading the section, it is a bug.
319 Before reporting the bug, check whether any programs you have loaded
320 into Guile, including your @file{.guile} file, set any variables that
321 may affect the functioning of Guile. Also, see whether the problem
322 happens in a freshly started Guile without loading your @file{.guile}
323 file (start Guile with the @code{-q} switch to prevent loading the init
324 file). If the problem does @emph{not} occur then, you must report the
325 precise contents of any programs that you must load into Guile in order
326 to cause the problem to occur.
328 When you write a bug report, please make sure to include as much of the
329 information described below in the report. If you can't figure out some
330 of the items, it is not a problem, but the more information we get, the
331 more likely we can diagnose and fix the bug.
335 The version number of Guile. You can get this information from invoking
336 @samp{guile --version} at your shell, or calling @code{(version)} from
340 Your machine type, as determined by the @code{config.guess} shell
341 script. If you have a Guile checkout, this file is located in
342 @code{build-aux}; otherwise you can fetch the latest version from
343 @uref{http://git.savannah.gnu.org/gitweb/?p=config.git;a=blob_plain;f=config.guess;hb=HEAD}.
346 $ build-aux/config.guess
347 x86_64-unknown-linux-gnu
351 If you installed Guile from a binary package, the version of that
352 package. On systems that use RPM, use @code{rpm -qa | grep guile}. On systems
353 that use DPKG, @code{dpkg -l | grep guile}.
356 If you built Guile yourself, the build configuration that you used:
359 $ ./config.status --config
360 '--enable-error-on-warning' '--disable-deprecated'...
364 A complete description of how to reproduce the bug.
366 If you have a Scheme program that produces the bug, please include it in
367 the bug report. If your program is too big to include. please try to
368 reduce your code to a minimal test case.
370 If you can reproduce your problem at the REPL, that is best. Give a
371 transcript of the expressions you typed at the REPL.
374 A description of the incorrect behavior. For example, "The Guile
375 process gets a fatal signal," or, "The resulting output is as follows,
376 which I think is wrong."
378 If the manifestation of the bug is a Guile error message, it is
379 important to report the precise text of the error message, and a
380 backtrace showing how the Scheme program arrived at the error. This can
381 be done using the @code{,backtrace} command in Guile's debugger.
384 If your bug causes Guile to crash, additional information from a
385 low-level debugger such as GDB might be helpful. If you have built Guile
386 yourself, you can run Guile under GDB via the
387 @code{meta/gdb-uninstalled-guile} script. Instead of invoking Guile as
388 usual, invoke the wrapper script, type @code{run} to start the process,
389 then @code{backtrace} when the crash comes. Include that backtrace in
395 @c TeX-master: "guile.texi"