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{guile>} prompts:
41 guile> (+ 1 2 3) ; add some numbers
43 guile> (define (factorial n) ; define a function
44 (if (zero? n) 1 (* n (factorial (- n 1)))))
47 guile> (getpwnam "jimb") ; find my entry in /etc/passwd
48 #("jimb" ".0krIpK2VqNbU" 4008 10 "Jim Blandy" "/u/jimb"
49 "/usr/local/bin/bash")
55 @node Running Guile Scripts
56 @subsection Running Guile Scripts
58 Like AWK, Perl, or any shell, Guile can interpret script files. A Guile
59 script is simply a file of Scheme code with some extra information at
60 the beginning which tells the operating system how to invoke Guile, and
61 then tells Guile how to handle the Scheme code.
63 Here is a trivial Guile script, for more details @xref{Guile Scripting}.
66 #!/usr/local/bin/guile -s
68 (display "Hello, world!")
73 @node Linking Guile into Programs
74 @subsection Linking Guile into Programs
76 The Guile interpreter is available as an object library, to be linked
77 into applications using Scheme as a configuration or extension
80 Here is @file{simple-guile.c}, source code for a program that will
81 produce a complete Guile interpreter. In addition to all usual
82 functions provided by Guile, it will also offer the function
92 char *s = getenv ("HOSTNAME");
96 return scm_from_locale_string (s);
100 inner_main (void *data, int argc, char **argv)
102 scm_c_define_gsubr ("my-hostname", 0, 0, 0, my_hostname);
103 scm_shell (argc, argv);
107 main (int argc, char **argv)
109 scm_boot_guile (argc, argv, inner_main, 0);
110 return 0; /* never reached */
114 When Guile is correctly installed on your system, the above program
115 can be compiled and linked like this:
118 $ gcc -o simple-guile simple-guile.c \
119 `pkg-config --cflags --libs guile-2.0`
122 When it is run, it behaves just like the @code{guile} program except
123 that you can also call the new @code{my-hostname} function.
133 @node Writing Guile Extensions
134 @subsection Writing Guile Extensions
136 You can link Guile into your program and make Scheme available to the
137 users of your program. You can also link your library into Guile and
138 make its functionality available to all users of Guile.
140 A library that is linked into Guile is called an @dfn{extensions}, but
141 it really just is an ordinary object library.
143 The following example shows how to write a simple extension for Guile
144 that makes the @code{j0} function available to Scheme code.
148 #include <libguile.h>
153 return scm_make_real (j0 (scm_num2dbl (x, "j0")));
159 scm_c_define_gsubr ("j0", 1, 0, 0, j0_wrapper);
163 This C source file needs to be compiled into a shared library. Here is
164 how to do it on GNU/Linux:
167 gcc -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 guile> (load-extension "./libguile-bessel" "init_bessel")
185 @node Using the Guile Module System
186 @subsection Using the Guile Module System
188 Guile has support for dividing a program into @dfn{modules}. By using
189 modules, you can group related code together and manage the
190 composition of complete programs from largely independent parts.
192 (Although the module system implementation is in flux, feel free to use it
193 anyway. Guile will provide reasonable backwards compatibility.)
195 Details on the module system beyond this introductory material can be found in
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 guile> (use-modules (ice-9 popen))
221 guile> (use-modules (ice-9 rdelim))
222 guile> (define p (open-input-pipe "ls -l"))
226 "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/foo/bar.scm
243 (define-module (foo bar))
246 (define (frob x) (* 2 x))
249 guile> (use-modules (foo bar))
254 @node Putting Extensions into Modules
255 @subsubsection Putting Extensions into Modules
257 In addition to Scheme code you can also put things that are defined in
260 You do this by writing a small Scheme file that defines the module and
261 call @code{load-extension} directly in the body of the module.
264 $ cat /usr/local/share/guile/math/bessel.scm
266 (define-module (math bessel))
269 (load-extension "libguile-bessel" "init_bessel")
271 $ file /usr/local/lib/libguile-bessel.so
272 @dots{} ELF 32-bit LSB shared object @dots{}
274 guile> (use-modules (math bessel))
279 There is also a way to manipulate the module system from C but only
280 Scheme files can be autoloaded. Thus, we recommend that you define
281 your modules in Scheme.
286 @section Reporting Bugs
288 Any problems with the installation should be reported to
289 @email{bug-guile@@gnu.org}.
291 Whenever you have found a bug in Guile you are encouraged to report it
292 to the Guile developers, so they can fix it. They may also be able to
293 suggest workarounds when it is not possible for you to apply the bug-fix
294 or install a new version of Guile yourself.
296 Before sending in bug reports, please check with the following list that
297 you really have found a bug.
301 Whenever documentation and actual behavior differ, you have certainly
302 found a bug, either in the documentation or in the program.
305 When Guile crashes, it is a bug.
308 When Guile hangs or takes forever to complete a task, it is a bug.
311 When calculations produce wrong results, it is a bug.
314 When Guile signals an error for valid Scheme programs, it is a bug.
317 When Guile does not signal an error for invalid Scheme programs, it may
318 be a bug, unless this is explicitly documented.
321 When some part of the documentation is not clear and does not make sense
322 to you even after re-reading the section, it is a bug.
325 When you write a bug report, please make sure to include as much of the
326 information described below in the report. If you can't figure out some
327 of the items, it is not a problem, but the more information we get, the
328 more likely we can diagnose and fix the bug.
332 The version number of Guile. Without this, we won't know whether there
333 is any point in looking for the bug in the current version of Guile.
335 You can get the version number by invoking the command
340 Copyright (c) 1995, 1996, 1997, 2000, 2001, 2002, 2003, 2004,
341 2005, 2006, 2007, 2008, 2009 Free Software Foundation
342 Guile may be distributed under the terms of the GNU Lesser General
343 Public Licence. For details, see the files `COPYING.LESSER' and
344 `COPYING', which are included in the Guile distribution. There is
345 no warranty, to the extent permitted by law.
349 The type of machine you are using, and the operating system name and
350 version number. On GNU systems, you can get it with @file{uname}.
354 Linux tortoise 2.2.17 #1 Thu Dec 21 17:29:05 CET 2000 i586 unknown
358 The operands given to the @file{configure} command when Guile was
359 installed. It's often useful to augment this with the output of the
360 command @code{guile-config info}.
363 A complete list of any modifications you have made to the Guile source.
364 (We may not have time to investigate the bug unless it happens in an
365 unmodified Guile. But if you've made modifications and you don't tell
366 us, you are sending us on a wild goose chase.)
368 Be precise about these changes. A description in English is not
369 enough---send a context diff for them.
371 Adding files of your own, or porting to another machine, is a
372 modification of the source.
375 Details of any other deviations from the standard procedure for
379 The complete text of any source files needed to reproduce the bug.
381 If you can tell us a way to cause the problem without loading any source
382 files, please do so. This makes it much easier to debug. If you do
383 need files, make sure you arrange for us to see their exact contents.
386 The precise Guile invocation command line we need to type to reproduce
390 A description of what behavior you observe that you believe is
391 incorrect. For example, "The Guile process gets a fatal signal," or,
392 "The resulting output is as follows, which I think is wrong."
394 Of course, if the bug is that Guile gets a fatal signal, then one can't
395 miss it. But if the bug is incorrect results, the maintainer might fail
396 to notice what is wrong. Why leave it to chance?
398 If the manifestation of the bug is a Guile error message, it is
399 important to report the precise text of the error message, and a
400 backtrace showing how the Scheme program arrived at the error.
402 This can be done using the procedure @code{backtrace} in the REPL.
405 Check whether any programs you have loaded into Guile, including your
406 @file{.guile} file, set any variables that may affect the functioning of
407 Guile. Also, see whether the problem happens in a freshly started Guile
408 without loading your @file{.guile} file (start Guile with the @code{-q}
409 switch to prevent loading the init file). If the problem does
410 @emph{not} occur then, you must report the precise contents of any
411 programs that you must load into Guile in order to cause the problem to
415 If the problem does depend on an init file or other Scheme programs that
416 are not part of the standard Guile distribution, then you should make
417 sure it is not a bug in those programs by complaining to their
418 maintainers first. After they verify that they are using Guile in a way
419 that is supposed to work, they should report the bug.
422 If you wish to mention something in the Guile source, show the line of
423 code with a few lines of context. Don't just give a line number.
425 The line numbers in the development sources might not match those in your
426 sources. It would take extra work for the maintainers to determine what
427 code is in your version at a given line number, and we could not be
431 Additional information from a C debugger such as GDB might enable
432 someone to find a problem on a machine which he does not have available.
433 If you don't know how to use GDB, please read the GDB manual---it is not
434 very long, and using GDB is easy. You can find the GDB distribution,
435 including the GDB manual in online form, in most of the same places you
436 can find the Guile distribution. To run Guile under GDB, you should
437 switch to the @file{libguile} subdirectory in which Guile was compiled, then
438 do @code{gdb guile} or @code{gdb .libs/guile} (if using GNU Libtool).
440 However, you need to think when you collect the additional information
441 if you want it to show what causes the bug.
443 For example, many people send just a backtrace, but that is not very
444 useful by itself. A simple backtrace with arguments often conveys
445 little about what is happening inside Guile, because most of the
446 arguments listed in the backtrace are pointers to Scheme objects. The
447 numeric values of these pointers have no significance whatever; all that
448 matters is the contents of the objects they point to (and most of the
449 contents are themselves pointers).
454 @c TeX-master: "guile.texi"