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 return scm_str2string (getenv ("HOSTNAME"));
200 inner_main (void *data, int argc, char **argv)
202 scm_c_define_gsubr ("my-hostname", 0, 0, 0, my_hostname);
203 scm_shell (argc, argv);
207 main (int argc, char **argv)
209 scm_boot_guile (argc, argv, inner_main, 0);
210 return 0; /* never reached */
214 When Guile is correctly installed on your system, the above program
215 can be compiled and linked like this:
218 $ gcc -o simple-guile simple-guile.c -lguile
221 When it is run, it behaves just like the @code{guile} program except
222 that you can also call the new @code{my-hostname} function.
232 @node Writing Guile Extensions
233 @subsection Writing Guile Extensions
235 You can link Guile into your program and make Scheme available to the
236 users of your program. You can also link your library into Guile and
237 make its functionality available to all users of Guile.
239 A library that is linked into Guile is called an @dfn{extensions}, but
240 it really just is an ordinary object library.
242 The following example shows how to write a simple extension for Guile
243 that makes the @code{j0} function available to Scheme code.
247 #include <libguile.h>
252 return scm_make_real (j0 (scm_num2dbl (x, "j0")));
258 scm_c_define_gsubr ("j0", 1, 0, 0, j0_wrapper);
262 This C source file needs to be compiled into a shared library. Here is
263 how to do it on GNU/Linux:
266 gcc -shared -o libguile-bessel.so -fPIC bessel.c
269 For creating shared libraries portably, we recommend the use of GNU
270 Libtool (@pxref{Top, , Introduction, libtool, GNU Libtool}).
272 A shared library can be loaded into a running Guile process with the
273 function @code{load-extension}. The @code{j0} is then immediately
278 guile> (load-extension "./libguile-bessel" "init_bessel")
284 @node Using the Guile Module System
285 @subsection Using the Guile Module System
287 Guile has support for dividing a program into @dfn{modules}. By using
288 modules, you can group related code together and manage the
289 composition of complete programs from largely independent parts.
291 (Although the module system implementation is in flux, feel free to use it
292 anyway. Guile will provide reasonable backwards compatibility.)
294 Details on the module system beyond this introductory material can be found in
299 * Writing new Modules::
300 * Putting Extensions into Modules::
305 @subsubsection Using Modules
307 Guile comes with a lot of useful modules, for example for string
308 processing or command line parsing. Additionally, there exist many
309 Guile modules written by other Guile hackers, but which have to be
312 Here is a sample interactive session that shows how to use the
313 @code{(ice-9 popen)} module which provides the means for communicating
314 with other processes over pipes together with the @code{(ice-9
315 rdelim)} module that provides the function @code{read-line}.
319 guile> (use-modules (ice-9 popen))
320 guile> (use-modules (ice-9 rdelim))
321 guile> (define p (open-input-pipe "ls -l"))
325 "drwxr-sr-x 2 mgrabmue mgrabmue 1024 Mar 29 19:57 CVS"
328 @node Writing new Modules
329 @subsubsection Writing new Modules
331 You can create new modules using the syntactic form
332 @code{define-module}. All definitions following this form until the
333 next @code{define-module} are placed into the new module.
335 One module is usually placed into one file, and that file is installed
336 in a location where Guile can automatically find it. The following
337 session shows a simple example.
340 $ cat /usr/local/share/guile/foo/bar.scm
342 (define-module (foo bar))
345 (define (frob x) (* 2 x))
348 guile> (use-modules (foo bar))
353 @node Putting Extensions into Modules
354 @subsubsection Putting Extensions into Modules
356 In addition to Scheme code you can also put things that are defined in
359 You do this by writing a small Scheme file that defines the module and
360 call @code{load-extension} directly in the body of the module.
363 $ cat /usr/local/share/guile/math/bessel.scm
365 (define-module (math bessel))
368 (load-extension "libguile-bessel" "init_bessel")
370 $ file /usr/local/lib/libguile-bessel.so
371 @dots{} ELF 32-bit LSB shared object @dots{}
373 guile> (use-modules (math bessel))
378 There is also a way to manipulate the module system from C but only
379 Scheme files can be autoloaded. Thus, we recommend that you define
380 your modules in Scheme.
382 @node Discouraged and Deprecated
383 @section Discouraged and Deprecated
385 From time to time functions and other features of Guile become
386 obsolete. Guile has some mechanisms in place that can help you cope
389 Guile has two levels of obsoleteness: things can be @emph{deprecated},
390 meaning that their use is considered harmful and should be avoided,
391 even in old code; or they can be merely @emph{discouraged}, meaning
392 that they are fine in and of themselves, but that there are better
393 alternatives that should be used in new code.
395 When you use a feature that is deprecated, you will likely get a
396 warning message at run-time. Also, deprecated features are not ready
397 for production use: they might be very slow. When something is merely
398 discouraged, it performs normally and you wont get any messages at
401 The primary source for information about just what things are
402 discouraged or deprecated in a given release is the file
403 @file{NEWS}. That file also documents what you should use instead
404 of the obsoleted things.
406 The file @file{README} contains instructions on how to control the
407 inclusion or removal of the deprecated and/or discouraged features
408 from the public API of Guile, and how to control the warning messages
409 for deprecated features.
411 The idea behind those mechanisms is that normally all deprecated and
412 discouraged features are available, but that you can omit them on
413 purpose to check whether your code still relies on them.
416 @section Reporting Bugs
418 Any problems with the installation should be reported to
419 @email{bug-guile@@gnu.org}.
421 Whenever you have found a bug in Guile you are encouraged to report it
422 to the Guile developers, so they can fix it. They may also be able to
423 suggest workarounds when it is not possible for you to apply the bug-fix
424 or install a new version of Guile yourself.
426 Before sending in bug reports, please check with the following list that
427 you really have found a bug.
431 Whenever documentation and actual behavior differ, you have certainly
432 found a bug, either in the documentation or in the program.
435 When Guile crashes, it is a bug.
438 When Guile hangs or takes forever to complete a task, it is a bug.
441 When calculations produce wrong results, it is a bug.
444 When Guile signals an error for valid Scheme programs, it is a bug.
447 When Guile does not signal an error for invalid Scheme programs, it may
448 be a bug, unless this is explicitly documented.
451 When some part of the documentation is not clear and does not make sense
452 to you even after re-reading the section, it is a bug.
455 When you write a bug report, please make sure to include as much of the
456 information described below in the report. If you can't figure out some
457 of the items, it is not a problem, but the more information we get, the
458 more likely we can diagnose and fix the bug.
462 The version number of Guile. Without this, we won't know whether there
463 is any point in looking for the bug in the current version of Guile.
465 You can get the version number by invoking the command
470 Copyright (c) 1995, 1996, 1997, 2000, 2006 Free Software Foundation
471 Guile may be distributed under the terms of the GNU General Public License;
472 certain other uses are permitted as well. For details, see the file
473 `COPYING', which is included in the Guile distribution.
474 There is no warranty, to the extent permitted by law.
478 The type of machine you are using, and the operating system name and
479 version number. On GNU systems, you can get it with @file{uname}.
483 Linux tortoise 2.2.17 #1 Thu Dec 21 17:29:05 CET 2000 i586 unknown
487 The operands given to the @file{configure} command when Guile was
488 installed. It's often useful to augment this with the output of the
489 command @code{guile-config info}.
492 A complete list of any modifications you have made to the Guile source.
493 (We may not have time to investigate the bug unless it happens in an
494 unmodified Guile. But if you've made modifications and you don't tell
495 us, you are sending us on a wild goose chase.)
497 Be precise about these changes. A description in English is not
498 enough---send a context diff for them.
500 Adding files of your own, or porting to another machine, is a
501 modification of the source.
504 Details of any other deviations from the standard procedure for
508 The complete text of any source files needed to reproduce the bug.
510 If you can tell us a way to cause the problem without loading any source
511 files, please do so. This makes it much easier to debug. If you do
512 need files, make sure you arrange for us to see their exact contents.
515 The precise Guile invocation command line we need to type to reproduce
519 A description of what behavior you observe that you believe is
520 incorrect. For example, "The Guile process gets a fatal signal," or,
521 "The resulting output is as follows, which I think is wrong."
523 Of course, if the bug is that Guile gets a fatal signal, then one can't
524 miss it. But if the bug is incorrect results, the maintainer might fail
525 to notice what is wrong. Why leave it to chance?
527 If the manifestation of the bug is a Guile error message, it is
528 important to report the precise text of the error message, and a
529 backtrace showing how the Scheme program arrived at the error.
531 This can be done using the procedure @code{backtrace} in the REPL.
534 Check whether any programs you have loaded into Guile, including your
535 @file{.guile} file, set any variables that may affect the functioning of
536 Guile. Also, see whether the problem happens in a freshly started Guile
537 without loading your @file{.guile} file (start Guile with the @code{-q}
538 switch to prevent loading the init file). If the problem does
539 @emph{not} occur then, you must report the precise contents of any
540 programs that you must load into Guile in order to cause the problem to
544 If the problem does depend on an init file or other Scheme programs that
545 are not part of the standard Guile distribution, then you should make
546 sure it is not a bug in those programs by complaining to their
547 maintainers first. After they verify that they are using Guile in a way
548 that is supposed to work, they should report the bug.
551 If you wish to mention something in the Guile source, show the line of
552 code with a few lines of context. Don't just give a line number.
554 The line numbers in the development sources might not match those in your
555 sources. It would take extra work for the maintainers to determine what
556 code is in your version at a given line number, and we could not be
560 Additional information from a C debugger such as GDB might enable
561 someone to find a problem on a machine which he does not have available.
562 If you don't know how to use GDB, please read the GDB manual---it is not
563 very long, and using GDB is easy. You can find the GDB distribution,
564 including the GDB manual in online form, in most of the same places you
565 can find the Guile distribution. To run Guile under GDB, you should
566 switch to the @file{libguile} subdirectory in which Guile was compiled, then
567 do @code{gdb guile} or @code{gdb .libs/guile} (if using GNU Libtool).
569 However, you need to think when you collect the additional information
570 if you want it to show what causes the bug.
572 For example, many people send just a backtrace, but that is not very
573 useful by itself. A simple backtrace with arguments often conveys
574 little about what is happening inside Guile, because most of the
575 arguments listed in the backtrace are pointers to Scheme objects. The
576 numeric values of these pointers have no significance whatever; all that
577 matters is the contents of the objects they point to (and most of the
578 contents are themselves pointers).
584 @c TeX-master: "guile.texi"