1 @c $Id: intro.texi,v 1.11 2001-05-30 20:32:05 mgrabmue Exp $
5 @chapter What is Guile?
7 Guile is an interpreter for the Scheme programming language, packaged
8 for use in a wide variety of environments. Guile implements Scheme as
16 Report on the Algorithmic Language Scheme (usually known as R5RS),
17 providing clean and general data and control structures. Guile goes
18 beyond the rather austere language presented in R5RS, extending it with
19 a module system, full access to POSIX system calls, networking support,
20 multiple threads, dynamic linking, a foreign function call interface,
21 powerful string processing, and many other features needed for
22 programming in the real world.
24 Like a shell, Guile can run interactively, reading expressions from the
25 user, evaluating them, and displaying the results, or as a script
26 interpreter, reading and executing Scheme code from a file. However,
27 Guile is also packaged as an object library, allowing other applications
28 to easily incorporate a complete Scheme interpreter. An application can
29 use Guile as an extension language, a clean and powerful configuration
30 language, or as multi-purpose ``glue'', connecting primitives provided
31 by the application. It is easy to call Scheme code from C code and vice
32 versa, giving the application designer full control of how and when to
33 invoke the interpreter. Applications can add new functions, data types,
34 control structures, and even syntax to Guile, creating a domain-specific
35 language tailored to the task at hand, but based on a robust language
38 Guile's module system allows one to break up a large program into
39 manageable sections with well-defined interfaces between them. Modules
40 may contain a mixture of interpreted and compiled code; Guile can use
41 either static or dynamic linking to incorporate compiled code. Modules
42 also encourage developers to package up useful collections of routines
43 for general distribution; as of this writing, one can find Emacs
44 interfaces, database access routines, compilers, GUI toolkit interfaces,
45 and HTTP client functions, among others.
47 In the future, we hope to expand Guile to support other languages like
48 Tcl and Perl by translating them to Scheme code. This means that users
49 can program applications which use Guile in the language of their
50 choice, rather than having the tastes of the application's author
55 @chapter A Whirlwind Tour
57 This chapter presents a quick tour of all the ways that Guile can be
61 * Running Guile Interactively::
63 * Linking Programs With Guile::
64 * Writing Extensions for Guile::
69 @node Running Guile Interactively
70 @section Running Guile Interactively
72 In its simplest form, Guile acts as an interactive interpreter for the
73 Scheme programming language, reading and evaluating Scheme expressions
74 the user enters from the terminal. Here is a sample interaction between
75 Guile and a user; the user's input appears after the @code{$} and
76 @code{guile>} prompts:
80 guile> (+ 1 2 3) ; add some numbers
82 guile> (define (factorial n) ; define a function
83 (if (zero? n) 1 (* n (factorial (- n 1)))))
86 guile> (getpwnam "jimb") ; find my entry in /etc/passwd
87 #("jimb" ".0krIpK2VqNbU" 4008 10 "Jim Blandy" "/u/jimb"
88 "/usr/local/bin/bash")
93 @c [[When we get a fancier read-eval-print loop, with features for bouncing
94 @c around among modules, referring to the value of the last expression,
95 @c etc. then this section will get longer.]]
99 @section Guile Scripts
101 Like AWK, Perl, or any shell, Guile can interpret script files. A Guile
102 script is simply a file of Scheme code with some extra information at
103 the beginning which tells the operating system how to invoke Guile, and
104 then tells Guile how to handle the Scheme code.
106 Before we present the details, here is a trivial Guile script:
109 #!/usr/local/bin/guile -s
111 (display "Hello, world!")
116 * The Top of a Script File:: How to start a Guile script.
117 * Scripting Examples:: Simple Guile scripts, explained.
121 @node The Top of a Script File
122 @subsection The Top of a Script File
124 The first line of a Guile script must tell the operating system to use
125 Guile to evaluate the script, and then tell Guile how to go about doing
126 that. Here is the simplest case:
131 The first two characters of the file must be @samp{#!}.
133 The operating system interprets this to mean that the rest of the line
134 is the name of an executable that can interpret the script. Guile,
135 however, interprets these characters as the beginning of a multi-line
136 comment, terminated by the characters @samp{!#} on a line by themselves.
137 (This is an extension to the syntax described in R5RS, added to support
141 Immediately after those two characters must come the full pathname to
142 the Guile interpreter. On most systems, this would be
143 @samp{/usr/local/bin/guile}.
146 Then must come a space, followed by a command-line argument to pass to
147 Guile; this should be @samp{-s}. This switch tells Guile to run a
148 script, instead of soliciting the user for input from the terminal.
149 There are more elaborate things one can do here; see @ref{The Meta
153 Follow this with a newline.
156 The second line of the script should contain only the characters
157 @samp{!#} --- just like the top of the file, but reversed. The
158 operating system never reads this far, but Guile treats this as the end
159 of the comment begun on the first line by the @samp{#!} characters.
162 The rest of the file should be a Scheme program.
166 Guile reads the program, evaluating expressions in the order that they
167 appear. Upon reaching the end of the file, Guile exits.
169 The function @code{command-line} returns the name of the script file and
170 any command-line arguments passed by the user, as a list of strings.
172 For example, consider the following script file:
174 #!/usr/local/bin/guile -s
176 (write (command-line))
180 If you put that text in a file called @file{foo} in the current
181 directory, then you could make it executable and try it out like this:
187 ("./foo" "bar" "baz")
191 As another example, here is a simple replacement for the POSIX
194 #!/usr/local/bin/guile -s
196 (for-each (lambda (s) (display s) (display " "))
197 (cdr (command-line)))
201 @deffn procedure command-line
202 @deffnx primitive program-arguments
203 Return a list of the command-line arguments passed to the currently
204 running program. If the program invoked Guile with the @samp{-s},
205 @samp{-c} or @samp{--} switches, these procedures ignore everything up
206 to and including those switches.
210 @node Scripting Examples
211 @subsection Scripting Examples
213 To start with, here are some examples of invoking Guile directly:
218 Run Guile interactively; @code{(command-line)} will return @*
219 @code{("/usr/local/bin/guile" "a" "b" "c")}.
221 @item guile -s /u/jimb/ex2 a b c
222 Load the file @file{/u/jimb/ex2}; @code{(command-line)} will return @*
223 @code{("/u/jimb/ex2" "a" "b" "c")}.
225 @item guile -c '(write %load-path) (newline)'
226 Write the value of the variable @code{%load-path}, print a newline,
229 @item guile -e main -s /u/jimb/ex4 foo
230 Load the file @file{/u/jimb/ex4}, and then call the function
231 @code{main}, passing it the list @code{("/u/jimb/ex4" "foo")}.
233 @item guile -l first -ds -l last -s script
234 Load the files @file{first}, @file{script}, and @file{last}, in that
235 order. The @code{-ds} switch says when to process the @code{-s}
236 switch. For a more motivated example, see the scripts below.
241 Here is a very simple Guile script:
243 #!/usr/local/bin/guile -s
245 (display "Hello, world!")
248 The first line marks the file as a Guile script. When the user invokes
249 it, the system runs @file{/usr/local/bin/guile} to interpret the script,
250 passing @code{-s}, the script's filename, and any arguments given to the
251 script as command-line arguments. When Guile sees @code{-s
252 @var{script}}, it loads @var{script}. Thus, running this program
258 Here is a script which prints the factorial of its argument:
260 #!/usr/local/bin/guile -s
264 (* n (fact (- n 1)))))
266 (display (fact (string->number (cadr (command-line)))))
276 However, suppose we want to use the definition of @code{fact} in this
277 file from another script. We can't simply @code{load} the script file,
278 and then use @code{fact}'s definition, because the script will try to
279 compute and display a factorial when we load it. To avoid this problem,
280 we might write the script this way:
283 #!/usr/local/bin/guile \
288 (* n (fact (- n 1)))))
291 (display (fact (string->number (cadr args))))
294 This version packages the actions the script should perform in a
295 function, @code{main}. This allows us to load the file purely for its
296 definitions, without any extraneous computation taking place. Then we
297 used the meta switch @code{\} and the entry point switch @code{-e} to
298 tell Guile to call @code{main} after loading the script.
301 30414093201713378043612608166064768844377641568960512000000000000
304 Suppose that we now want to write a script which computes the
305 @code{choose} function: given a set of @var{m} distinct objects,
306 @code{(choose @var{n} @var{m})} is the number of distinct subsets
307 containing @var{n} objects each. It's easy to write @code{choose} given
308 @code{fact}, so we might write the script this way:
310 #!/usr/local/bin/guile \
314 (/ (fact m) (* (fact (- m n)) (fact n))))
317 (let ((n (string->number (cadr args)))
318 (m (string->number (caddr args))))
319 (display (choose n m))
323 The command-line arguments here tell Guile to first load the file
324 @file{fact}, and then run the script, with @code{main} as the entry
325 point. In other words, the @code{choose} script can use definitions
326 made in the @code{fact} script. Here are some sample runs:
339 100891344545564193334812497256
343 @node Linking Programs With Guile
344 @section Linking Programs With Guile
346 The Guile interpreter is available as an object library, to be linked
347 into applications using Scheme as a configuration or extension
348 language. This chapter covers the mechanics of linking your program
349 with Guile on a typical POSIX system.
351 Parts III and IV of this manual describe the C functions Guile provides.
352 Furthermore, any Scheme function described in this manual as a
353 ``Primitive'' is also callable from C; see @ref{Scheme Primitives}.
355 The header file @code{<libguile.h>} provides declarations for all of
356 Guile's functions and constants. You should @code{#include} it at the
357 head of any C source file that uses identifiers described in this
358 manual. Once you've compiled your source files, you need to link them
359 against the Guile object code library, @code{libguile}.
361 On most systems, you should not need to do tell the compiler and linker
362 explicitely where they can find @file{libguile.h} and @file{libguile}.
363 When Guile has been installed in a peculiar way, or when you are on a
364 peculiar system, things might not be so easy and you might need to pass
365 additional @code{-I} or @code{-L} options to the compiler. Guile
366 provides the utility program @code{guile-config} to help you find the
367 right values for these options. You would typically run
368 @code{guile-config} during the configuration phase of your program and
369 use the obtained information in the Makefile.
372 * Guile Initialization Functions:: What to call first.
373 * A Sample Guile Main Program:: Sources and makefiles.
377 @node Guile Initialization Functions
378 @subsection Guile Initialization Functions
380 To initialize Guile, you can use one of two functions. The first,
381 @code{scm_boot_guile}, is the most portable way to initialize Guile. It
382 should be used whenever you have control over the main function of your
383 program because it never returns. The second function,
384 @code{scm_init_guile}, does return and can thus be used in more
385 situations. However, @code{scm_init_guile} is not as widely available
386 as @code{scm_boot_guile} because it needs to rely on non-portable code
387 to find the stack bounds. When Guile does not know how to find these
388 bounds on your system, it will not provide @code{scm_init_guile}.
390 When you can tolerate the limits of @code{scm_boot_guile}, you should
391 use it in favor of @code{scm_init_guile} since that will make your
392 program more portable.
394 @deftypefun void scm_boot_guile (int @var{argc}, char **@var{argv}, void (*@var{main_func}) (), void *@var{closure})
395 Initialize the Guile Scheme interpreter. Then call @var{main_func},
396 passing it @var{closure}, @var{argc}, and @var{argv}. @var{main_func}
397 should do all the work of the program (initializing other packages,
398 defining application-specific functions, reading user input, and so on)
399 before returning. When @var{main_func} returns, call @code{exit (0)};
400 @code{scm_boot_guile} never returns. If you want some other exit value,
401 have @var{main_func} call exit itself.
403 @code{scm_boot_guile} arranges for the Scheme @code{command-line}
404 function to return the strings given by @var{argc} and @var{argv}. If
405 @var{main_func} modifies @var{argc} or @var{argv}, it should call
406 @code{scm_set_program_arguments} with the final list, so Scheme code
407 will know which arguments have been processed.
409 Why must the caller do all the real work from @var{main_func}? Guile's
410 garbage collector scans the stack to find all local variables that
411 reference Scheme objects. To do this, it needs to know the bounds of
412 the stack that might contain such references. Because there is no
413 protable way in C to find the base of the stack, @code{scm_boot_guile}
414 assumes that all references are above its own stack frame. If you try
415 to manipulate Scheme objects after this function returns, it's the luck
416 of the draw whether Guile's storage manager will be able to find the
417 objects you allocate. So, @code{scm_boot_guile} function exits, rather
418 than returning, to discourage you from making that mistake.
420 See @code{scm_init_guile}, below, for a function that can find the real
421 base of the stack, but not in a portable way.
424 @deftypefun void scm_init_guile ()
425 Initialize the Guile Scheme interpreter.
427 In contrast to @code{scm_boot_guile}, this function knows how to find
428 the true base of the stack and thus does not need to usurp the control
429 flow of your program. However, since finding the stack base can not be
430 done portably, this function might not be available in all installations
431 of Guile. If you can, you should use @code{scm_boot_guile} instead.
433 Note that @code{scm_init_guile} does not inform Guile about the command
434 line arguments that should be returned by the Scheme function
435 @code{comamnd-line}. You can use @code{scm_set_program_arguments} to do
439 One common way to use Guile is to write a set of C functions which
440 perform some useful task, make them callable from Scheme, and then link
441 the program with Guile. This yields a Scheme interpreter just like
442 @code{guile}, but augmented with extra functions for some specific
443 application --- a special-purpose scripting language.
445 In this situation, the application should probably process its
446 command-line arguments in the same manner as the stock Guile
447 interpreter. To make that straightforward, Guile provides this
450 @deftypefun void scm_shell (int @var{argc}, char **@var{argv})
451 Process command-line arguments in the manner of the @code{guile}
452 executable. This includes loading the normal Guile initialization
453 files, interacting with the user or running any scripts or expressions
454 specified by @code{-s} or @code{-e} options, and then exiting.
455 @xref{Invoking Guile}, for more details.
457 Since this function does not return, you must do all
458 application-specific initialization before calling this function.
462 @node A Sample Guile Main Program
463 @subsection A Sample Guile Main Program
465 Here is @file{simple-guile.c}, source code for a @code{main} and an
466 @code{inner_main} function that will produce a complete Guile
470 /* simple-guile.c --- how to start up the Guile
471 interpreter from C code. */
473 /* Get declarations for all the scm_ functions. */
474 #include <libguile.h>
477 inner_main (void *closure, int argc, char **argv)
479 /* module initializations would go here */
480 scm_shell (argc, argv);
484 main (int argc, char **argv)
486 scm_boot_guile (argc, argv, inner_main, 0);
487 return 0; /* never reached */
491 The @code{main} function calls @code{scm_boot_guile} to initialize
492 Guile, passing it @code{inner_main}. Once @code{scm_boot_guile} is
493 ready, it invokes @code{inner_main}, which calls @code{scm_shell} to
494 process the command-line arguments in the usual way.
496 Here is a Makefile which you can use to compile the above program. It
497 uses @code{guile-config} to learn about the necessary compiler and
500 # Use GCC, if you have it installed.
503 # Tell the C compiler where to find <libguile.h>
504 CFLAGS=`guile-config compile`
506 # Tell the linker what libraries to use and where to find them.
507 LIBS=`guile-config link`
509 simple-guile: simple-guile.o
510 $@{CC@} simple-guile.o $@{LIBS@} -o simple-guile
512 simple-guile.o: simple-guile.c
513 $@{CC@} -c $@{CFLAGS@} simple-guile.c
516 If you are using the GNU Autoconf package to make your application more
517 portable, Autoconf will settle many of the details in the Makefile above
518 automatically, making it much simpler and more portable; we recommend
519 using Autoconf with Guile. Guile also provides the @code{GUILE_FLAGS}
520 macro for autoconf that performs all necessary checks. Here is a
521 @file{configure.in} file for @code{simple-guile} that uses this macro.
522 Autoconf can use as this file as template to generate a @code{configure}
523 script. In order for Autoconf to find the @code{GUILE_FLAGS} macro, you
524 will need to run @code{aclocal} first. This is not really Guile
525 specific, so you should refer to the Autoconf documentation REFFIXME
528 AC_INIT(simple-guile.c)
536 # Generate a Makefile, based on the results.
540 Here is a @code{Makefile.in} template, from which the @code{configure}
541 script produces a Makefile customized for the host system:
543 # The configure script fills in these values.
545 CFLAGS=@@GUILE_CFLAGS@@
546 LIBS=@@GUILE_LDFLAGS@@
548 simple-guile: simple-guile.o
549 $@{CC@} simple-guile.o $@{LIBS@} -o simple-guile
550 simple-guile.o: simple-guile.c
551 $@{CC@} -c $@{CFLAGS@} simple-guile.c
554 The developer should use Autoconf to generate the @file{configure}
555 script from the @file{configure.in} template, and distribute
556 @file{configure} with the application. Here's how a user might go about
557 building the application:
561 Makefile.in configure* configure.in simple-guile.c
563 creating cache ./config.cache
564 checking for gcc... (cached) gcc
565 checking whether the C compiler (gcc ) works... yes
566 checking whether the C compiler (gcc ) is a cross-compiler... no
567 checking whether we are using GNU C... (cached) yes
568 checking whether gcc accepts -g... (cached) yes
569 checking for Guile... yes
570 creating ./config.status
573 gcc -c -I/usr/local/include simple-guile.c
574 gcc simple-guile.o -L/usr/local/lib -lguile -lqthreads -lpthread -lm -o simple-guile
578 guile> (getpwnam "jimb")
579 #("jimb" "83Z7d75W2tyJQ" 4008 10 "Jim Blandy" "/u/jimb"
580 "/usr/local/bin/bash")
585 @node Writing Extensions for Guile
586 @section Writing Extensions for Guile
588 The previous sections have briefly explained how to write programs that
589 make use of an embedded Guile interpreter. But sometimes, all you want
590 to do is make new primitive procedures and data types available to the
591 Scheme programmer. Writing a new version of @code{guile} is
592 inconvenient in this case and it would in fact make the life of the
593 users of your new features needlessly hard.
595 @c [[ the following is probably a bit longwinded ]]
597 For example, suppose that there is a program @code{guile-db} that is a
598 version of Guile with additional features for accessing a database.
599 People who want to write Scheme programs that use these features would
600 have to use @code{guile-db} instead of the usual @code{guile} program.
601 Now suppose that there is also a program @code{guile-gtk} that extends
602 Guile with access to the popular Gtk+ toolkit for graphical user
603 interfaces. People who want to write GUIs in Scheme would have to use
604 @code{guile-gtk}. Now, what happens when you want to write a Scheme
605 application that uses a GUI to let the user accessa a database? You
606 would have to write a @emph{third} program that incorporates both the
607 database stuff and the GUI stuff. This might not be easy (because
608 @code{guile-gtk} might be a quite obscure program, say) and taking this
609 example further makes it easy to see that this approach can not work in
612 It would have been much better if both the database features and the GUI
613 feature had been provided as libraries that can just be linked with
614 @code{guile}. Guile makes it easy to do just this, and we encourage you
615 to make your extensions to Guile available as libraries whenever
618 You write the new primitive procedures and data types in the normal
619 fashion, and link them into a shared library instead of into a
620 standalone program. The shared library can then be loaded dynamically
624 * A Sample Guile Extension::
627 @node A Sample Guile Extension
628 @subsection A Sample Guile Extension
630 This section explains how to make the Bessel functions of the C library
631 available to Scheme. First we need to write the appropriate glue code
632 to convert the arguments and return values of the functions from Scheme
633 to C and back. Additionally, we need a function that will add them to
634 the set of Guile primitives. Because this is just an example, we will
635 only implement this for the @code{j0} function, tho.
637 Consider the following file @file{bessel.c}.
641 #include <libguile.h>
646 return scm_make_real (j0 (scm_num2dbl (x, "j0")));
652 scm_make_gsubr ("j0", 1, 0, 0, j0_wrapper);
656 This C source file needs to be compiled into a shared library. Here is
657 how to do it on GNU/Linux:
660 gcc -shared -o libguile-bessel.so -fPIC bessel.c
663 For creating shared libraries portably, we recommend the use of
666 A shared library can be loaded into a running Guile process with
667 @code{dynamic-link}. After it has been linked you can call its exported
668 functions via @code{dynamic-call}. For our example, we are going to
669 call the function @code{init_bessel} which will make @code{j0_wrapper}
670 available to Scheme programs with the name @code{j0}. Note that we do
671 not specify a filename extension such as @file{.so} when invoking
672 @code{dynamic-link}. The right extension for the host platform will be
673 provided automatically.
676 (define bessel-lib (dynamic-link "libguile-bessel"))
677 (dynamic-call "init_bessel" bessel-lib)
679 @result{} 0.223890779141236
682 For this to work, @code{dynamic-link} must be able to find
683 @file{libguile-bessel}, of course. It will look in the places that are
684 usual for your operating system, and it will additionally look into the
685 directories listed in the @code{LTDL_LIBRRAY_PATH} environment variable.
687 To see how these Guile extensions via shared libraries relate to the
688 module system, see below @xref{Intro to Modules and Extensions}.
691 @section Guile Modules
693 Guile has support for dividing a program into @dfn{modules}. By using
694 modules, you can group related code together and manage the
695 composition of complete programs from largely independent parts.
697 (Although the module system implementation is in flux, feel free to use it
698 anyway. Guile will provide reasonable backwards compatability.)
700 Details on the module system beyond this introductory material can be found in
705 * Intro to Using Guile Modules::
706 * Intro to Writing New Modules::
707 * Intro to Modules and Extensions::
710 @node Intro to Using Guile Modules
711 @subsection Intro to Using Existing Modules
713 Guile comes with a lot of useful modules, for example for string
714 processing or command line parsing. Additionally, there exist many
715 Guile modules written by other Guile hackers, but which have to be
718 Existing modules have to be placed in places where Guile looks for them
719 by default or in colon-separated directories in the environment variable
720 @code{GUILE_LOAD_PATH}. When this variable is set, those directories
721 are searched first, then the the default. The following command
722 shows the complete list of directories searched:
725 guile -c '(for-each write-line %load-path)'
728 Suppose you want to use the procedures and variables exported by the
729 module @code{(ice-9 popen)}, which provides the means for communicating
730 with other processes over pipes. Add the following line to your
731 currently running Guile REPL or the top of you script file.
734 (use-modules (ice-9 popen))
737 This will load the module and make the procedures exported by
738 @code{(ice-9 popen)} automatically available. The next step could be to
739 open a pipe to @file{ls} and read the contents of the current directory,
743 (define p (open-input-pipe "ls -l"))
749 "drwxr-sr-x 2 mgrabmue mgrabmue 1024 Mar 29 19:57 CVS"
753 @node Intro to Writing New Modules
754 @subsection Intro to Writing New Modules
756 Of course it is possible to write modules yourself. Using modules for
757 structuring your programs makes them more readable and lets you
758 distribute them more easily. Also, explicitly defining the procedures
759 and variables which are exported from a module adds documentation to the
760 source and specifies the interface a module provides.
762 In Guile, you can create new modules and switch to exisiting modules in
763 order to add bindings to them using the syntactic form
764 @code{define-module}.
767 (define-module (foo bar))
772 Will create the module @code{(foo bar)}.@footnote{It is only convention
773 that the module names in this section have two elements. One or more
774 than two elements are perfectly fine, such as @code{(foo)} or @code{(foo
775 bar braz)}} All definitions following this statement will add bindings
776 to the module @code{(foo bar)}, and these bindings will not be visible
777 outside of the module. To make the bindings accessible to other
778 modules, you have to export them explicitly using one of the following
783 Export them with the @code{export} form:
789 Include them into the @code{define-module} form with the keyword
792 (define-module (foo bar)
797 Change the definition of @code{frob} to use @code{define-public}, which
798 is a combination of @code{define} and @code{export}.
800 (define-public (frob x) x)
804 After exporting, other modules can access the exported items simply by
805 using @code{use-modules} to load the module @code{(foo bar)}.
808 @node Intro to Modules and Extensions
809 @subsection Intro to Modules and Extensions
811 In addition to Scheme code you can also put new procedures and other
812 named features that are provided by an extension into a module.
814 You do this by writing a small Scheme file that defines the module.
815 That Scheme file in turn invokes @code{dynamic-link} and
816 @code{dynamic-call} as explained above to make the extension
819 Suppose we want to put the Bessel function @code{j0} from the example
820 extension into a module called @code{(math bessel)}. We would have to
821 write a Scheme file with this contents
824 (define-module (math bessel))
826 (dynamic-call "init_bessel" (dynamic-link "libguile-bessel"))
829 The file should of course be saved in the right place for autoloading,
830 for example as @file{/usr/local/share/guile/math/bessel.scm}.
835 @chapter Reporting Bugs
837 Any problems with the installation should be reported to
838 @email{bug-guile@@gnu.org}.
840 Whenever you have found a bug in Guile you are encouraged to report it
841 to the Guile developers, so they can fix it. They may also be able to
842 suggest workarounds when it is not possible for you to apply the bugfix
843 or install a new version of Guile yourself.
845 Before sending in bug reports, please check with the following list that
846 you really have found a bug.
850 Whenever documentation and actual behaviour differ, you have certainly
851 found a bug, either in the documentation or in the program.
854 When Guile crashes, it is a bug.
857 When Guile hangs or takes forever to complete a task, it is a bug.
860 When calculations produce wrong results, it is a bug.
863 When Guile signals an error for valid Scheme programs, it is a bug.
866 When Guile does not signal an error for invalid Scheme programs, it may
867 be a bug, unless this is explicitly documented.
870 When some part of the documentation is not clear and does not make sense
871 to you even after re-reading the section, it is a bug.
874 When you write a bug report, please make sure to include as much of the
875 information described below in the report. If you can't figure out some
876 of the items, it is not a problem, but the more information we get, the
877 more likely we can diagnose and fix the bug.
881 The version number of Guile. Without this, we won't know whether there
882 is any point in looking for the bug in the current version of Guile.
884 You can get the version number by invoking the command
889 Copyright (c) 1995, 1996, 1997, 2000 Free Software Foundation
890 Guile may be distributed under the terms of the GNU General Public Licence;
891 certain other uses are permitted as well. For details, see the file
892 `COPYING', which is included in the Guile distribution.
893 There is no warranty, to the extent permitted by law.
897 The type of machine you are using, and the operating system name and
898 version number. On GNU systems, you can get it with @file{uname}.
902 Linux tortoise 2.2.17 #1 Thu Dec 21 17:29:05 CET 2000 i586 unknown
906 The operands given to the @file{configure} command when Guile was
907 installed. It's often useful to augment this with the output of the
908 command @code{guile-config info}.
911 A complete list of any modifications you have made to the Guile source.
912 (We may not have time to investigate the bug unless it happens in an
913 unmodified Guile. But if you've made modifications and you don't tell
914 us, you are sending us on a wild goose chase.)
916 Be precise about these changes. A description in English is not
917 enough---send a context diff for them.
919 Adding files of your own, or porting to another machine, is a
920 modification of the source.
923 Details of any other deviations from the standard procedure for
927 The complete text of any source files needed to reproduce the bug.
929 If you can tell us a way to cause the problem without loading any source
930 files, please do so. This makes it much easier to debug. If you do
931 need files, make sure you arrange for us to see their exact contents.
934 The precise Guile invocation command line we need to type to reproduce
938 A description of what behavior you observe that you believe is
939 incorrect. For example, "The Guile process gets a fatal signal," or,
940 "The resulting output is as follows, which I think is wrong."
942 Of course, if the bug is that Guile gets a fatal signal, then one can't
943 miss it. But if the bug is incorrect results, the maintainer might fail
944 to notice what is wrong. Why leave it to chance?
946 If the manifestation of the bug is an Guile error message, it is
947 important to report the precise text of the error message, and a
948 backtrace showing how the Scheme program arrived at the error.
950 This can be done using the procedure @code{backtrace} in the REPL.
953 Check whether any programs you have loaded into Guile, including your
954 @file{.guile} file, set any variables that may affect the functioning of
955 Guile. Also, see whether the problem happens in a freshly started Guile
956 without loading your @file{.guile} file (start Guile with the @code{-q}
957 switch to prevent loading the init file). If the problem does
958 @emph{not} occur then, you must report the precise contents of any
959 programs that you must load into Guile in order to cause the problem to
963 If the problem does depend on an init file or other Lisp programs that
964 are not part of the standard Guile distribution, then you should make
965 sure it is not a bug in those programs by complaining to their
966 maintainers first. After they verify that they are using Guile in a way
967 that is supposed to work, they should report the bug.
970 If you wish to mention something in the Guile source, show the line of
971 code with a few lines of context. Don't just give a line number.
973 The line numbers in the development sources don't match those in your
974 sources. It would take extra work for the maintainers to determine what
975 code is in your version at a given line number, and we could not be
979 Additional information from a C debugger such as GDB might enable
980 someone to find a problem on a machine which he does not have available.
981 If you don't know how to use GDB, please read the GDB manual---it is not
982 very long, and using GDB is easy. You can find the GDB distribution,
983 including the GDB manual in online form, in most of the same places you
984 can find the Guile distribution. To run Guile under GDB, you should
985 switch to the @file{libguile} subdirectory in which Guile was compiled, then
986 do @code{gdb .libs/guile}.
987 @c fixme: libguile/.libs is for libtool-enabled systems -- what about rest?
989 However, you need to think when you collect the additional information
990 if you want it to show what causes the bug.
992 For example, many people send just a backtrace, but that is not very
993 useful by itself. A simple backtrace with arguments often conveys
994 little about what is happening inside Guile, because most of the
995 arguments listed in the backtrace are pointers to Scheme objects. The
996 numeric values of these pointers have no significance whatever; all that
997 matters is the contents of the objects they point to (and most of the
998 contents are themselves pointers).
1004 @c TeX-master: "guile.texi"