2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006
4 @c Free Software Foundation, Inc.
5 @c See the file guile.texi for copying conditions.
7 @node Introduction to Guile
8 @chapter Introduction to Guile
12 * Obtaining and Installing Guile::
14 * Discouraged and Deprecated::
19 @section What is Guile?
21 Guile is an interpreter for the Scheme programming language, packaged
22 for use in a wide variety of environments. Guile implements Scheme as
30 Report on the Algorithmic Language Scheme (usually known as @acronym{R5RS}),
31 providing clean and general data and control structures. Guile goes
32 beyond the rather austere language presented in @acronym{R5RS}, extending it with
33 a module system, full access to @acronym{POSIX} system calls, networking support,
34 multiple threads, dynamic linking, a foreign function call interface,
35 powerful string processing, and many other features needed for
36 programming in the real world.
38 Like a shell, Guile can run interactively, reading expressions from the
39 user, evaluating them, and displaying the results, or as a script
40 interpreter, reading and executing Scheme code from a file. However,
41 Guile is also packaged as an object library, allowing other applications
42 to easily incorporate a complete Scheme interpreter. An application can
43 then use Guile as an extension language, a clean and powerful configuration
44 language, or as multi-purpose ``glue'', connecting primitives provided
45 by the application. It is easy to call Scheme code from C code and vice
46 versa, giving the application designer full control of how and when to
47 invoke the interpreter. Applications can add new functions, data types,
48 control structures, and even syntax to Guile, creating a domain-specific
49 language tailored to the task at hand, but based on a robust language
52 Guile's module system allows one to break up a large program into
53 manageable sections with well-defined interfaces between them.
54 Modules may contain a mixture of interpreted and compiled code; Guile
55 can use either static or dynamic linking to incorporate compiled code.
56 Modules also encourage developers to package up useful collections of
57 routines for general distribution; as of this writing, one can find
58 Emacs interfaces, database access routines, compilers, @acronym{GUI}
59 toolkit interfaces, and @acronym{HTTP} client functions, among others.
61 In the future, we hope to expand Guile to support other languages like
62 Tcl and Perl by translating them to Scheme code. This means that users
63 can program applications which use Guile in the language of their
64 choice, rather than having the tastes of the application's author
67 @node Obtaining and Installing Guile
68 @section Obtaining and Installing Guile
70 Guile can be obtained from the main GNU archive site
71 @url{ftp://ftp.gnu.org} or any of its mirrors. The file will be named
72 guile-version.tar.gz. The current version is @value{VERSION}, so the
73 file you should grab is:
75 @url{ftp://ftp.gnu.org/pub/gnu/guile-@value{VERSION}.tar.gz}
77 To unbundle Guile use the instruction
80 zcat guile-@value{VERSION}.tar.gz | tar xvf -
83 which will create a directory called @file{guile-@value{VERSION}} with
84 all the sources. You can look at the file @file{INSTALL} for detailed
85 instructions on how to build and install Guile, but you should be able
89 cd guile-@value{VERSION}
95 This will install the Guile executable @file{guile}, the Guile library
96 @file{-lguile} and various associated header files and support
97 libraries. It will also install the Guile tutorial and reference
100 @c [[include instructions for getting R5RS]]
102 Since this manual frequently refers to the Scheme ``standard'', also
103 known as R5RS, or the
105 ``Revised$^5$ Report on the Algorithmic Language Scheme'',
108 ``Revised^5 Report on the Algorithmic Language Scheme'',
110 we have included the report in the Guile distribution;
111 @xref{Top, , Introduction, r5rs, Revised(5) Report on the Algorithmic
113 This will also be installed in your info directory.
116 @section A Whirlwind Tour
118 This chapter presents a quick tour of all the ways that Guile can be
119 used. There are additional examples in the @file{examples/}
120 directory in the Guile source distribution.
122 The following examples assume that Guile has been installed in
126 * Running Guile Interactively::
127 * Running Guile Scripts::
128 * Linking Guile into Programs::
129 * Writing Guile Extensions::
130 * Using the Guile Module System::
134 @node Running Guile Interactively
135 @subsection Running Guile Interactively
137 In its simplest form, Guile acts as an interactive interpreter for the
138 Scheme programming language, reading and evaluating Scheme expressions
139 the user enters from the terminal. Here is a sample interaction between
140 Guile and a user; the user's input appears after the @code{$} and
141 @code{guile>} prompts:
145 guile> (+ 1 2 3) ; add some numbers
147 guile> (define (factorial n) ; define a function
148 (if (zero? n) 1 (* n (factorial (- n 1)))))
149 guile> (factorial 20)
151 guile> (getpwnam "jimb") ; find my entry in /etc/passwd
152 #("jimb" ".0krIpK2VqNbU" 4008 10 "Jim Blandy" "/u/jimb"
153 "/usr/local/bin/bash")
159 @node Running Guile Scripts
160 @subsection Running Guile Scripts
162 Like AWK, Perl, or any shell, Guile can interpret script files. A Guile
163 script is simply a file of Scheme code with some extra information at
164 the beginning which tells the operating system how to invoke Guile, and
165 then tells Guile how to handle the Scheme code.
167 Here is a trivial Guile script, for more details @xref{Guile Scripting}.
170 #!/usr/local/bin/guile -s
172 (display "Hello, world!")
177 @node Linking Guile into Programs
178 @subsection Linking Guile into Programs
180 The Guile interpreter is available as an object library, to be linked
181 into applications using Scheme as a configuration or extension
184 Here is @file{simple-guile.c}, source code for a program that will
185 produce a complete Guile interpreter. In addition to all usual
186 functions provided by Guile, it will also offer the function
191 #include <libguile.h>
196 char *s = getenv ("HOSTNAME");
200 return scm_from_locale_string (s);
204 inner_main (void *data, int argc, char **argv)
206 scm_c_define_gsubr ("my-hostname", 0, 0, 0, my_hostname);
207 scm_shell (argc, argv);
211 main (int argc, char **argv)
213 scm_boot_guile (argc, argv, inner_main, 0);
214 return 0; /* never reached */
218 When Guile is correctly installed on your system, the above program
219 can be compiled and linked like this:
222 $ gcc -o simple-guile simple-guile.c -lguile
225 When it is run, it behaves just like the @code{guile} program except
226 that you can also call the new @code{my-hostname} function.
236 @node Writing Guile Extensions
237 @subsection Writing Guile Extensions
239 You can link Guile into your program and make Scheme available to the
240 users of your program. You can also link your library into Guile and
241 make its functionality available to all users of Guile.
243 A library that is linked into Guile is called an @dfn{extensions}, but
244 it really just is an ordinary object library.
246 The following example shows how to write a simple extension for Guile
247 that makes the @code{j0} function available to Scheme code.
251 #include <libguile.h>
256 return scm_make_real (j0 (scm_num2dbl (x, "j0")));
262 scm_c_define_gsubr ("j0", 1, 0, 0, j0_wrapper);
266 This C source file needs to be compiled into a shared library. Here is
267 how to do it on GNU/Linux:
270 gcc -shared -o libguile-bessel.so -fPIC bessel.c
273 For creating shared libraries portably, we recommend the use of GNU
274 Libtool (@pxref{Top, , Introduction, libtool, GNU Libtool}).
276 A shared library can be loaded into a running Guile process with the
277 function @code{load-extension}. The @code{j0} is then immediately
282 guile> (load-extension "./libguile-bessel" "init_bessel")
288 @node Using the Guile Module System
289 @subsection Using the Guile Module System
291 Guile has support for dividing a program into @dfn{modules}. By using
292 modules, you can group related code together and manage the
293 composition of complete programs from largely independent parts.
295 (Although the module system implementation is in flux, feel free to use it
296 anyway. Guile will provide reasonable backwards compatibility.)
298 Details on the module system beyond this introductory material can be found in
303 * Writing new Modules::
304 * Putting Extensions into Modules::
309 @subsubsection Using Modules
311 Guile comes with a lot of useful modules, for example for string
312 processing or command line parsing. Additionally, there exist many
313 Guile modules written by other Guile hackers, but which have to be
316 Here is a sample interactive session that shows how to use the
317 @code{(ice-9 popen)} module which provides the means for communicating
318 with other processes over pipes together with the @code{(ice-9
319 rdelim)} module that provides the function @code{read-line}.
323 guile> (use-modules (ice-9 popen))
324 guile> (use-modules (ice-9 rdelim))
325 guile> (define p (open-input-pipe "ls -l"))
329 "drwxr-sr-x 2 mgrabmue mgrabmue 1024 Mar 29 19:57 CVS"
332 @node Writing new Modules
333 @subsubsection Writing new Modules
335 You can create new modules using the syntactic form
336 @code{define-module}. All definitions following this form until the
337 next @code{define-module} are placed into the new module.
339 One module is usually placed into one file, and that file is installed
340 in a location where Guile can automatically find it. The following
341 session shows a simple example.
344 $ cat /usr/local/share/guile/foo/bar.scm
346 (define-module (foo bar))
349 (define (frob x) (* 2 x))
352 guile> (use-modules (foo bar))
357 @node Putting Extensions into Modules
358 @subsubsection Putting Extensions into Modules
360 In addition to Scheme code you can also put things that are defined in
363 You do this by writing a small Scheme file that defines the module and
364 call @code{load-extension} directly in the body of the module.
367 $ cat /usr/local/share/guile/math/bessel.scm
369 (define-module (math bessel))
372 (load-extension "libguile-bessel" "init_bessel")
374 $ file /usr/local/lib/libguile-bessel.so
375 @dots{} ELF 32-bit LSB shared object @dots{}
377 guile> (use-modules (math bessel))
382 There is also a way to manipulate the module system from C but only
383 Scheme files can be autoloaded. Thus, we recommend that you define
384 your modules in Scheme.
386 @node Discouraged and Deprecated
387 @section Discouraged and Deprecated
389 From time to time functions and other features of Guile become
390 obsolete. Guile has some mechanisms in place that can help you cope
393 Guile has two levels of obsoleteness: things can be @emph{deprecated},
394 meaning that their use is considered harmful and should be avoided,
395 even in old code; or they can be merely @emph{discouraged}, meaning
396 that they are fine in and of themselves, but that there are better
397 alternatives that should be used in new code.
399 When you use a feature that is deprecated, you will likely get a
400 warning message at run-time. Also, deprecated features are not ready
401 for production use: they might be very slow. When something is merely
402 discouraged, it performs normally and you wont get any messages at
405 The primary source for information about just what things are
406 discouraged or deprecated in a given release is the file
407 @file{NEWS}. That file also documents what you should use instead
408 of the obsoleted things.
410 The file @file{README} contains instructions on how to control the
411 inclusion or removal of the deprecated and/or discouraged features
412 from the public API of Guile, and how to control the warning messages
413 for deprecated features.
415 The idea behind those mechanisms is that normally all deprecated and
416 discouraged features are available, but that you can omit them on
417 purpose to check whether your code still relies on them.
420 @section Reporting Bugs
422 Any problems with the installation should be reported to
423 @email{bug-guile@@gnu.org}.
425 Whenever you have found a bug in Guile you are encouraged to report it
426 to the Guile developers, so they can fix it. They may also be able to
427 suggest workarounds when it is not possible for you to apply the bug-fix
428 or install a new version of Guile yourself.
430 Before sending in bug reports, please check with the following list that
431 you really have found a bug.
435 Whenever documentation and actual behavior differ, you have certainly
436 found a bug, either in the documentation or in the program.
439 When Guile crashes, it is a bug.
442 When Guile hangs or takes forever to complete a task, it is a bug.
445 When calculations produce wrong results, it is a bug.
448 When Guile signals an error for valid Scheme programs, it is a bug.
451 When Guile does not signal an error for invalid Scheme programs, it may
452 be a bug, unless this is explicitly documented.
455 When some part of the documentation is not clear and does not make sense
456 to you even after re-reading the section, it is a bug.
459 When you write a bug report, please make sure to include as much of the
460 information described below in the report. If you can't figure out some
461 of the items, it is not a problem, but the more information we get, the
462 more likely we can diagnose and fix the bug.
466 The version number of Guile. Without this, we won't know whether there
467 is any point in looking for the bug in the current version of Guile.
469 You can get the version number by invoking the command
474 Copyright (c) 1995, 1996, 1997, 2000, 2006 Free Software Foundation
475 Guile may be distributed under the terms of the GNU General Public License;
476 certain other uses are permitted as well. For details, see the file
477 `COPYING', which is included in the Guile distribution.
478 There is no warranty, to the extent permitted by law.
482 The type of machine you are using, and the operating system name and
483 version number. On GNU systems, you can get it with @file{uname}.
487 Linux tortoise 2.2.17 #1 Thu Dec 21 17:29:05 CET 2000 i586 unknown
491 The operands given to the @file{configure} command when Guile was
492 installed. It's often useful to augment this with the output of the
493 command @code{guile-config info}.
496 A complete list of any modifications you have made to the Guile source.
497 (We may not have time to investigate the bug unless it happens in an
498 unmodified Guile. But if you've made modifications and you don't tell
499 us, you are sending us on a wild goose chase.)
501 Be precise about these changes. A description in English is not
502 enough---send a context diff for them.
504 Adding files of your own, or porting to another machine, is a
505 modification of the source.
508 Details of any other deviations from the standard procedure for
512 The complete text of any source files needed to reproduce the bug.
514 If you can tell us a way to cause the problem without loading any source
515 files, please do so. This makes it much easier to debug. If you do
516 need files, make sure you arrange for us to see their exact contents.
519 The precise Guile invocation command line we need to type to reproduce
523 A description of what behavior you observe that you believe is
524 incorrect. For example, "The Guile process gets a fatal signal," or,
525 "The resulting output is as follows, which I think is wrong."
527 Of course, if the bug is that Guile gets a fatal signal, then one can't
528 miss it. But if the bug is incorrect results, the maintainer might fail
529 to notice what is wrong. Why leave it to chance?
531 If the manifestation of the bug is a Guile error message, it is
532 important to report the precise text of the error message, and a
533 backtrace showing how the Scheme program arrived at the error.
535 This can be done using the procedure @code{backtrace} in the REPL.
538 Check whether any programs you have loaded into Guile, including your
539 @file{.guile} file, set any variables that may affect the functioning of
540 Guile. Also, see whether the problem happens in a freshly started Guile
541 without loading your @file{.guile} file (start Guile with the @code{-q}
542 switch to prevent loading the init file). If the problem does
543 @emph{not} occur then, you must report the precise contents of any
544 programs that you must load into Guile in order to cause the problem to
548 If the problem does depend on an init file or other Scheme programs that
549 are not part of the standard Guile distribution, then you should make
550 sure it is not a bug in those programs by complaining to their
551 maintainers first. After they verify that they are using Guile in a way
552 that is supposed to work, they should report the bug.
555 If you wish to mention something in the Guile source, show the line of
556 code with a few lines of context. Don't just give a line number.
558 The line numbers in the development sources might not match those in your
559 sources. It would take extra work for the maintainers to determine what
560 code is in your version at a given line number, and we could not be
564 Additional information from a C debugger such as GDB might enable
565 someone to find a problem on a machine which he does not have available.
566 If you don't know how to use GDB, please read the GDB manual---it is not
567 very long, and using GDB is easy. You can find the GDB distribution,
568 including the GDB manual in online form, in most of the same places you
569 can find the Guile distribution. To run Guile under GDB, you should
570 switch to the @file{libguile} subdirectory in which Guile was compiled, then
571 do @code{gdb guile} or @code{gdb .libs/guile} (if using GNU Libtool).
573 However, you need to think when you collect the additional information
574 if you want it to show what causes the bug.
576 For example, many people send just a backtrace, but that is not very
577 useful by itself. A simple backtrace with arguments often conveys
578 little about what is happening inside Guile, because most of the
579 arguments listed in the backtrace are pointers to Scheme objects. The
580 numeric values of these pointers have no significance whatever; all that
581 matters is the contents of the objects they point to (and most of the
582 contents are themselves pointers).
588 @c TeX-master: "guile.texi"