2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2010, 2011,
4 @c 2012 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-@value{EFFECTIVE-VERSION}`
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_from_double (j0 (scm_to_double (x)));
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 `pkg-config --cflags guile-@value{EFFECTIVE-VERSION}` \
167 -shared -o libguile-bessel.so -fPIC bessel.c
170 For creating shared libraries portably, we recommend the use of GNU
171 Libtool (@pxref{Top, , Introduction, libtool, GNU Libtool}).
173 A shared library can be loaded into a running Guile process with the
174 function @code{load-extension}. The @code{j0} is then immediately
179 scheme@@(guile-user)> (load-extension "./libguile-bessel" "init_bessel")
180 scheme@@(guile-user)> (j0 2)
181 $1 = 0.223890779141236
184 For more on how to install your extension, @pxref{Installing Site
188 @node Using the Guile Module System
189 @subsection Using the Guile Module System
191 Guile has support for dividing a program into @dfn{modules}. By using
192 modules, you can group related code together and manage the
193 composition of complete programs from largely independent parts.
195 For more details on the module system beyond this introductory material,
200 * Writing new Modules::
201 * Putting Extensions into Modules::
206 @subsubsection Using Modules
208 Guile comes with a lot of useful modules, for example for string
209 processing or command line parsing. Additionally, there exist many
210 Guile modules written by other Guile hackers, but which have to be
213 Here is a sample interactive session that shows how to use the
214 @code{(ice-9 popen)} module which provides the means for communicating
215 with other processes over pipes together with the @code{(ice-9
216 rdelim)} module that provides the function @code{read-line}.
220 scheme@@(guile-user)> (use-modules (ice-9 popen))
221 scheme@@(guile-user)> (use-modules (ice-9 rdelim))
222 scheme@@(guile-user)> (define p (open-input-pipe "ls -l"))
223 scheme@@(guile-user)> (read-line p)
225 scheme@@(guile-user)> (read-line p)
226 $2 = "drwxr-sr-x 2 mgrabmue mgrabmue 1024 Mar 29 19:57 CVS"
229 @node Writing new Modules
230 @subsubsection Writing new Modules
232 You can create new modules using the syntactic form
233 @code{define-module}. All definitions following this form until the
234 next @code{define-module} are placed into the new module.
236 One module is usually placed into one file, and that file is installed
237 in a location where Guile can automatically find it. The following
238 session shows a simple example.
241 $ cat /usr/local/share/guile/site/foo/bar.scm
243 (define-module (foo bar)
246 (define (frob x) (* 2 x))
249 scheme@@(guile-user)> (use-modules (foo bar))
250 scheme@@(guile-user)> (frob 12)
254 For more on how to install your module, @pxref{Installing Site
258 @node Putting Extensions into Modules
259 @subsubsection Putting Extensions into Modules
261 In addition to Scheme code you can also put things that are defined in
264 You do this by writing a small Scheme file that defines the module and
265 call @code{load-extension} directly in the body of the module.
268 $ cat /usr/local/share/guile/site/math/bessel.scm
270 (define-module (math bessel)
273 (load-extension "libguile-bessel" "init_bessel")
275 $ file /usr/local/lib/guile/@value{EFFECTIVE-VERSION}/extensions/libguile-bessel.so
276 @dots{} ELF 32-bit LSB shared object @dots{}
278 scheme@@(guile-user)> (use-modules (math bessel))
279 scheme@@(guile-user)> (j0 2)
280 $1 = 0.223890779141236
283 @xref{Modules and Extensions}, for more information.
288 @section Reporting Bugs
290 Any problems with the installation should be reported to
291 @email{bug-guile@@gnu.org}.
293 If you find a bug in Guile, please report it to the Guile developers, so
294 they can fix it. They may also be able to suggest workarounds when it
295 is not possible for you to apply the bug-fix or install a new version of
298 Before sending in bug reports, please check with the following list that
299 you really have found a bug.
303 Whenever documentation and actual behavior differ, you have certainly
304 found a bug, either in the documentation or in the program.
307 When Guile crashes, it is a bug.
310 When Guile hangs or takes forever to complete a task, it is a bug.
313 When calculations produce wrong results, it is a bug.
316 When Guile signals an error for valid Scheme programs, it is a bug.
319 When Guile does not signal an error for invalid Scheme programs, it may
320 be a bug, unless this is explicitly documented.
323 When some part of the documentation is not clear and does not make sense
324 to you even after re-reading the section, it is a bug.
327 Before reporting the bug, check whether any programs you have loaded
328 into Guile, including your @file{.guile} file, set any variables that
329 may affect the functioning of Guile. Also, see whether the problem
330 happens in a freshly started Guile without loading your @file{.guile}
331 file (start Guile with the @code{-q} switch to prevent loading the init
332 file). If the problem does @emph{not} occur then, you must report the
333 precise contents of any programs that you must load into Guile in order
334 to cause the problem to occur.
336 When you write a bug report, please make sure to include as much of the
337 information described below in the report. If you can't figure out some
338 of the items, it is not a problem, but the more information we get, the
339 more likely we can diagnose and fix the bug.
343 The version number of Guile. You can get this information from invoking
344 @samp{guile --version} at your shell, or calling @code{(version)} from
348 Your machine type, as determined by the @code{config.guess} shell
349 script. If you have a Guile checkout, this file is located in
350 @code{build-aux}; otherwise you can fetch the latest version from
351 @uref{http://git.savannah.gnu.org/gitweb/?p=config.git;a=blob_plain;f=config.guess;hb=HEAD}.
354 $ build-aux/config.guess
355 x86_64-unknown-linux-gnu
359 If you installed Guile from a binary package, the version of that
360 package. On systems that use RPM, use @code{rpm -qa | grep guile}. On systems
361 that use DPKG, @code{dpkg -l | grep guile}.
364 If you built Guile yourself, the build configuration that you used:
367 $ ./config.status --config
368 '--enable-error-on-warning' '--disable-deprecated'...
372 A complete description of how to reproduce the bug.
374 If you have a Scheme program that produces the bug, please include it in
375 the bug report. If your program is too big to include. please try to
376 reduce your code to a minimal test case.
378 If you can reproduce your problem at the REPL, that is best. Give a
379 transcript of the expressions you typed at the REPL.
382 A description of the incorrect behavior. For example, "The Guile
383 process gets a fatal signal," or, "The resulting output is as follows,
384 which I think is wrong."
386 If the manifestation of the bug is a Guile error message, it is
387 important to report the precise text of the error message, and a
388 backtrace showing how the Scheme program arrived at the error. This can
389 be done using the @code{,backtrace} command in Guile's debugger.
392 If your bug causes Guile to crash, additional information from a
393 low-level debugger such as GDB might be helpful. If you have built Guile
394 yourself, you can run Guile under GDB via the
395 @code{meta/gdb-uninstalled-guile} script. Instead of invoking Guile as
396 usual, invoke the wrapper script, type @code{run} to start the process,
397 then @code{backtrace} when the crash comes. Include that backtrace in
403 @c TeX-master: "guile.texi"