2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004
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::
18 @section What is Guile?
20 Guile is an interpreter for the Scheme programming language, packaged
21 for use in a wide variety of environments. Guile implements Scheme as
29 Report on the Algorithmic Language Scheme (usually known as @acronym{R5RS}),
30 providing clean and general data and control structures. Guile goes
31 beyond the rather austere language presented in @acronym{R5RS}, extending it with
32 a module system, full access to @acronym{POSIX} system calls, networking support,
33 multiple threads, dynamic linking, a foreign function call interface,
34 powerful string processing, and many other features needed for
35 programming in the real world.
37 Like a shell, Guile can run interactively, reading expressions from the
38 user, evaluating them, and displaying the results, or as a script
39 interpreter, reading and executing Scheme code from a file. However,
40 Guile is also packaged as an object library, allowing other applications
41 to easily incorporate a complete Scheme interpreter. An application can
42 then use Guile as an extension language, a clean and powerful configuration
43 language, or as multi-purpose ``glue'', connecting primitives provided
44 by the application. It is easy to call Scheme code from C code and vice
45 versa, giving the application designer full control of how and when to
46 invoke the interpreter. Applications can add new functions, data types,
47 control structures, and even syntax to Guile, creating a domain-specific
48 language tailored to the task at hand, but based on a robust language
51 Guile's module system allows one to break up a large program into
52 manageable sections with well-defined interfaces between them.
53 Modules may contain a mixture of interpreted and compiled code; Guile
54 can use either static or dynamic linking to incorporate compiled code.
55 Modules also encourage developers to package up useful collections of
56 routines for general distribution; as of this writing, one can find
57 Emacs interfaces, database access routines, compilers, @acronym{GUI}
58 toolkit interfaces, and @acronym{HTTP} client functions, among others.
60 In the future, we hope to expand Guile to support other languages like
61 Tcl and Perl by translating them to Scheme code. This means that users
62 can program applications which use Guile in the language of their
63 choice, rather than having the tastes of the application's author
66 @node Obtaining and Installing Guile
67 @section Obtaining and Installing Guile
69 Guile can be obtained from the main GNU archive site
70 @url{ftp://ftp.gnu.org} or any of its mirrors. The file will be named
71 guile-version.tar.gz. The current version is @value{VERSION}, so the
72 file you should grab is:
74 @url{ftp://ftp.gnu.org/pub/gnu/guile-@value{VERSION}.tar.gz}
76 To unbundle Guile use the instruction
79 zcat guile-@value{VERSION}.tar.gz | tar xvf -
82 which will create a directory called @file{guile-@value{VERSION}} with
83 all the sources. You can look at the file @file{INSTALL} for detailed
84 instructions on how to build and install Guile, but you should be able
88 cd guile-@value{VERSION}
94 This will install the Guile executable @file{guile}, the Guile library
95 @file{-lguile} and various associated header files and support
96 libraries. It will also install the Guile tutorial and reference
99 @c [[include instructions for getting R5RS]]
101 Since this manual frequently refers to the Scheme ``standard'', also
102 known as R5RS, or the
104 ``Revised$^5$ Report on the Algorithmic Language Scheme'',
107 ``Revised^5 Report on the Algorithmic Language Scheme'',
109 we have included the report in the Guile distribution;
110 @xref{Top, , Introduction, r5rs, Revised(5) Report on the Algorithmic
112 This will also be installed in your info directory.
115 @section A Whirlwind Tour
117 This chapter presents a quick tour of all the ways that Guile can be
118 used. There are additional examples in the @file{examples/}
119 directory in the Guile source distribution.
121 The following examples assume that Guile has been installed in
125 * Running Guile Interactively::
126 * Running Guile Scripts::
127 * Linking Guile into Programs::
128 * Writing Guile Extensions::
129 * Using the Guile Module System::
133 @node Running Guile Interactively
134 @subsection Running Guile Interactively
136 In its simplest form, Guile acts as an interactive interpreter for the
137 Scheme programming language, reading and evaluating Scheme expressions
138 the user enters from the terminal. Here is a sample interaction between
139 Guile and a user; the user's input appears after the @code{$} and
140 @code{guile>} prompts:
144 guile> (+ 1 2 3) ; add some numbers
146 guile> (define (factorial n) ; define a function
147 (if (zero? n) 1 (* n (factorial (- n 1)))))
148 guile> (factorial 20)
150 guile> (getpwnam "jimb") ; find my entry in /etc/passwd
151 #("jimb" ".0krIpK2VqNbU" 4008 10 "Jim Blandy" "/u/jimb"
152 "/usr/local/bin/bash")
158 @node Running Guile Scripts
159 @subsection Running Guile Scripts
161 Like AWK, Perl, or any shell, Guile can interpret script files. A Guile
162 script is simply a file of Scheme code with some extra information at
163 the beginning which tells the operating system how to invoke Guile, and
164 then tells Guile how to handle the Scheme code.
166 Here is a trivial Guile script, for more details @xref{Guile Scripting}.
169 #!/usr/local/bin/guile -s
171 (display "Hello, world!")
176 @node Linking Guile into Programs
177 @subsection Linking Guile into Programs
179 The Guile interpreter is available as an object library, to be linked
180 into applications using Scheme as a configuration or extension
183 Here is @file{simple-guile.c}, source code for a program that will
184 produce a complete Guile interpreter. In addition to all usual
185 functions provided by Guile, it will also offer the function
190 #include <libguile.h>
195 return scm_str2string (getenv ("HOSTNAME"));
199 inner_main (void *data, int argc, char **argv)
201 scm_c_define_gsubr ("my-hostname", 0, 0, 0, my_hostname);
202 scm_shell (argc, argv);
206 main (int argc, char **argv)
208 scm_boot_guile (argc, argv, inner_main, 0);
209 return 0; /* never reached */
213 When Guile is correctly installed on your system, the above program
214 can be compiled and linked like this:
217 $ gcc -o simple-guile simple-guile.c -lguile
220 When it is run, it behaves just like the @code{guile} program except
221 that you can also call the new @code{my-hostname} function.
231 @node Writing Guile Extensions
232 @subsection Writing Guile Extensions
234 You can link Guile into your program and make Scheme available to the
235 users of your program. You can also link your library into Guile and
236 make its functionality available to all users of Guile.
238 A library that is linked into Guile is called an @dfn{extensions}, but
239 it really just is an ordinary object library.
241 The following example shows how to write a simple extension for Guile
242 that makes the @code{j0} function available to Scheme code.
246 #include <libguile.h>
251 return scm_make_real (j0 (scm_num2dbl (x, "j0")));
257 scm_c_define_gsubr ("j0", 1, 0, 0, j0_wrapper);
261 This C source file needs to be compiled into a shared library. Here is
262 how to do it on GNU/Linux:
265 gcc -shared -o libguile-bessel.so -fPIC bessel.c
268 For creating shared libraries portably, we recommend the use of
271 A shared library can be loaded into a running Guile process with the
272 function @code{load-extension}. The @code{j0} is then immediately
277 guile> (load-extension "./libguile-bessel" "init_bessel")
283 @node Using the Guile Module System
284 @subsection Using the Guile Module System
286 Guile has support for dividing a program into @dfn{modules}. By using
287 modules, you can group related code together and manage the
288 composition of complete programs from largely independent parts.
290 (Although the module system implementation is in flux, feel free to use it
291 anyway. Guile will provide reasonable backwards compatibility.)
293 Details on the module system beyond this introductory material can be found in
298 * Writing new Modules::
299 * Putting Extensions into Modules::
304 @subsubsection Using Modules
306 Guile comes with a lot of useful modules, for example for string
307 processing or command line parsing. Additionally, there exist many
308 Guile modules written by other Guile hackers, but which have to be
311 Here is a sample interactive session that shows how to use the
312 @code{(ice-9 popen)} module which provides the means for communicating
313 with other processes over pipes together with the @code{(ice-9
314 rdelim)} module that provides the function @code{read-line}.
318 guile> (use-modules (ice-9 popen))
319 guile> (use-modules (ice-9 rdelim))
320 guile> (define p (open-input-pipe "ls -l"))
324 "drwxr-sr-x 2 mgrabmue mgrabmue 1024 Mar 29 19:57 CVS"
327 @node Writing new Modules
328 @subsubsection Writing new Modules
330 You can create new modules using the syntactic form
331 @code{define-module}. All definitions following this form until the
332 next @code{define-module} are placed into the new module.
334 One module is usually placed into one file, and that file is installed
335 in a location where Guile can automatically find it. The following
336 session shows a simple example.
339 $ cat /usr/local/share/guile/foo/bar.scm
341 (define-module (foo bar))
344 (define (frob x) (* 2 x))
347 guile> (use-modules (foo bar))
352 @node Putting Extensions into Modules
353 @subsubsection Putting Extensions into Modules
355 In addition to Scheme code you can also put things that are defined in
358 You do this by writing a small Scheme file that defines the module and
359 call @code{load-extension} directly in the body of the module.
362 $ cat /usr/local/share/guile/math/bessel.scm
364 (define-module (math bessel))
367 (load-extension "libguile-bessel" "init_bessel")
369 $ file /usr/local/lib/libguile-bessel.so
370 @dots{} ELF 32-bit LSB shared object @dots{}
372 guile> (use-modules (math bessel))
377 There is also a way to manipulate the module system from C but only
378 Scheme files can be autoloaded. Thus, we recommend that you define
379 your modules in Scheme.
382 @section Reporting Bugs
384 Any problems with the installation should be reported to
385 @email{bug-guile@@gnu.org}.
387 Whenever you have found a bug in Guile you are encouraged to report it
388 to the Guile developers, so they can fix it. They may also be able to
389 suggest workarounds when it is not possible for you to apply the bug-fix
390 or install a new version of Guile yourself.
392 Before sending in bug reports, please check with the following list that
393 you really have found a bug.
397 Whenever documentation and actual behavior differ, you have certainly
398 found a bug, either in the documentation or in the program.
401 When Guile crashes, it is a bug.
404 When Guile hangs or takes forever to complete a task, it is a bug.
407 When calculations produce wrong results, it is a bug.
410 When Guile signals an error for valid Scheme programs, it is a bug.
413 When Guile does not signal an error for invalid Scheme programs, it may
414 be a bug, unless this is explicitly documented.
417 When some part of the documentation is not clear and does not make sense
418 to you even after re-reading the section, it is a bug.
421 When you write a bug report, please make sure to include as much of the
422 information described below in the report. If you can't figure out some
423 of the items, it is not a problem, but the more information we get, the
424 more likely we can diagnose and fix the bug.
428 The version number of Guile. Without this, we won't know whether there
429 is any point in looking for the bug in the current version of Guile.
431 You can get the version number by invoking the command
436 Copyright (c) 1995, 1996, 1997, 2000 Free Software Foundation
437 Guile may be distributed under the terms of the GNU General Public License;
438 certain other uses are permitted as well. For details, see the file
439 `COPYING', which is included in the Guile distribution.
440 There is no warranty, to the extent permitted by law.
444 The type of machine you are using, and the operating system name and
445 version number. On GNU systems, you can get it with @file{uname}.
449 Linux tortoise 2.2.17 #1 Thu Dec 21 17:29:05 CET 2000 i586 unknown
453 The operands given to the @file{configure} command when Guile was
454 installed. It's often useful to augment this with the output of the
455 command @code{guile-config info}.
458 A complete list of any modifications you have made to the Guile source.
459 (We may not have time to investigate the bug unless it happens in an
460 unmodified Guile. But if you've made modifications and you don't tell
461 us, you are sending us on a wild goose chase.)
463 Be precise about these changes. A description in English is not
464 enough---send a context diff for them.
466 Adding files of your own, or porting to another machine, is a
467 modification of the source.
470 Details of any other deviations from the standard procedure for
474 The complete text of any source files needed to reproduce the bug.
476 If you can tell us a way to cause the problem without loading any source
477 files, please do so. This makes it much easier to debug. If you do
478 need files, make sure you arrange for us to see their exact contents.
481 The precise Guile invocation command line we need to type to reproduce
485 A description of what behavior you observe that you believe is
486 incorrect. For example, "The Guile process gets a fatal signal," or,
487 "The resulting output is as follows, which I think is wrong."
489 Of course, if the bug is that Guile gets a fatal signal, then one can't
490 miss it. But if the bug is incorrect results, the maintainer might fail
491 to notice what is wrong. Why leave it to chance?
493 If the manifestation of the bug is a Guile error message, it is
494 important to report the precise text of the error message, and a
495 backtrace showing how the Scheme program arrived at the error.
497 This can be done using the procedure @code{backtrace} in the REPL.
500 Check whether any programs you have loaded into Guile, including your
501 @file{.guile} file, set any variables that may affect the functioning of
502 Guile. Also, see whether the problem happens in a freshly started Guile
503 without loading your @file{.guile} file (start Guile with the @code{-q}
504 switch to prevent loading the init file). If the problem does
505 @emph{not} occur then, you must report the precise contents of any
506 programs that you must load into Guile in order to cause the problem to
510 If the problem does depend on an init file or other Scheme programs that
511 are not part of the standard Guile distribution, then you should make
512 sure it is not a bug in those programs by complaining to their
513 maintainers first. After they verify that they are using Guile in a way
514 that is supposed to work, they should report the bug.
517 If you wish to mention something in the Guile source, show the line of
518 code with a few lines of context. Don't just give a line number.
520 The line numbers in the development sources might not match those in your
521 sources. It would take extra work for the maintainers to determine what
522 code is in your version at a given line number, and we could not be
526 Additional information from a C debugger such as GDB might enable
527 someone to find a problem on a machine which he does not have available.
528 If you don't know how to use GDB, please read the GDB manual---it is not
529 very long, and using GDB is easy. You can find the GDB distribution,
530 including the GDB manual in online form, in most of the same places you
531 can find the Guile distribution. To run Guile under GDB, you should
532 switch to the @file{libguile} subdirectory in which Guile was compiled, then
533 do @code{gdb guile} or @code{gdb .libs/guile} (if using GNU Libtool).
535 However, you need to think when you collect the additional information
536 if you want it to show what causes the bug.
538 For example, many people send just a backtrace, but that is not very
539 useful by itself. A simple backtrace with arguments often conveys
540 little about what is happening inside Guile, because most of the
541 arguments listed in the backtrace are pointers to Scheme objects. The
542 numeric values of these pointers have no significance whatever; all that
543 matters is the contents of the objects they point to (and most of the
544 contents are themselves pointers).
550 @c TeX-master: "guile.texi"