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.
9 @chapter What is Guile?
11 Guile is an interpreter for the Scheme programming language, packaged
12 for use in a wide variety of environments. Guile implements Scheme as
20 Report on the Algorithmic Language Scheme (usually known as @acronym{R5RS}),
21 providing clean and general data and control structures. Guile goes
22 beyond the rather austere language presented in @acronym{R5RS}, extending it with
23 a module system, full access to @acronym{POSIX} system calls, networking support,
24 multiple threads, dynamic linking, a foreign function call interface,
25 powerful string processing, and many other features needed for
26 programming in the real world.
28 Like a shell, Guile can run interactively, reading expressions from the
29 user, evaluating them, and displaying the results, or as a script
30 interpreter, reading and executing Scheme code from a file. However,
31 Guile is also packaged as an object library, allowing other applications
32 to easily incorporate a complete Scheme interpreter. An application can
33 then use Guile as an extension language, a clean and powerful configuration
34 language, or as multi-purpose ``glue'', connecting primitives provided
35 by the application. It is easy to call Scheme code from C code and vice
36 versa, giving the application designer full control of how and when to
37 invoke the interpreter. Applications can add new functions, data types,
38 control structures, and even syntax to Guile, creating a domain-specific
39 language tailored to the task at hand, but based on a robust language
42 Guile's module system allows one to break up a large program into
43 manageable sections with well-defined interfaces between them.
44 Modules may contain a mixture of interpreted and compiled code; Guile
45 can use either static or dynamic linking to incorporate compiled code.
46 Modules also encourage developers to package up useful collections of
47 routines for general distribution; as of this writing, one can find
48 Emacs interfaces, database access routines, compilers, @acronym{GUI}
49 toolkit interfaces, and @acronym{HTTP} client functions, among others.
51 In the future, we hope to expand Guile to support other languages like
52 Tcl and Perl by translating them to Scheme code. This means that users
53 can program applications which use Guile in the language of their
54 choice, rather than having the tastes of the application's author
60 @chapter A Whirlwind Tour
62 This chapter presents a quick tour of all the ways that Guile can be
63 used. There are additional examples in the @file{examples/}
64 directory in the Guile source distribution.
67 * Running Guile Interactively::
69 * Linking Programs With Guile::
70 * Writing Extensions for Guile::
75 @node Running Guile Interactively
76 @section Running Guile Interactively
78 In its simplest form, Guile acts as an interactive interpreter for the
79 Scheme programming language, reading and evaluating Scheme expressions
80 the user enters from the terminal. Here is a sample interaction between
81 Guile and a user; the user's input appears after the @code{$} and
82 @code{guile>} prompts:
86 guile> (+ 1 2 3) ; add some numbers
88 guile> (define (factorial n) ; define a function
89 (if (zero? n) 1 (* n (factorial (- n 1)))))
92 guile> (getpwnam "jimb") ; find my entry in /etc/passwd
93 #("jimb" ".0krIpK2VqNbU" 4008 10 "Jim Blandy" "/u/jimb"
94 "/usr/local/bin/bash")
99 @c [[When we get a fancier read-eval-print loop, with features for bouncing
100 @c around among modules, referring to the value of the last expression,
101 @c etc. then this section will get longer.]]
105 @section Guile Scripts
107 Like AWK, Perl, or any shell, Guile can interpret script files. A Guile
108 script is simply a file of Scheme code with some extra information at
109 the beginning which tells the operating system how to invoke Guile, and
110 then tells Guile how to handle the Scheme code.
112 Before we present the details, here is a trivial Guile script:
115 #!/usr/local/bin/guile -s
117 (display "Hello, world!")
122 * The Top of a Script File:: How to start a Guile script.
123 * Scripting Examples:: Simple Guile scripts, explained.
127 @node The Top of a Script File
128 @subsection The Top of a Script File
130 The first line of a Guile script must tell the operating system to use
131 Guile to evaluate the script, and then tell Guile how to go about doing
132 that. Here is the simplest case:
137 The first two characters of the file must be @samp{#!}.
139 The operating system interprets this to mean that the rest of the line
140 is the name of an executable that can interpret the script. Guile,
141 however, interprets these characters as the beginning of a multi-line
142 comment, terminated by the characters @samp{!#} on a line by themselves.
143 (This is an extension to the syntax described in R5RS, added to support
147 Immediately after those two characters must come the full pathname to
148 the Guile interpreter. On most systems, this would be
149 @samp{/usr/local/bin/guile}.
152 Then must come a space, followed by a command-line argument to pass to
153 Guile; this should be @samp{-s}. This switch tells Guile to run a
154 script, instead of soliciting the user for input from the terminal.
155 There are more elaborate things one can do here; see @ref{The Meta
159 Follow this with a newline.
162 The second line of the script should contain only the characters
163 @samp{!#} --- just like the top of the file, but reversed. The
164 operating system never reads this far, but Guile treats this as the end
165 of the comment begun on the first line by the @samp{#!} characters.
168 The rest of the file should be a Scheme program.
172 Guile reads the program, evaluating expressions in the order that they
173 appear. Upon reaching the end of the file, Guile exits.
175 The function @code{command-line} returns the name of the script file and
176 any command-line arguments passed by the user, as a list of strings.
178 For example, consider the following script file:
180 #!/usr/local/bin/guile -s
182 (write (command-line))
186 If you put that text in a file called @file{foo} in the current
187 directory, then you could make it executable and try it out like this:
193 ("./foo" "bar" "baz")
197 As another example, here is a simple replacement for the POSIX
200 #!/usr/local/bin/guile -s
202 (for-each (lambda (s) (display s) (display " "))
203 (cdr (command-line)))
207 @deffn {Scheme Procedure} command-line
208 @deffnx {Scheme Procedure} program-arguments
209 Return a list of the command-line arguments passed to the currently
210 running program. If the program invoked Guile with the @samp{-s},
211 @samp{-c} or @samp{--} switches, these procedures ignore everything up
212 to and including those switches.
216 @node Scripting Examples
217 @subsection Scripting Examples
219 To start with, here are some examples of invoking Guile directly:
224 Run Guile interactively; @code{(command-line)} will return @*
225 @code{("/usr/local/bin/guile" "a" "b" "c")}.
227 @item guile -s /u/jimb/ex2 a b c
228 Load the file @file{/u/jimb/ex2}; @code{(command-line)} will return @*
229 @code{("/u/jimb/ex2" "a" "b" "c")}.
231 @item guile -c '(write %load-path) (newline)'
232 Write the value of the variable @code{%load-path}, print a newline,
235 @item guile -e main -s /u/jimb/ex4 foo
236 Load the file @file{/u/jimb/ex4}, and then call the function
237 @code{main}, passing it the list @code{("/u/jimb/ex4" "foo")}.
239 @item guile -l first -ds -l last -s script
240 Load the files @file{first}, @file{script}, and @file{last}, in that
241 order. The @code{-ds} switch says when to process the @code{-s}
242 switch. For a more motivated example, see the scripts below.
247 Here is a very simple Guile script:
249 #!/usr/local/bin/guile -s
251 (display "Hello, world!")
254 The first line marks the file as a Guile script. When the user invokes
255 it, the system runs @file{/usr/local/bin/guile} to interpret the script,
256 passing @code{-s}, the script's filename, and any arguments given to the
257 script as command-line arguments. When Guile sees @code{-s
258 @var{script}}, it loads @var{script}. Thus, running this program
264 Here is a script which prints the factorial of its argument:
266 #!/usr/local/bin/guile -s
270 (* n (fact (- n 1)))))
272 (display (fact (string->number (cadr (command-line)))))
282 However, suppose we want to use the definition of @code{fact} in this
283 file from another script. We can't simply @code{load} the script file,
284 and then use @code{fact}'s definition, because the script will try to
285 compute and display a factorial when we load it. To avoid this problem,
286 we might write the script this way:
289 #!/usr/local/bin/guile \
294 (* n (fact (- n 1)))))
297 (display (fact (string->number (cadr args))))
300 This version packages the actions the script should perform in a
301 function, @code{main}. This allows us to load the file purely for its
302 definitions, without any extraneous computation taking place. Then we
303 used the meta switch @code{\} and the entry point switch @code{-e} to
304 tell Guile to call @code{main} after loading the script.
307 30414093201713378043612608166064768844377641568960512000000000000
310 Suppose that we now want to write a script which computes the
311 @code{choose} function: given a set of @var{m} distinct objects,
312 @code{(choose @var{n} @var{m})} is the number of distinct subsets
313 containing @var{n} objects each. It's easy to write @code{choose} given
314 @code{fact}, so we might write the script this way:
316 #!/usr/local/bin/guile \
320 (/ (fact m) (* (fact (- m n)) (fact n))))
323 (let ((n (string->number (cadr args)))
324 (m (string->number (caddr args))))
325 (display (choose n m))
329 The command-line arguments here tell Guile to first load the file
330 @file{fact}, and then run the script, with @code{main} as the entry
331 point. In other words, the @code{choose} script can use definitions
332 made in the @code{fact} script. Here are some sample runs:
345 100891344545564193334812497256
349 @node Linking Programs With Guile
350 @section Linking Programs With Guile
352 The Guile interpreter is available as an object library, to be linked
353 into applications using Scheme as a configuration or extension
354 language. This chapter covers the mechanics of linking your program
355 with Guile on a typical POSIX system.
357 Parts III and IV of this manual describe the C functions Guile provides.
358 Furthermore, any Scheme function described in this manual as a
359 ``Primitive'' is also callable from C; see @ref{Primitives}.
361 The header file @code{<libguile.h>} provides declarations for all of
362 Guile's functions and constants. You should @code{#include} it at the
363 head of any C source file that uses identifiers described in this
364 manual. Once you've compiled your source files, you need to link them
365 against the Guile object code library, @code{libguile}.
367 On most systems, you should not need to tell the compiler and linker
368 explicitly where they can find @file{libguile.h} and @file{libguile}.
369 When Guile has been installed in a peculiar way, or when you are on a
370 peculiar system, things might not be so easy and you might need to pass
371 additional @code{-I} or @code{-L} options to the compiler. Guile
372 provides the utility program @code{guile-config} to help you find the
373 right values for these options. You would typically run
374 @code{guile-config} during the configuration phase of your program and
375 use the obtained information in the Makefile.
378 * Guile Initialization Functions:: What to call first.
379 * A Sample Guile Main Program:: Sources and makefiles.
383 @node Guile Initialization Functions
384 @subsection Guile Initialization Functions
386 To initialize Guile, you can use one of two functions. The first,
387 @code{scm_boot_guile}, is the most portable way to initialize Guile. It
388 should be used whenever you have control over the main function of your
389 program because it never returns. The second function,
390 @code{scm_init_guile}, does return and can thus be used in more
391 situations. However, @code{scm_init_guile} is not as widely available
392 as @code{scm_boot_guile} because it needs to rely on non-portable code
393 to find the stack bounds. When Guile does not know how to find these
394 bounds on your system, it will not provide @code{scm_init_guile}.
396 When you can tolerate the limits of @code{scm_boot_guile}, you should
397 use it in favor of @code{scm_init_guile} since that will make your
398 program more portable.
400 @deftypefun void scm_boot_guile (int @var{argc}, char **@var{argv}, void (*@var{main_func}) (), void *@var{closure})
401 Initialize the Guile Scheme interpreter. Then call @var{main_func},
402 passing it @var{closure}, @var{argc}, and @var{argv}. @var{main_func}
403 should do all the work of the program (initializing other packages,
404 defining application-specific functions, reading user input, and so on)
405 before returning. When @var{main_func} returns, call @code{exit (0)};
406 @code{scm_boot_guile} never returns. If you want some other exit value,
407 have @var{main_func} call exit itself.
409 @code{scm_boot_guile} arranges for the Scheme @code{command-line}
410 function to return the strings given by @var{argc} and @var{argv}. If
411 @var{main_func} modifies @var{argc} or @var{argv}, it should call
412 @code{scm_set_program_arguments} with the final list, so Scheme code
413 will know which arguments have been processed.
415 Why must the caller do all the real work from @var{main_func}? Guile's
416 garbage collector scans the stack to find all local variables that
417 reference Scheme objects. To do this, it needs to know the bounds of
418 the stack that might contain such references. Because there is no
419 portable way in C to find the base of the stack, @code{scm_boot_guile}
420 assumes that all references are above its own stack frame. If you try
421 to manipulate Scheme objects after this function returns, it's the luck
422 of the draw whether Guile's storage manager will be able to find the
423 objects you allocate. So, @code{scm_boot_guile} function exits, rather
424 than returning, to discourage you from making that mistake.
426 See @code{scm_init_guile}, below, for a function that can find the real
427 base of the stack, but not in a portable way.
430 @deftypefun void scm_init_guile ()
431 Initialize the Guile Scheme interpreter.
433 In contrast to @code{scm_boot_guile}, this function knows how to find
434 the true base of the stack and thus does not need to usurp the control
435 flow of your program. However, since finding the stack base can not be
436 done portably, this function might not be available in all installations
437 of Guile. If you can, you should use @code{scm_boot_guile} instead.
439 Note that @code{scm_init_guile} does not inform Guile about the command
440 line arguments that should be returned by the Scheme function
441 @code{command-line}. You can use @code{scm_set_program_arguments} to do
445 One common way to use Guile is to write a set of C functions which
446 perform some useful task, make them callable from Scheme, and then link
447 the program with Guile. This yields a Scheme interpreter just like
448 @code{guile}, but augmented with extra functions for some specific
449 application --- a special-purpose scripting language.
451 In this situation, the application should probably process its
452 command-line arguments in the same manner as the stock Guile
453 interpreter. To make that straightforward, Guile provides this
456 @deftypefun void scm_shell (int @var{argc}, char **@var{argv})
457 Process command-line arguments in the manner of the @code{guile}
458 executable. This includes loading the normal Guile initialization
459 files, interacting with the user or running any scripts or expressions
460 specified by @code{-s} or @code{-e} options, and then exiting.
461 @xref{Invoking Guile}, for more details.
463 Since this function does not return, you must do all
464 application-specific initialization before calling this function.
468 @node A Sample Guile Main Program
469 @subsection A Sample Guile Main Program
471 Here is @file{simple-guile.c}, source code for a @code{main} and an
472 @code{inner_main} function that will produce a complete Guile
476 /* simple-guile.c --- how to start up the Guile
477 interpreter from C code. */
479 /* Get declarations for all the scm_ functions. */
480 #include <libguile.h>
483 inner_main (void *closure, int argc, char **argv)
485 /* module initializations would go here */
486 scm_shell (argc, argv);
490 main (int argc, char **argv)
492 scm_boot_guile (argc, argv, inner_main, 0);
493 return 0; /* never reached */
497 The @code{main} function calls @code{scm_boot_guile} to initialize
498 Guile, passing it @code{inner_main}. Once @code{scm_boot_guile} is
499 ready, it invokes @code{inner_main}, which calls @code{scm_shell} to
500 process the command-line arguments in the usual way.
502 Here is a Makefile which you can use to compile the above program. It
503 uses @code{guile-config} to learn about the necessary compiler and
506 # Use GCC, if you have it installed.
509 # Tell the C compiler where to find <libguile.h>
510 CFLAGS=`guile-config compile`
512 # Tell the linker what libraries to use and where to find them.
513 LIBS=`guile-config link`
515 simple-guile: simple-guile.o
516 $@{CC@} simple-guile.o $@{LIBS@} -o simple-guile
518 simple-guile.o: simple-guile.c
519 $@{CC@} -c $@{CFLAGS@} simple-guile.c
522 If you are using the GNU Autoconf package to make your application more
523 portable, Autoconf will settle many of the details in the Makefile above
524 automatically, making it much simpler and more portable; we recommend
525 using Autoconf with Guile. Guile also provides the @code{GUILE_FLAGS}
526 macro for autoconf that performs all necessary checks. Here is a
527 @file{configure.in} file for @code{simple-guile} that uses this macro.
528 Autoconf can use as this file as template to generate a @code{configure}
529 script. In order for Autoconf to find the @code{GUILE_FLAGS} macro, you
530 will need to run @code{aclocal} first. This is not really Guile
531 specific, so you should refer to the Autoconf documentation REFFIXME
534 AC_INIT(simple-guile.c)
542 # Generate a Makefile, based on the results.
546 Here is a @code{Makefile.in} template, from which the @code{configure}
547 script produces a Makefile customized for the host system:
549 # The configure script fills in these values.
551 CFLAGS=@@GUILE_CFLAGS@@
552 LIBS=@@GUILE_LDFLAGS@@
554 simple-guile: simple-guile.o
555 $@{CC@} simple-guile.o $@{LIBS@} -o simple-guile
556 simple-guile.o: simple-guile.c
557 $@{CC@} -c $@{CFLAGS@} simple-guile.c
560 The developer should use Autoconf to generate the @file{configure}
561 script from the @file{configure.in} template, and distribute
562 @file{configure} with the application. Here's how a user might go about
563 building the application:
567 Makefile.in configure* configure.in simple-guile.c
569 creating cache ./config.cache
570 checking for gcc... (cached) gcc
571 checking whether the C compiler (gcc ) works... yes
572 checking whether the C compiler (gcc ) is a cross-compiler... no
573 checking whether we are using GNU C... (cached) yes
574 checking whether gcc accepts -g... (cached) yes
575 checking for Guile... yes
576 creating ./config.status
579 gcc -c -I/usr/local/include simple-guile.c
580 gcc simple-guile.o -L/usr/local/lib -lguile -lqthreads -lpthread -lm -o simple-guile
584 guile> (getpwnam "jimb")
585 #("jimb" "83Z7d75W2tyJQ" 4008 10 "Jim Blandy" "/u/jimb"
586 "/usr/local/bin/bash")
592 @node Writing Extensions for Guile
593 @section Writing Extensions for Guile
595 The previous sections have briefly explained how to write programs that
596 make use of an embedded Guile interpreter. But sometimes, all you want
597 to do is make new primitive procedures and data types available to the
598 Scheme programmer. Writing a new version of @code{guile} is
599 inconvenient in this case and it would in fact make the life of the
600 users of your new features needlessly hard.
602 @c [[ the following is probably a bit long-winded ]]
604 For example, suppose that there is a program @code{guile-db} that is a
605 version of Guile with additional features for accessing a database.
606 People who want to write Scheme programs that use these features would
607 have to use @code{guile-db} instead of the usual @code{guile} program.
608 Now suppose that there is also a program @code{guile-gtk} that extends
609 Guile with access to the popular Gtk+ toolkit for graphical user
610 interfaces. People who want to write GUIs in Scheme would have to use
611 @code{guile-gtk}. Now, what happens when you want to write a Scheme
612 application that uses a GUI to let the user access a database? You
613 would have to write a @emph{third} program that incorporates both the
614 database stuff and the GUI stuff. This might not be easy (because
615 @code{guile-gtk} might be a quite obscure program, say) and taking this
616 example further makes it easy to see that this approach can not work in
619 It would have been much better if both the database features and the GUI
620 feature had been provided as libraries that can just be linked with
621 @code{guile}. Guile makes it easy to do just this, and we encourage you
622 to make your extensions to Guile available as libraries whenever
625 You write the new primitive procedures and data types in the normal
626 fashion, and link them into a shared library instead of into a
627 stand-alone program. The shared library can then be loaded dynamically
631 * A Sample Guile Extension::
635 @node A Sample Guile Extension
636 @subsection A Sample Guile Extension
638 This section explains how to make the Bessel functions of the C library
639 available to Scheme. First we need to write the appropriate glue code
640 to convert the arguments and return values of the functions from Scheme
641 to C and back. Additionally, we need a function that will add them to
642 the set of Guile primitives. Because this is just an example, we will
643 only implement this for the @code{j0} function.
645 Consider the following file @file{bessel.c}.
649 #include <libguile.h>
654 return scm_make_real (j0 (scm_num2dbl (x, "j0")));
660 scm_c_define_gsubr ("j0", 1, 0, 0, j0_wrapper);
664 This C source file needs to be compiled into a shared library. Here is
665 how to do it on GNU/Linux:
668 gcc -shared -o libguile-bessel.so -fPIC bessel.c
671 For creating shared libraries portably, we recommend the use of
674 A shared library can be loaded into a running Guile process with the
675 function @code{load-extension}. In addition to the name of the
676 library to load, this function also expects the name of function from
677 that library that will be called to initialize it. For our example,
678 we are going to call the function @code{init_bessel} which will make
679 @code{j0_wrapper} available to Scheme programs with the name
680 @code{j0}. Note that we do not specify a filename extension such as
681 @file{.so} when invoking @code{load-extension}. The right extension for
682 the host platform will be provided automatically.
685 (load-extension "libguile-bessel" "init_bessel")
687 @result{} 0.223890779141236
690 For this to work, @code{load-extension} must be able to find
691 @file{libguile-bessel}, of course. It will look in the places that
692 are usual for your operating system, and it will additionally look
693 into the directories listed in the @code{LTDL_LIBRARY_PATH}
694 environment variable.
696 To see how these Guile extensions via shared libraries relate to the
697 module system, see below @xref{Intro to Modules and Extensions}.
701 @section Guile Modules
703 Guile has support for dividing a program into @dfn{modules}. By using
704 modules, you can group related code together and manage the
705 composition of complete programs from largely independent parts.
707 (Although the module system implementation is in flux, feel free to use it
708 anyway. Guile will provide reasonable backwards compatibility.)
710 Details on the module system beyond this introductory material can be found in
714 * Intro to Using Guile Modules::
715 * Intro to Writing New Modules::
716 * Intro to Modules and Extensions::
720 @node Intro to Using Guile Modules
721 @subsection Intro to Using Existing Modules
723 Guile comes with a lot of useful modules, for example for string
724 processing or command line parsing. Additionally, there exist many
725 Guile modules written by other Guile hackers, but which have to be
728 Existing modules have to be placed in places where Guile looks for them
729 by default or in colon-separated directories in the environment variable
730 @code{GUILE_LOAD_PATH}. When this variable is set, those directories
731 are searched first, then the the default. The following command
732 shows the complete list of directories searched:
735 guile -c '(write %load-path) (newline)'
738 Suppose you want to use the procedures and variables exported by the
739 module @code{(ice-9 popen)}, which provides the means for communicating
740 with other processes over pipes. Add the following line to your
741 currently running Guile REPL or the top of your script file.
744 (use-modules (ice-9 popen))
747 This will load the module and make the procedures exported by
748 @code{(ice-9 popen)} automatically available. The next step could be
749 to open a pipe to @file{ls} and read the contents of the current
750 directory, one line at a time. For the latter, we use the function
751 @code{read-line}, which can be found in the module @code{(ice-9
752 rdelim)}, so we use that module as well.
755 (use-modules (ice-9 rdelim))
756 (define p (open-input-pipe "ls -l"))
762 "drwxr-sr-x 2 mgrabmue mgrabmue 1024 Mar 29 19:57 CVS"
765 The macro @code{use-modules} can take any number of modules to use.
766 Therefore, we could have written the two @code{use-modules} statements
770 (use-modules (ice-9 popen) (ice-9 rdelim))
773 @node Intro to Writing New Modules
774 @subsection Intro to Writing New Modules
776 Of course it is possible to write modules yourself. Using modules for
777 structuring your programs makes them more readable and lets you
778 distribute them more easily. Also, explicitly defining the procedures
779 and variables which are exported from a module adds documentation to the
780 source and specifies the interface a module provides.
782 In Guile, you can create new modules and switch to existing modules in
783 order to add bindings to them using the syntactic form
784 @code{define-module}.
787 (define-module (foo bar))
792 Will create the module @code{(foo bar)}.@footnote{It is only convention
793 that the module names in this section have two elements. One or more
794 than two elements are perfectly fine, such as @code{(foo)} or @code{(foo
795 bar braz)}} All definitions following this statement will add bindings
796 to the module @code{(foo bar)}, and these bindings will not be visible
797 outside of the module. To make the bindings accessible to other
798 modules, you have to export them explicitly using one of the following
803 Export them with the @code{export} form:
809 Include them into the @code{define-module} form with the keyword
812 (define-module (foo bar)
817 Change the definition of @code{frob} to use @code{define-public}, which
818 is a combination of @code{define} and @code{export}.
820 (define-public (frob x) x)
824 After exporting, other modules can access the exported items simply by
825 using @code{use-modules} to load the module @code{(foo bar)}.
828 @node Intro to Modules and Extensions
829 @subsection Intro to Modules and Extensions
831 In addition to Scheme code you can also put things that are defined in
834 You do this by writing a small Scheme file that defines the module.
835 That Scheme file in turn invokes @code{load-extension} to make the
836 features defined in C available. This works since all definitions
837 made by @code{scm_c_define_gsubr} etc. go into the @emph{current
838 module} and @code{define-module} causes the newly defined module to be
839 current while the code that follows it is executed.
841 Suppose we want to put the Bessel function @code{j0} from the example
842 extension into a module called @code{(math bessel)}. We would have to
843 write a Scheme file with this contents
846 (define-module (math bessel))
850 (load-extension "libguile-bessel" "init_bessel")
853 This file should of course be saved in the right place for
854 autoloading, for example as
855 @file{/usr/local/share/guile/math/bessel.scm}.
857 When @code{init_bessel} is called, the new @code{(math bessel)} module
858 is the current one. Thus, the call to @code{scm_c_define_gsubr} will
859 put the new definition for @code{j0} into it, just as we want it.
861 The definitions made in the C code are not automatically exported from
862 a module. You need to explicitly list the ones you want to export in
863 @code{export} statements or with the @code{:export} option of
864 @code{define-module}.
866 There is also a way to manipulate the module system from C but only
867 Scheme files can be autoloaded. Thus, we recommend that you define
868 your modules in Scheme.
872 @node Obtaining and Installing Guile
873 @chapter Obtaining and Installing Guile
875 Here is the information you will need to get and install Guile and extra
876 packages and documentation you might need or find interesting.
879 * The Basic Guile Package::
880 * Packages not shipped with Guile::
884 @node The Basic Guile Package
885 @section The Basic Guile Package
887 Guile can be obtained from the main GNU archive site
888 @url{ftp://ftp.gnu.org} or any of its mirrors. The file
889 will be named guile-version.tar.gz. The current version is
890 @value{VERSION}, so the file you should grab is:
892 @url{ftp://ftp.gnu.org/pub/gnu/guile-@value{VERSION}.tar.gz}
894 To unbundle Guile use the instruction
897 zcat guile-@value{VERSION}.tar.gz | tar xvf -
900 which will create a directory called @file{guile-@value{VERSION}} with
901 all the sources. You can look at the file @file{INSTALL} for detailed
902 instructions on how to build and install Guile, but you should be able
906 cd guile-@value{VERSION}
912 This will install the Guile executable @file{guile}, the Guile library
913 @file{-lguile} and various associated header files and support
914 libraries. It will also install the Guile tutorial and reference
917 @c [[include instructions for getting R5RS]]
919 Since this manual frequently refers to the Scheme ``standard'', also
920 known as R5RS, or the
922 ``Revised$^5$ Report on the Algorithmic Language Scheme'',
925 ``Revised^5 Report on the Algorithmic Language Scheme'',
927 we have included the report in the Guile distribution;
928 @xref{Top, , Introduction, r5rs, Revised(5) Report on the Algorithmic
930 This will also be installed in your info directory.
933 @node Packages not shipped with Guile
934 @section Packages not shipped with Guile
936 We ship the Guile tutorial and reference manual with the Guile
937 distribution. Since the Scheme standard (R5RS) is a stable document, we
940 Here are references (usually World Wide Web URLs) to some other freely
941 redistributable documents and packages which you might find useful if
946 the Scheme Shell. Gary Houston has ported SCSH to Guile. The relevant
947 chapter (@pxref{The Scheme shell (scsh)}) has references to the SCSH web
948 page with all its documentation.
951 a portable Scheme library maintained by Aubrey Jaffer. SLIB can be
952 obtained by ftp from @url{ftp://prep.ai.mit.edu/pub/gnu/jacal/}.
954 The SLIB package should be unpacked somewhere in Guile's load path. It
955 will typically be unpacked in @file{/usr/local/share/guile/site}, so
956 that it will be @file{/usr/local/share/guile/site/slib}.
958 Guile might have been installed with a different prefix, in which case
959 the load path can be checked from inside the interpreter with:
963 ("/usr/local/share/guile/site" "/usr/local/share/guile/1.3a" "/usr/local/share/guile" ".")
966 The relevant chapter (@pxref{SLIB}) has details on how to use SLIB with
970 a symbolic math package by Aubrey Jaffer. The latest version of Jacal
971 can be obtained from @url{ftp://prep.ai.mit.edu/pub/gnu/jacal/}, and
972 should be unpacked in @file{/usr/local/share/guile/site/slib} so that
973 it will be in @file{/usr/local/share/guile/site/slib/jacal}.
975 The relevant section (@pxref{JACAL}) has details on how to use Jacal.
981 @chapter Reporting Bugs
983 Any problems with the installation should be reported to
984 @email{bug-guile@@gnu.org}.
986 Whenever you have found a bug in Guile you are encouraged to report it
987 to the Guile developers, so they can fix it. They may also be able to
988 suggest workarounds when it is not possible for you to apply the bug-fix
989 or install a new version of Guile yourself.
991 Before sending in bug reports, please check with the following list that
992 you really have found a bug.
996 Whenever documentation and actual behavior differ, you have certainly
997 found a bug, either in the documentation or in the program.
1000 When Guile crashes, it is a bug.
1003 When Guile hangs or takes forever to complete a task, it is a bug.
1006 When calculations produce wrong results, it is a bug.
1009 When Guile signals an error for valid Scheme programs, it is a bug.
1012 When Guile does not signal an error for invalid Scheme programs, it may
1013 be a bug, unless this is explicitly documented.
1016 When some part of the documentation is not clear and does not make sense
1017 to you even after re-reading the section, it is a bug.
1020 When you write a bug report, please make sure to include as much of the
1021 information described below in the report. If you can't figure out some
1022 of the items, it is not a problem, but the more information we get, the
1023 more likely we can diagnose and fix the bug.
1027 The version number of Guile. Without this, we won't know whether there
1028 is any point in looking for the bug in the current version of Guile.
1030 You can get the version number by invoking the command
1035 Copyright (c) 1995, 1996, 1997, 2000 Free Software Foundation
1036 Guile may be distributed under the terms of the GNU General Public License;
1037 certain other uses are permitted as well. For details, see the file
1038 `COPYING', which is included in the Guile distribution.
1039 There is no warranty, to the extent permitted by law.
1043 The type of machine you are using, and the operating system name and
1044 version number. On GNU systems, you can get it with @file{uname}.
1048 Linux tortoise 2.2.17 #1 Thu Dec 21 17:29:05 CET 2000 i586 unknown
1052 The operands given to the @file{configure} command when Guile was
1053 installed. It's often useful to augment this with the output of the
1054 command @code{guile-config info}.
1057 A complete list of any modifications you have made to the Guile source.
1058 (We may not have time to investigate the bug unless it happens in an
1059 unmodified Guile. But if you've made modifications and you don't tell
1060 us, you are sending us on a wild goose chase.)
1062 Be precise about these changes. A description in English is not
1063 enough---send a context diff for them.
1065 Adding files of your own, or porting to another machine, is a
1066 modification of the source.
1069 Details of any other deviations from the standard procedure for
1073 The complete text of any source files needed to reproduce the bug.
1075 If you can tell us a way to cause the problem without loading any source
1076 files, please do so. This makes it much easier to debug. If you do
1077 need files, make sure you arrange for us to see their exact contents.
1080 The precise Guile invocation command line we need to type to reproduce
1084 A description of what behavior you observe that you believe is
1085 incorrect. For example, "The Guile process gets a fatal signal," or,
1086 "The resulting output is as follows, which I think is wrong."
1088 Of course, if the bug is that Guile gets a fatal signal, then one can't
1089 miss it. But if the bug is incorrect results, the maintainer might fail
1090 to notice what is wrong. Why leave it to chance?
1092 If the manifestation of the bug is a Guile error message, it is
1093 important to report the precise text of the error message, and a
1094 backtrace showing how the Scheme program arrived at the error.
1096 This can be done using the procedure @code{backtrace} in the REPL.
1099 Check whether any programs you have loaded into Guile, including your
1100 @file{.guile} file, set any variables that may affect the functioning of
1101 Guile. Also, see whether the problem happens in a freshly started Guile
1102 without loading your @file{.guile} file (start Guile with the @code{-q}
1103 switch to prevent loading the init file). If the problem does
1104 @emph{not} occur then, you must report the precise contents of any
1105 programs that you must load into Guile in order to cause the problem to
1109 If the problem does depend on an init file or other Scheme programs that
1110 are not part of the standard Guile distribution, then you should make
1111 sure it is not a bug in those programs by complaining to their
1112 maintainers first. After they verify that they are using Guile in a way
1113 that is supposed to work, they should report the bug.
1116 If you wish to mention something in the Guile source, show the line of
1117 code with a few lines of context. Don't just give a line number.
1119 The line numbers in the development sources might not match those in your
1120 sources. It would take extra work for the maintainers to determine what
1121 code is in your version at a given line number, and we could not be
1125 Additional information from a C debugger such as GDB might enable
1126 someone to find a problem on a machine which he does not have available.
1127 If you don't know how to use GDB, please read the GDB manual---it is not
1128 very long, and using GDB is easy. You can find the GDB distribution,
1129 including the GDB manual in online form, in most of the same places you
1130 can find the Guile distribution. To run Guile under GDB, you should
1131 switch to the @file{libguile} subdirectory in which Guile was compiled, then
1132 do @code{gdb guile} or @code{gdb .libs/guile} (if using GNU Libtool).
1134 However, you need to think when you collect the additional information
1135 if you want it to show what causes the bug.
1137 For example, many people send just a backtrace, but that is not very
1138 useful by itself. A simple backtrace with arguments often conveys
1139 little about what is happening inside Guile, because most of the
1140 arguments listed in the backtrace are pointers to Scheme objects. The
1141 numeric values of these pointers have no significance whatever; all that
1142 matters is the contents of the objects they point to (and most of the
1143 contents are themselves pointers).
1149 @c TeX-master: "guile.texi"