Commit | Line | Data |
---|---|---|
2da09c3f MV |
1 | @c -*-texinfo-*- |
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. | |
6 | ||
38a93523 NJ |
7 | @page |
8 | @node What is Guile? | |
9 | @chapter What is Guile? | |
10 | ||
11 | Guile is an interpreter for the Scheme programming language, packaged | |
12 | for use in a wide variety of environments. Guile implements Scheme as | |
13 | described in the | |
14 | @tex | |
15 | Revised$^5$ | |
16 | @end tex | |
801892e7 | 17 | @ifnottex |
38a93523 | 18 | Revised^5 |
801892e7 | 19 | @end ifnottex |
01b30204 | 20 | Report on the Algorithmic Language Scheme (usually known as @acronym{R5RS}), |
38a93523 | 21 | providing clean and general data and control structures. Guile goes |
01b30204 MV |
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, | |
38a93523 NJ |
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. | |
27 | ||
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 | |
01b30204 | 33 | then use Guile as an extension language, a clean and powerful configuration |
38a93523 NJ |
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 | |
40 | design. | |
41 | ||
42 | Guile's module system allows one to break up a large program into | |
01b30204 MV |
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. | |
38a93523 NJ |
50 | |
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 | |
55 | imposed on them. | |
56 | ||
9401323e | 57 | |
38a93523 NJ |
58 | @page |
59 | @node Whirlwind Tour | |
60 | @chapter A Whirlwind Tour | |
61 | ||
62 | This chapter presents a quick tour of all the ways that Guile can be | |
cc772cf8 MV |
63 | used. There are additional examples in the @file{examples/} |
64 | directory in the Guile source distribution. | |
38a93523 NJ |
65 | |
66 | @menu | |
5134bfa7 TTN |
67 | * Running Guile Interactively:: |
68 | * Guile Scripts:: | |
69 | * Linking Programs With Guile:: | |
70 | * Writing Extensions for Guile:: | |
71 | * Guile Modules:: | |
38a93523 NJ |
72 | @end menu |
73 | ||
74 | ||
75 | @node Running Guile Interactively | |
76 | @section Running Guile Interactively | |
77 | ||
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: | |
83 | ||
84 | @example | |
85 | $ guile | |
86 | guile> (+ 1 2 3) ; add some numbers | |
87 | 6 | |
88 | guile> (define (factorial n) ; define a function | |
89 | (if (zero? n) 1 (* n (factorial (- n 1))))) | |
90 | guile> (factorial 20) | |
91 | 2432902008176640000 | |
92 | guile> (getpwnam "jimb") ; find my entry in /etc/passwd | |
93 | #("jimb" ".0krIpK2VqNbU" 4008 10 "Jim Blandy" "/u/jimb" | |
94 | "/usr/local/bin/bash") | |
95 | guile> @kbd{C-d} | |
96 | $ | |
97 | @end example | |
98 | ||
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.]] | |
102 | ||
103 | ||
104 | @node Guile Scripts | |
105 | @section Guile Scripts | |
106 | ||
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. | |
111 | ||
112 | Before we present the details, here is a trivial Guile script: | |
113 | ||
114 | @example | |
115 | #!/usr/local/bin/guile -s | |
116 | !# | |
117 | (display "Hello, world!") | |
118 | (newline) | |
119 | @end example | |
120 | ||
121 | @menu | |
122 | * The Top of a Script File:: How to start a Guile script. | |
123 | * Scripting Examples:: Simple Guile scripts, explained. | |
124 | @end menu | |
125 | ||
126 | ||
127 | @node The Top of a Script File | |
128 | @subsection The Top of a Script File | |
129 | ||
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: | |
133 | ||
134 | @itemize @bullet | |
135 | ||
136 | @item | |
137 | The first two characters of the file must be @samp{#!}. | |
138 | ||
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 | |
144 | shell scripts.) | |
145 | ||
146 | @item | |
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}. | |
150 | ||
151 | @item | |
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 | |
156 | Switch}. | |
157 | ||
158 | @item | |
159 | Follow this with a newline. | |
160 | ||
161 | @item | |
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. | |
166 | ||
167 | @item | |
168 | The rest of the file should be a Scheme program. | |
169 | ||
170 | @end itemize | |
171 | ||
172 | Guile reads the program, evaluating expressions in the order that they | |
173 | appear. Upon reaching the end of the file, Guile exits. | |
174 | ||
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. | |
177 | ||
178 | For example, consider the following script file: | |
179 | @example | |
180 | #!/usr/local/bin/guile -s | |
181 | !# | |
182 | (write (command-line)) | |
183 | (newline) | |
184 | @end example | |
185 | ||
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: | |
188 | @example | |
189 | $ chmod a+x foo | |
190 | $ ./foo | |
191 | ("./foo") | |
192 | $ ./foo bar baz | |
193 | ("./foo" "bar" "baz") | |
5134bfa7 | 194 | $ |
38a93523 NJ |
195 | @end example |
196 | ||
197 | As another example, here is a simple replacement for the POSIX | |
198 | @code{echo} command: | |
199 | @example | |
200 | #!/usr/local/bin/guile -s | |
201 | !# | |
202 | (for-each (lambda (s) (display s) (display " ")) | |
203 | (cdr (command-line))) | |
204 | (newline) | |
205 | @end example | |
206 | ||
8f85c0c6 NJ |
207 | @deffn {Scheme Procedure} command-line |
208 | @deffnx {Scheme Procedure} program-arguments | |
38a93523 NJ |
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. | |
213 | @end deffn | |
214 | ||
215 | ||
216 | @node Scripting Examples | |
217 | @subsection Scripting Examples | |
218 | ||
219 | To start with, here are some examples of invoking Guile directly: | |
220 | ||
221 | @table @code | |
222 | ||
223 | @item guile -- a b c | |
224 | Run Guile interactively; @code{(command-line)} will return @* | |
225 | @code{("/usr/local/bin/guile" "a" "b" "c")}. | |
226 | ||
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")}. | |
230 | ||
231 | @item guile -c '(write %load-path) (newline)' | |
232 | Write the value of the variable @code{%load-path}, print a newline, | |
233 | and exit. | |
234 | ||
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")}. | |
238 | ||
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. | |
243 | ||
244 | @end table | |
245 | ||
246 | ||
247 | Here is a very simple Guile script: | |
248 | @example | |
249 | #!/usr/local/bin/guile -s | |
250 | !# | |
251 | (display "Hello, world!") | |
252 | (newline) | |
253 | @end example | |
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 | |
259 | produces the output: | |
260 | @example | |
261 | Hello, world! | |
262 | @end example | |
263 | ||
264 | Here is a script which prints the factorial of its argument: | |
265 | @example | |
266 | #!/usr/local/bin/guile -s | |
267 | !# | |
268 | (define (fact n) | |
269 | (if (zero? n) 1 | |
270 | (* n (fact (- n 1))))) | |
271 | ||
272 | (display (fact (string->number (cadr (command-line))))) | |
273 | (newline) | |
274 | @end example | |
275 | In action: | |
276 | @example | |
277 | $ fact 5 | |
278 | 120 | |
279 | $ | |
280 | @end example | |
281 | ||
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: | |
287 | ||
288 | @example | |
289 | #!/usr/local/bin/guile \ | |
290 | -e main -s | |
291 | !# | |
292 | (define (fact n) | |
293 | (if (zero? n) 1 | |
294 | (* n (fact (- n 1))))) | |
295 | ||
296 | (define (main args) | |
297 | (display (fact (string->number (cadr args)))) | |
298 | (newline)) | |
299 | @end example | |
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. | |
305 | @example | |
306 | $ fact 50 | |
307 | 30414093201713378043612608166064768844377641568960512000000000000 | |
308 | @end example | |
309 | ||
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: | |
315 | @example | |
316 | #!/usr/local/bin/guile \ | |
317 | -l fact -e main -s | |
318 | !# | |
319 | (define (choose n m) | |
320 | (/ (fact m) (* (fact (- m n)) (fact n)))) | |
321 | ||
322 | (define (main args) | |
323 | (let ((n (string->number (cadr args))) | |
324 | (m (string->number (caddr args)))) | |
325 | (display (choose n m)) | |
326 | (newline))) | |
327 | @end example | |
328 | ||
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: | |
333 | @example | |
334 | $ choose 0 4 | |
335 | 1 | |
336 | $ choose 1 4 | |
337 | 4 | |
338 | $ choose 2 4 | |
339 | 6 | |
340 | $ choose 3 4 | |
341 | 4 | |
342 | $ choose 4 4 | |
343 | 1 | |
344 | $ choose 50 100 | |
345 | 100891344545564193334812497256 | |
346 | @end example | |
347 | ||
348 | ||
349 | @node Linking Programs With Guile | |
350 | @section Linking Programs With Guile | |
351 | ||
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. | |
356 | ||
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 | |
a7a7bb95 | 359 | ``Primitive'' is also callable from C; see @ref{Primitives}. |
38a93523 NJ |
360 | |
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 | |
ac3e3f5b MV |
364 | manual. Once you've compiled your source files, you need to link them |
365 | against the Guile object code library, @code{libguile}. | |
366 | ||
4902ea64 | 367 | On most systems, you should not need to tell the compiler and linker |
b45898ca | 368 | explicitly where they can find @file{libguile.h} and @file{libguile}. |
ac3e3f5b MV |
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. | |
38a93523 NJ |
376 | |
377 | @menu | |
378 | * Guile Initialization Functions:: What to call first. | |
379 | * A Sample Guile Main Program:: Sources and makefiles. | |
380 | @end menu | |
381 | ||
382 | ||
383 | @node Guile Initialization Functions | |
384 | @subsection Guile Initialization Functions | |
385 | ||
ac3e3f5b MV |
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}. | |
395 | ||
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. | |
38a93523 NJ |
399 | |
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. | |
408 | ||
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. | |
414 | ||
38a93523 | 415 | Why must the caller do all the real work from @var{main_func}? Guile's |
ac3e3f5b MV |
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 | |
b45898ca | 419 | portable way in C to find the base of the stack, @code{scm_boot_guile} |
ac3e3f5b MV |
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. | |
425 | ||
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. | |
428 | @end deftypefun | |
429 | ||
430 | @deftypefun void scm_init_guile () | |
431 | Initialize the Guile Scheme interpreter. | |
432 | ||
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. | |
438 | ||
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 | |
7bb16613 | 441 | @code{command-line}. You can use @code{scm_set_program_arguments} to do |
ac3e3f5b | 442 | this. |
38a93523 NJ |
443 | @end deftypefun |
444 | ||
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. | |
450 | ||
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 | |
454 | function: | |
455 | ||
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. | |
462 | ||
463 | Since this function does not return, you must do all | |
464 | application-specific initialization before calling this function. | |
38a93523 NJ |
465 | @end deftypefun |
466 | ||
467 | ||
468 | @node A Sample Guile Main Program | |
469 | @subsection A Sample Guile Main Program | |
470 | ||
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 | |
473 | interpreter. | |
474 | ||
475 | @example | |
476 | /* simple-guile.c --- how to start up the Guile | |
477 | interpreter from C code. */ | |
478 | ||
479 | /* Get declarations for all the scm_ functions. */ | |
480 | #include <libguile.h> | |
481 | ||
482 | static void | |
483 | inner_main (void *closure, int argc, char **argv) | |
484 | @{ | |
485 | /* module initializations would go here */ | |
486 | scm_shell (argc, argv); | |
487 | @} | |
488 | ||
489 | int | |
490 | main (int argc, char **argv) | |
491 | @{ | |
492 | scm_boot_guile (argc, argv, inner_main, 0); | |
493 | return 0; /* never reached */ | |
494 | @} | |
495 | @end example | |
496 | ||
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. | |
501 | ||
ac3e3f5b MV |
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 | |
504 | linker flags. | |
38a93523 NJ |
505 | @example |
506 | # Use GCC, if you have it installed. | |
507 | CC=gcc | |
508 | ||
ac3e3f5b MV |
509 | # Tell the C compiler where to find <libguile.h> |
510 | CFLAGS=`guile-config compile` | |
38a93523 | 511 | |
ac3e3f5b MV |
512 | # Tell the linker what libraries to use and where to find them. |
513 | LIBS=`guile-config link` | |
38a93523 NJ |
514 | |
515 | simple-guile: simple-guile.o | |
ac3e3f5b MV |
516 | $@{CC@} simple-guile.o $@{LIBS@} -o simple-guile |
517 | ||
38a93523 NJ |
518 | simple-guile.o: simple-guile.c |
519 | $@{CC@} -c $@{CFLAGS@} simple-guile.c | |
520 | @end example | |
521 | ||
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 | |
ac3e3f5b MV |
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 | |
532 | when in doubt. | |
38a93523 NJ |
533 | @example |
534 | AC_INIT(simple-guile.c) | |
535 | ||
536 | # Find a C compiler. | |
537 | AC_PROG_CC | |
538 | ||
ac3e3f5b MV |
539 | # Check for Guile |
540 | GUILE_FLAGS | |
38a93523 NJ |
541 | |
542 | # Generate a Makefile, based on the results. | |
543 | AC_OUTPUT(Makefile) | |
544 | @end example | |
545 | ||
546 | Here is a @code{Makefile.in} template, from which the @code{configure} | |
547 | script produces a Makefile customized for the host system: | |
548 | @example | |
549 | # The configure script fills in these values. | |
550 | CC=@@CC@@ | |
ac3e3f5b MV |
551 | CFLAGS=@@GUILE_CFLAGS@@ |
552 | LIBS=@@GUILE_LDFLAGS@@ | |
38a93523 NJ |
553 | |
554 | simple-guile: simple-guile.o | |
ac3e3f5b | 555 | $@{CC@} simple-guile.o $@{LIBS@} -o simple-guile |
38a93523 NJ |
556 | simple-guile.o: simple-guile.c |
557 | $@{CC@} -c $@{CFLAGS@} simple-guile.c | |
558 | @end example | |
559 | ||
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: | |
564 | ||
565 | @example | |
566 | $ ls | |
567 | Makefile.in configure* configure.in simple-guile.c | |
568 | $ ./configure | |
569 | creating cache ./config.cache | |
ac3e3f5b | 570 | checking for gcc... (cached) gcc |
38a93523 NJ |
571 | checking whether the C compiler (gcc ) works... yes |
572 | checking whether the C compiler (gcc ) is a cross-compiler... no | |
ac3e3f5b MV |
573 | checking whether we are using GNU C... (cached) yes |
574 | checking whether gcc accepts -g... (cached) yes | |
575 | checking for Guile... yes | |
38a93523 NJ |
576 | creating ./config.status |
577 | creating Makefile | |
578 | $ make | |
ac3e3f5b MV |
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 | |
38a93523 NJ |
581 | $ ./simple-guile |
582 | guile> (+ 1 2 3) | |
583 | 6 | |
584 | guile> (getpwnam "jimb") | |
585 | #("jimb" "83Z7d75W2tyJQ" 4008 10 "Jim Blandy" "/u/jimb" | |
586 | "/usr/local/bin/bash") | |
587 | guile> (exit) | |
5134bfa7 | 588 | $ |
38a93523 NJ |
589 | @end example |
590 | ||
9401323e | 591 | |
ac3e3f5b MV |
592 | @node Writing Extensions for Guile |
593 | @section Writing Extensions for Guile | |
594 | ||
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 | |
8d009ee4 | 600 | users of your new features needlessly hard. |
ac3e3f5b | 601 | |
7bb16613 | 602 | @c [[ the following is probably a bit long-winded ]] |
ac3e3f5b MV |
603 | |
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 | |
7bb16613 | 612 | application that uses a GUI to let the user access a database? You |
ac3e3f5b MV |
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 | |
617 | practice. | |
618 | ||
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 | |
623 | possible. | |
624 | ||
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 | |
7bb16613 | 627 | stand-alone program. The shared library can then be loaded dynamically |
ac3e3f5b MV |
628 | by Guile. |
629 | ||
630 | @menu | |
5134bfa7 | 631 | * A Sample Guile Extension:: |
ac3e3f5b MV |
632 | @end menu |
633 | ||
9401323e | 634 | |
ac3e3f5b MV |
635 | @node A Sample Guile Extension |
636 | @subsection A Sample Guile Extension | |
637 | ||
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 | |
b45898ca | 643 | only implement this for the @code{j0} function. |
ac3e3f5b MV |
644 | |
645 | Consider the following file @file{bessel.c}. | |
646 | ||
647 | @smallexample | |
648 | #include <math.h> | |
649 | #include <libguile.h> | |
650 | ||
651 | SCM | |
652 | j0_wrapper (SCM x) | |
653 | @{ | |
654 | return scm_make_real (j0 (scm_num2dbl (x, "j0"))); | |
655 | @} | |
656 | ||
657 | void | |
658 | init_bessel () | |
659 | @{ | |
be8dd118 | 660 | scm_c_define_gsubr ("j0", 1, 0, 0, j0_wrapper); |
ac3e3f5b MV |
661 | @} |
662 | @end smallexample | |
663 | ||
664 | This C source file needs to be compiled into a shared library. Here is | |
665 | how to do it on GNU/Linux: | |
666 | ||
667 | @smallexample | |
668 | gcc -shared -o libguile-bessel.so -fPIC bessel.c | |
669 | @end smallexample | |
670 | ||
671 | For creating shared libraries portably, we recommend the use of | |
672 | @code{GNU Libtool}. | |
673 | ||
be8dd118 MV |
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. | |
ac3e3f5b MV |
683 | |
684 | @smalllisp | |
be8dd118 | 685 | (load-extension "libguile-bessel" "init_bessel") |
ac3e3f5b MV |
686 | (j0 2) |
687 | @result{} 0.223890779141236 | |
688 | @end smalllisp | |
689 | ||
be8dd118 MV |
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 | |
85a9b4ed | 693 | into the directories listed in the @code{LTDL_LIBRARY_PATH} |
be8dd118 | 694 | environment variable. |
ac3e3f5b MV |
695 | |
696 | To see how these Guile extensions via shared libraries relate to the | |
92905faf | 697 | module system, see below @xref{Intro to Modules and Extensions}. |
38a93523 | 698 | |
9401323e | 699 | |
95a62aed MV |
700 | @node Guile Modules |
701 | @section Guile Modules | |
38a93523 | 702 | |
ac3e3f5b | 703 | Guile has support for dividing a program into @dfn{modules}. By using |
95a62aed MV |
704 | modules, you can group related code together and manage the |
705 | composition of complete programs from largely independent parts. | |
ac3e3f5b | 706 | |
c71375c9 | 707 | (Although the module system implementation is in flux, feel free to use it |
7bb16613 | 708 | anyway. Guile will provide reasonable backwards compatibility.) |
c71375c9 TTN |
709 | |
710 | Details on the module system beyond this introductory material can be found in | |
711 | @xref{Modules}. | |
712 | ||
95a62aed | 713 | @menu |
c71375c9 TTN |
714 | * Intro to Using Guile Modules:: |
715 | * Intro to Writing New Modules:: | |
716 | * Intro to Modules and Extensions:: | |
95a62aed MV |
717 | @end menu |
718 | ||
9401323e | 719 | |
c71375c9 TTN |
720 | @node Intro to Using Guile Modules |
721 | @subsection Intro to Using Existing Modules | |
95a62aed | 722 | |
2da0d971 MG |
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 | |
726 | installed manually. | |
727 | ||
728 | Existing modules have to be placed in places where Guile looks for them | |
5134bfa7 TTN |
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: | |
733 | ||
734 | @smallexample | |
be8dd118 | 735 | guile -c '(write %load-path) (newline)' |
5134bfa7 | 736 | @end smallexample |
2da0d971 MG |
737 | |
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 | |
b45898ca | 741 | currently running Guile REPL or the top of your script file. |
2da0d971 MG |
742 | |
743 | @lisp | |
744 | (use-modules (ice-9 popen)) | |
745 | @end lisp | |
746 | ||
747 | This will load the module and make the procedures exported by | |
4310df36 MV |
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. | |
2da0d971 MG |
753 | |
754 | @lisp | |
4310df36 | 755 | (use-modules (ice-9 rdelim)) |
2da0d971 MG |
756 | (define p (open-input-pipe "ls -l")) |
757 | (read-line p) | |
758 | @result{} | |
759 | "total 30" | |
760 | (read-line p) | |
761 | @result{} | |
762 | "drwxr-sr-x 2 mgrabmue mgrabmue 1024 Mar 29 19:57 CVS" | |
763 | @end lisp | |
764 | ||
4310df36 MV |
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 | |
767 | in the code above as | |
768 | ||
769 | @lisp | |
770 | (use-modules (ice-9 popen) (ice-9 rdelim)) | |
771 | @end lisp | |
2da0d971 | 772 | |
c71375c9 TTN |
773 | @node Intro to Writing New Modules |
774 | @subsection Intro to Writing New Modules | |
95a62aed | 775 | |
2da0d971 MG |
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. | |
781 | ||
7bb16613 | 782 | In Guile, you can create new modules and switch to existing modules in |
2da0d971 MG |
783 | order to add bindings to them using the syntactic form |
784 | @code{define-module}. | |
785 | ||
786 | @lisp | |
787 | (define-module (foo bar)) | |
788 | ||
789 | (define (frob x) x) | |
790 | @end lisp | |
791 | ||
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 | |
799 | means: | |
800 | ||
801 | @itemize @bullet | |
802 | @item | |
803 | Export them with the @code{export} form: | |
804 | @lisp | |
805 | (export frob) | |
806 | @end lisp | |
807 | ||
808 | @item | |
809 | Include them into the @code{define-module} form with the keyword | |
810 | @code{export}: | |
811 | @lisp | |
812 | (define-module (foo bar) | |
813 | #:export (frob)) | |
814 | @end lisp | |
815 | ||
816 | @item | |
817 | Change the definition of @code{frob} to use @code{define-public}, which | |
818 | is a combination of @code{define} and @code{export}. | |
819 | @lisp | |
820 | (define-public (frob x) x) | |
821 | @end lisp | |
822 | @end itemize | |
823 | ||
824 | After exporting, other modules can access the exported items simply by | |
825 | using @code{use-modules} to load the module @code{(foo bar)}. | |
826 | ||
95a62aed | 827 | |
c71375c9 TTN |
828 | @node Intro to Modules and Extensions |
829 | @subsection Intro to Modules and Extensions | |
95a62aed | 830 | |
be8dd118 MV |
831 | In addition to Scheme code you can also put things that are defined in |
832 | C into a module. | |
95a62aed MV |
833 | |
834 | You do this by writing a small Scheme file that defines the module. | |
be8dd118 MV |
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. | |
95a62aed MV |
840 | |
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 | |
844 | ||
845 | @smallexample | |
846 | (define-module (math bessel)) | |
847 | ||
be8dd118 MV |
848 | (export j0) |
849 | ||
850 | (load-extension "libguile-bessel" "init_bessel") | |
95a62aed MV |
851 | @end smallexample |
852 | ||
be8dd118 MV |
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}. | |
856 | ||
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. | |
860 | ||
861 | The definitions made in the C code are not automatically exported from | |
b45898ca | 862 | a module. You need to explicitly list the ones you want to export in |
be8dd118 MV |
863 | @code{export} statements or with the @code{:export} option of |
864 | @code{define-module}. | |
38a93523 | 865 | |
be8dd118 MV |
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. | |
c71375c9 | 869 | |
9401323e NJ |
870 | |
871 | @page | |
872 | @node Obtaining and Installing Guile | |
873 | @chapter Obtaining and Installing Guile | |
874 | ||
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. | |
877 | ||
878 | @menu | |
7bb16613 TTN |
879 | * The Basic Guile Package:: |
880 | * Packages not shipped with Guile:: | |
9401323e NJ |
881 | @end menu |
882 | ||
883 | ||
884 | @node The Basic Guile Package | |
885 | @section The Basic Guile Package | |
886 | ||
887 | Guile can be obtained from the main GNU archive site | |
6e63303d | 888 | @url{ftp://ftp.gnu.org} or any of its mirrors. The file |
9401323e NJ |
889 | will be named guile-version.tar.gz. The current version is |
890 | @value{VERSION}, so the file you should grab is: | |
891 | ||
6e63303d | 892 | @url{ftp://ftp.gnu.org/pub/gnu/guile-@value{VERSION}.tar.gz} |
9401323e NJ |
893 | |
894 | To unbundle Guile use the instruction | |
6e63303d | 895 | |
9401323e NJ |
896 | @example |
897 | zcat guile-@value{VERSION}.tar.gz | tar xvf - | |
898 | @end example | |
6e63303d | 899 | |
9401323e NJ |
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 | |
903 | to just do | |
6e63303d | 904 | |
9401323e NJ |
905 | @example |
906 | cd guile-@value{VERSION} | |
907 | ./configure | |
6e63303d | 908 | make |
9401323e NJ |
909 | make install |
910 | @end example | |
911 | ||
912 | This will install the Guile executable @file{guile}, the Guile library | |
6e63303d MV |
913 | @file{-lguile} and various associated header files and support |
914 | libraries. It will also install the Guile tutorial and reference | |
915 | manual. | |
9401323e NJ |
916 | |
917 | @c [[include instructions for getting R5RS]] | |
918 | ||
919 | Since this manual frequently refers to the Scheme ``standard'', also | |
920 | known as R5RS, or the | |
921 | @iftex | |
922 | ``Revised$^5$ Report on the Algorithmic Language Scheme'', | |
923 | @end iftex | |
801892e7 | 924 | @ifnottex |
9401323e | 925 | ``Revised^5 Report on the Algorithmic Language Scheme'', |
801892e7 | 926 | @end ifnottex |
9401323e NJ |
927 | we have included the report in the Guile distribution; |
928 | @xref{Top, , Introduction, r5rs, Revised(5) Report on the Algorithmic | |
929 | Language Scheme}. | |
930 | This will also be installed in your info directory. | |
931 | ||
932 | ||
933 | @node Packages not shipped with Guile | |
934 | @section Packages not shipped with Guile | |
935 | ||
936 | We ship the Guile tutorial and reference manual with the Guile | |
937 | distribution. Since the Scheme standard (R5RS) is a stable document, we | |
938 | ship that too. | |
939 | ||
940 | Here are references (usually World Wide Web URLs) to some other freely | |
941 | redistributable documents and packages which you might find useful if | |
942 | you are using Guile. | |
943 | ||
944 | @table @strong | |
945 | @item SCSH | |
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. | |
949 | ||
950 | @item SLIB | |
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/}. | |
953 | ||
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}. | |
957 | ||
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: | |
960 | ||
961 | @smalllisp | |
962 | guile> %load-path | |
963 | ("/usr/local/share/guile/site" "/usr/local/share/guile/1.3a" "/usr/local/share/guile" ".") | |
964 | @end smalllisp | |
965 | ||
966 | The relevant chapter (@pxref{SLIB}) has details on how to use SLIB with | |
967 | Guile. | |
968 | ||
969 | @item JACAL | |
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}. | |
974 | ||
975 | The relevant section (@pxref{JACAL}) has details on how to use Jacal. | |
976 | @end table | |
977 | ||
978 | ||
38a93523 NJ |
979 | @page |
980 | @node Reporting Bugs | |
981 | @chapter Reporting Bugs | |
982 | ||
983 | Any problems with the installation should be reported to | |
984 | @email{bug-guile@@gnu.org}. | |
985 | ||
2da0d971 | 986 | Whenever you have found a bug in Guile you are encouraged to report it |
5134bfa7 | 987 | to the Guile developers, so they can fix it. They may also be able to |
7bb16613 | 988 | suggest workarounds when it is not possible for you to apply the bug-fix |
5134bfa7 | 989 | or install a new version of Guile yourself. |
2da0d971 MG |
990 | |
991 | Before sending in bug reports, please check with the following list that | |
992 | you really have found a bug. | |
993 | ||
994 | @itemize @bullet | |
995 | @item | |
7bb16613 | 996 | Whenever documentation and actual behavior differ, you have certainly |
2da0d971 MG |
997 | found a bug, either in the documentation or in the program. |
998 | ||
999 | @item | |
1000 | When Guile crashes, it is a bug. | |
1001 | ||
1002 | @item | |
1003 | When Guile hangs or takes forever to complete a task, it is a bug. | |
1004 | ||
1005 | @item | |
1006 | When calculations produce wrong results, it is a bug. | |
1007 | ||
1008 | @item | |
1009 | When Guile signals an error for valid Scheme programs, it is a bug. | |
1010 | ||
1011 | @item | |
2da0d971 MG |
1012 | When Guile does not signal an error for invalid Scheme programs, it may |
1013 | be a bug, unless this is explicitly documented. | |
1014 | ||
1015 | @item | |
1016 | When some part of the documentation is not clear and does not make sense | |
fb02eb66 | 1017 | to you even after re-reading the section, it is a bug. |
2da0d971 MG |
1018 | @end itemize |
1019 | ||
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 | |
5134bfa7 | 1023 | more likely we can diagnose and fix the bug. |
2da0d971 MG |
1024 | |
1025 | @itemize @bullet | |
1026 | @item | |
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. | |
1029 | ||
1030 | You can get the version number by invoking the command | |
1031 | ||
1032 | @example | |
1033 | $ guile --version | |
1034 | Guile 1.4.1 | |
1035 | Copyright (c) 1995, 1996, 1997, 2000 Free Software Foundation | |
7bb16613 | 1036 | Guile may be distributed under the terms of the GNU General Public License; |
2da0d971 MG |
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. | |
1040 | @end example | |
1041 | ||
1042 | @item | |
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}. | |
1045 | ||
1046 | @example | |
1047 | $ uname -a | |
1048 | Linux tortoise 2.2.17 #1 Thu Dec 21 17:29:05 CET 2000 i586 unknown | |
1049 | @end example | |
1050 | ||
1051 | @item | |
1052 | The operands given to the @file{configure} command when Guile was | |
5134bfa7 TTN |
1053 | installed. It's often useful to augment this with the output of the |
1054 | command @code{guile-config info}. | |
2da0d971 MG |
1055 | |
1056 | @item | |
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.) | |
1061 | ||
1062 | Be precise about these changes. A description in English is not | |
fb02eb66 | 1063 | enough---send a context diff for them. |
2da0d971 MG |
1064 | |
1065 | Adding files of your own, or porting to another machine, is a | |
1066 | modification of the source. | |
1067 | ||
1068 | @item | |
1069 | Details of any other deviations from the standard procedure for | |
1070 | installing Guile. | |
1071 | ||
1072 | @item | |
1073 | The complete text of any source files needed to reproduce the bug. | |
1074 | ||
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. | |
1078 | ||
1079 | @item | |
1080 | The precise Guile invocation command line we need to type to reproduce | |
1081 | the bug. | |
1082 | ||
1083 | @item | |
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." | |
1087 | ||
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? | |
1091 | ||
b45898ca | 1092 | If the manifestation of the bug is a Guile error message, it is |
2da0d971 MG |
1093 | important to report the precise text of the error message, and a |
1094 | backtrace showing how the Scheme program arrived at the error. | |
1095 | ||
1096 | This can be done using the procedure @code{backtrace} in the REPL. | |
1097 | ||
1098 | @item | |
1099 | Check whether any programs you have loaded into Guile, including your | |
5134bfa7 | 1100 | @file{.guile} file, set any variables that may affect the functioning of |
2da0d971 | 1101 | Guile. Also, see whether the problem happens in a freshly started Guile |
5134bfa7 TTN |
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 | |
1106 | occur. | |
2da0d971 MG |
1107 | |
1108 | @item | |
b45898ca | 1109 | If the problem does depend on an init file or other Scheme programs that |
2da0d971 MG |
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. | |
1114 | ||
1115 | @item | |
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. | |
1118 | ||
b45898ca | 1119 | The line numbers in the development sources might not match those in your |
2da0d971 MG |
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 | |
1122 | certain. | |
1123 | ||
1124 | @item | |
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. | |
fb02eb66 | 1127 | If you don't know how to use GDB, please read the GDB manual---it is not |
2da0d971 MG |
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 | |
5134bfa7 | 1131 | switch to the @file{libguile} subdirectory in which Guile was compiled, then |
b45898ca | 1132 | do @code{gdb guile} or @code{gdb .libs/guile} (if using GNU Libtool). |
2da0d971 MG |
1133 | |
1134 | However, you need to think when you collect the additional information | |
1135 | if you want it to show what causes the bug. | |
1136 | ||
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). | |
1144 | @end itemize | |
1145 | ||
38a93523 NJ |
1146 | |
1147 | ||
1148 | @c Local Variables: | |
1149 | @c TeX-master: "guile.texi" | |
1150 | @c End: |