Commit | Line | Data |
---|---|---|
2da09c3f MV |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Guile Reference Manual. | |
5f30c653 | 3 | @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006 |
2da09c3f MV |
4 | @c Free Software Foundation, Inc. |
5 | @c See the file guile.texi for copying conditions. | |
6 | ||
3229f68b MV |
7 | @node Introduction to Guile |
8 | @chapter Introduction to Guile | |
9 | ||
10 | @menu | |
11 | * What is Guile?:: | |
12 | * Obtaining and Installing Guile:: | |
13 | * Whirlwind Tour:: | |
235da338 | 14 | * Discouraged and Deprecated:: |
064f84ae | 15 | * Manual Conventions:: |
3229f68b MV |
16 | * Reporting Bugs:: |
17 | @end menu | |
18 | ||
38a93523 | 19 | @node What is Guile? |
3229f68b | 20 | @section What is Guile? |
38a93523 NJ |
21 | |
22 | Guile is an interpreter for the Scheme programming language, packaged | |
23 | for use in a wide variety of environments. Guile implements Scheme as | |
24 | described in the | |
25 | @tex | |
26 | Revised$^5$ | |
27 | @end tex | |
801892e7 | 28 | @ifnottex |
38a93523 | 29 | Revised^5 |
801892e7 | 30 | @end ifnottex |
01b30204 | 31 | Report on the Algorithmic Language Scheme (usually known as @acronym{R5RS}), |
38a93523 | 32 | providing clean and general data and control structures. Guile goes |
01b30204 MV |
33 | beyond the rather austere language presented in @acronym{R5RS}, extending it with |
34 | a module system, full access to @acronym{POSIX} system calls, networking support, | |
38a93523 NJ |
35 | multiple threads, dynamic linking, a foreign function call interface, |
36 | powerful string processing, and many other features needed for | |
37 | programming in the real world. | |
38 | ||
39 | Like a shell, Guile can run interactively, reading expressions from the | |
40 | user, evaluating them, and displaying the results, or as a script | |
41 | interpreter, reading and executing Scheme code from a file. However, | |
42 | Guile is also packaged as an object library, allowing other applications | |
43 | to easily incorporate a complete Scheme interpreter. An application can | |
01b30204 | 44 | then use Guile as an extension language, a clean and powerful configuration |
38a93523 NJ |
45 | language, or as multi-purpose ``glue'', connecting primitives provided |
46 | by the application. It is easy to call Scheme code from C code and vice | |
47 | versa, giving the application designer full control of how and when to | |
48 | invoke the interpreter. Applications can add new functions, data types, | |
49 | control structures, and even syntax to Guile, creating a domain-specific | |
50 | language tailored to the task at hand, but based on a robust language | |
51 | design. | |
52 | ||
53 | Guile's module system allows one to break up a large program into | |
01b30204 MV |
54 | manageable sections with well-defined interfaces between them. |
55 | Modules may contain a mixture of interpreted and compiled code; Guile | |
56 | can use either static or dynamic linking to incorporate compiled code. | |
57 | Modules also encourage developers to package up useful collections of | |
58 | routines for general distribution; as of this writing, one can find | |
59 | Emacs interfaces, database access routines, compilers, @acronym{GUI} | |
60 | toolkit interfaces, and @acronym{HTTP} client functions, among others. | |
38a93523 NJ |
61 | |
62 | In the future, we hope to expand Guile to support other languages like | |
63 | Tcl and Perl by translating them to Scheme code. This means that users | |
64 | can program applications which use Guile in the language of their | |
65 | choice, rather than having the tastes of the application's author | |
66 | imposed on them. | |
67 | ||
3229f68b MV |
68 | @node Obtaining and Installing Guile |
69 | @section Obtaining and Installing Guile | |
70 | ||
71 | Guile can be obtained from the main GNU archive site | |
72 | @url{ftp://ftp.gnu.org} or any of its mirrors. The file will be named | |
73 | guile-version.tar.gz. The current version is @value{VERSION}, so the | |
74 | file you should grab is: | |
75 | ||
d746e18e | 76 | @url{ftp://ftp.gnu.org/pub/gnu/guile/guile-@value{VERSION}.tar.gz} |
3229f68b MV |
77 | |
78 | To unbundle Guile use the instruction | |
79 | ||
80 | @example | |
81 | zcat guile-@value{VERSION}.tar.gz | tar xvf - | |
82 | @end example | |
83 | ||
31c73458 | 84 | @noindent |
3229f68b MV |
85 | which will create a directory called @file{guile-@value{VERSION}} with |
86 | all the sources. You can look at the file @file{INSTALL} for detailed | |
87 | instructions on how to build and install Guile, but you should be able | |
88 | to just do | |
89 | ||
90 | @example | |
91 | cd guile-@value{VERSION} | |
92 | ./configure | |
93 | make | |
94 | make install | |
95 | @end example | |
96 | ||
97 | This will install the Guile executable @file{guile}, the Guile library | |
31c73458 | 98 | @file{libguile} and various associated header files and support |
3229f68b MV |
99 | libraries. It will also install the Guile tutorial and reference |
100 | manual. | |
101 | ||
102 | @c [[include instructions for getting R5RS]] | |
103 | ||
104 | Since this manual frequently refers to the Scheme ``standard'', also | |
105 | known as R5RS, or the | |
31c73458 | 106 | @tex |
3229f68b | 107 | ``Revised$^5$ Report on the Algorithmic Language Scheme'', |
31c73458 | 108 | @end tex |
3229f68b MV |
109 | @ifnottex |
110 | ``Revised^5 Report on the Algorithmic Language Scheme'', | |
111 | @end ifnottex | |
31c73458 NJ |
112 | we have included the report in the Guile distribution; see |
113 | @ref{Top, , Introduction, r5rs, Revised(5) Report on the Algorithmic | |
3229f68b MV |
114 | Language Scheme}. |
115 | This will also be installed in your info directory. | |
9401323e | 116 | |
38a93523 | 117 | @node Whirlwind Tour |
3229f68b | 118 | @section A Whirlwind Tour |
38a93523 NJ |
119 | |
120 | This chapter presents a quick tour of all the ways that Guile can be | |
cc772cf8 MV |
121 | used. There are additional examples in the @file{examples/} |
122 | directory in the Guile source distribution. | |
38a93523 | 123 | |
3229f68b MV |
124 | The following examples assume that Guile has been installed in |
125 | @code{/usr/local/}. | |
126 | ||
38a93523 | 127 | @menu |
5134bfa7 | 128 | * Running Guile Interactively:: |
3229f68b MV |
129 | * Running Guile Scripts:: |
130 | * Linking Guile into Programs:: | |
131 | * Writing Guile Extensions:: | |
132 | * Using the Guile Module System:: | |
38a93523 NJ |
133 | @end menu |
134 | ||
135 | ||
136 | @node Running Guile Interactively | |
3229f68b | 137 | @subsection Running Guile Interactively |
38a93523 NJ |
138 | |
139 | In its simplest form, Guile acts as an interactive interpreter for the | |
140 | Scheme programming language, reading and evaluating Scheme expressions | |
141 | the user enters from the terminal. Here is a sample interaction between | |
142 | Guile and a user; the user's input appears after the @code{$} and | |
143 | @code{guile>} prompts: | |
144 | ||
145 | @example | |
146 | $ guile | |
147 | guile> (+ 1 2 3) ; add some numbers | |
148 | 6 | |
149 | guile> (define (factorial n) ; define a function | |
150 | (if (zero? n) 1 (* n (factorial (- n 1))))) | |
151 | guile> (factorial 20) | |
152 | 2432902008176640000 | |
153 | guile> (getpwnam "jimb") ; find my entry in /etc/passwd | |
154 | #("jimb" ".0krIpK2VqNbU" 4008 10 "Jim Blandy" "/u/jimb" | |
155 | "/usr/local/bin/bash") | |
156 | guile> @kbd{C-d} | |
157 | $ | |
158 | @end example | |
159 | ||
38a93523 | 160 | |
3229f68b MV |
161 | @node Running Guile Scripts |
162 | @subsection Running Guile Scripts | |
38a93523 NJ |
163 | |
164 | Like AWK, Perl, or any shell, Guile can interpret script files. A Guile | |
165 | script is simply a file of Scheme code with some extra information at | |
166 | the beginning which tells the operating system how to invoke Guile, and | |
167 | then tells Guile how to handle the Scheme code. | |
168 | ||
3229f68b | 169 | Here is a trivial Guile script, for more details @xref{Guile Scripting}. |
38a93523 NJ |
170 | |
171 | @example | |
172 | #!/usr/local/bin/guile -s | |
173 | !# | |
174 | (display "Hello, world!") | |
175 | (newline) | |
176 | @end example | |
177 | ||
38a93523 | 178 | |
3229f68b MV |
179 | @node Linking Guile into Programs |
180 | @subsection Linking Guile into Programs | |
38a93523 NJ |
181 | |
182 | The Guile interpreter is available as an object library, to be linked | |
183 | into applications using Scheme as a configuration or extension | |
3229f68b | 184 | language. |
38a93523 | 185 | |
3229f68b MV |
186 | Here is @file{simple-guile.c}, source code for a program that will |
187 | produce a complete Guile interpreter. In addition to all usual | |
188 | functions provided by Guile, it will also offer the function | |
189 | @code{my-hostname}. | |
38a93523 NJ |
190 | |
191 | @example | |
3229f68b | 192 | #include <stdlib.h> |
38a93523 NJ |
193 | #include <libguile.h> |
194 | ||
3229f68b MV |
195 | static SCM |
196 | my_hostname (void) | |
197 | @{ | |
23f2b9a3 KR |
198 | char *s = getenv ("HOSTNAME"); |
199 | if (s == NULL) | |
200 | return SCM_BOOL_F; | |
201 | else | |
202 | return scm_from_locale_string (s); | |
3229f68b MV |
203 | @} |
204 | ||
38a93523 | 205 | static void |
3229f68b | 206 | inner_main (void *data, int argc, char **argv) |
38a93523 | 207 | @{ |
3229f68b | 208 | scm_c_define_gsubr ("my-hostname", 0, 0, 0, my_hostname); |
38a93523 NJ |
209 | scm_shell (argc, argv); |
210 | @} | |
211 | ||
212 | int | |
213 | main (int argc, char **argv) | |
214 | @{ | |
215 | scm_boot_guile (argc, argv, inner_main, 0); | |
216 | return 0; /* never reached */ | |
217 | @} | |
218 | @end example | |
219 | ||
3229f68b MV |
220 | When Guile is correctly installed on your system, the above program |
221 | can be compiled and linked like this: | |
38a93523 | 222 | |
38a93523 | 223 | @example |
3229f68b | 224 | $ gcc -o simple-guile simple-guile.c -lguile |
38a93523 NJ |
225 | @end example |
226 | ||
3229f68b MV |
227 | When it is run, it behaves just like the @code{guile} program except |
228 | that you can also call the new @code{my-hostname} function. | |
38a93523 | 229 | |
38a93523 | 230 | @example |
38a93523 NJ |
231 | $ ./simple-guile |
232 | guile> (+ 1 2 3) | |
233 | 6 | |
3229f68b MV |
234 | guile> (my-hostname) |
235 | "burns" | |
38a93523 NJ |
236 | @end example |
237 | ||
3229f68b MV |
238 | @node Writing Guile Extensions |
239 | @subsection Writing Guile Extensions | |
9401323e | 240 | |
3229f68b MV |
241 | You can link Guile into your program and make Scheme available to the |
242 | users of your program. You can also link your library into Guile and | |
243 | make its functionality available to all users of Guile. | |
ac3e3f5b | 244 | |
3229f68b MV |
245 | A library that is linked into Guile is called an @dfn{extensions}, but |
246 | it really just is an ordinary object library. | |
ac3e3f5b | 247 | |
3229f68b MV |
248 | The following example shows how to write a simple extension for Guile |
249 | that makes the @code{j0} function available to Scheme code. | |
ac3e3f5b MV |
250 | |
251 | @smallexample | |
252 | #include <math.h> | |
253 | #include <libguile.h> | |
254 | ||
255 | SCM | |
256 | j0_wrapper (SCM x) | |
257 | @{ | |
258 | return scm_make_real (j0 (scm_num2dbl (x, "j0"))); | |
259 | @} | |
260 | ||
261 | void | |
262 | init_bessel () | |
263 | @{ | |
be8dd118 | 264 | scm_c_define_gsubr ("j0", 1, 0, 0, j0_wrapper); |
ac3e3f5b MV |
265 | @} |
266 | @end smallexample | |
267 | ||
268 | This C source file needs to be compiled into a shared library. Here is | |
269 | how to do it on GNU/Linux: | |
270 | ||
271 | @smallexample | |
272 | gcc -shared -o libguile-bessel.so -fPIC bessel.c | |
273 | @end smallexample | |
274 | ||
5f30c653 KR |
275 | For creating shared libraries portably, we recommend the use of GNU |
276 | Libtool (@pxref{Top, , Introduction, libtool, GNU Libtool}). | |
ac3e3f5b | 277 | |
be8dd118 | 278 | A shared library can be loaded into a running Guile process with the |
3229f68b MV |
279 | function @code{load-extension}. The @code{j0} is then immediately |
280 | available: | |
ac3e3f5b | 281 | |
3229f68b MV |
282 | @smallexample |
283 | $ guile | |
284 | guile> (load-extension "./libguile-bessel" "init_bessel") | |
285 | guile> (j0 2) | |
286 | 0.223890779141236 | |
287 | @end smallexample | |
38a93523 | 288 | |
9401323e | 289 | |
3229f68b MV |
290 | @node Using the Guile Module System |
291 | @subsection Using the Guile Module System | |
38a93523 | 292 | |
ac3e3f5b | 293 | Guile has support for dividing a program into @dfn{modules}. By using |
95a62aed MV |
294 | modules, you can group related code together and manage the |
295 | composition of complete programs from largely independent parts. | |
ac3e3f5b | 296 | |
c71375c9 | 297 | (Although the module system implementation is in flux, feel free to use it |
7bb16613 | 298 | anyway. Guile will provide reasonable backwards compatibility.) |
c71375c9 TTN |
299 | |
300 | Details on the module system beyond this introductory material can be found in | |
301 | @xref{Modules}. | |
302 | ||
95a62aed | 303 | @menu |
3229f68b MV |
304 | * Using Modules:: |
305 | * Writing new Modules:: | |
306 | * Putting Extensions into Modules:: | |
95a62aed MV |
307 | @end menu |
308 | ||
9401323e | 309 | |
3229f68b MV |
310 | @node Using Modules |
311 | @subsubsection Using Modules | |
95a62aed | 312 | |
2da0d971 MG |
313 | Guile comes with a lot of useful modules, for example for string |
314 | processing or command line parsing. Additionally, there exist many | |
315 | Guile modules written by other Guile hackers, but which have to be | |
316 | installed manually. | |
317 | ||
3229f68b MV |
318 | Here is a sample interactive session that shows how to use the |
319 | @code{(ice-9 popen)} module which provides the means for communicating | |
320 | with other processes over pipes together with the @code{(ice-9 | |
321 | rdelim)} module that provides the function @code{read-line}. | |
5134bfa7 TTN |
322 | |
323 | @smallexample | |
3229f68b MV |
324 | $ guile |
325 | guile> (use-modules (ice-9 popen)) | |
326 | guile> (use-modules (ice-9 rdelim)) | |
327 | guile> (define p (open-input-pipe "ls -l")) | |
328 | guile> (read-line p) | |
2da0d971 | 329 | "total 30" |
3229f68b | 330 | guile> (read-line p) |
2da0d971 | 331 | "drwxr-sr-x 2 mgrabmue mgrabmue 1024 Mar 29 19:57 CVS" |
3229f68b | 332 | @end smallexample |
4310df36 | 333 | |
3229f68b MV |
334 | @node Writing new Modules |
335 | @subsubsection Writing new Modules | |
2da0d971 | 336 | |
3229f68b MV |
337 | You can create new modules using the syntactic form |
338 | @code{define-module}. All definitions following this form until the | |
339 | next @code{define-module} are placed into the new module. | |
95a62aed | 340 | |
3229f68b MV |
341 | One module is usually placed into one file, and that file is installed |
342 | in a location where Guile can automatically find it. The following | |
343 | session shows a simple example. | |
2da0d971 | 344 | |
3229f68b MV |
345 | @smallexample |
346 | $ cat /usr/local/share/guile/foo/bar.scm | |
2da0d971 | 347 | |
2da0d971 | 348 | (define-module (foo bar)) |
2da0d971 | 349 | (export frob) |
2da0d971 | 350 | |
3229f68b | 351 | (define (frob x) (* 2 x)) |
2da0d971 | 352 | |
3229f68b MV |
353 | $ guile |
354 | guile> (use-modules (foo bar)) | |
355 | guile> (frob 12) | |
356 | 24 | |
357 | @end smallexample | |
95a62aed | 358 | |
3229f68b MV |
359 | @node Putting Extensions into Modules |
360 | @subsubsection Putting Extensions into Modules | |
95a62aed | 361 | |
be8dd118 MV |
362 | In addition to Scheme code you can also put things that are defined in |
363 | C into a module. | |
95a62aed | 364 | |
3229f68b MV |
365 | You do this by writing a small Scheme file that defines the module and |
366 | call @code{load-extension} directly in the body of the module. | |
95a62aed MV |
367 | |
368 | @smallexample | |
3229f68b | 369 | $ cat /usr/local/share/guile/math/bessel.scm |
95a62aed | 370 | |
3229f68b | 371 | (define-module (math bessel)) |
be8dd118 MV |
372 | (export j0) |
373 | ||
374 | (load-extension "libguile-bessel" "init_bessel") | |
95a62aed | 375 | |
3229f68b MV |
376 | $ file /usr/local/lib/libguile-bessel.so |
377 | @dots{} ELF 32-bit LSB shared object @dots{} | |
378 | $ guile | |
379 | guile> (use-modules (math bessel)) | |
380 | guile> (j0 2) | |
381 | 0.223890779141236 | |
382 | @end smallexample | |
38a93523 | 383 | |
be8dd118 MV |
384 | There is also a way to manipulate the module system from C but only |
385 | Scheme files can be autoloaded. Thus, we recommend that you define | |
386 | your modules in Scheme. | |
c71375c9 | 387 | |
235da338 MV |
388 | @node Discouraged and Deprecated |
389 | @section Discouraged and Deprecated | |
390 | ||
391 | From time to time functions and other features of Guile become | |
392 | obsolete. Guile has some mechanisms in place that can help you cope | |
393 | with this. | |
394 | ||
395 | Guile has two levels of obsoleteness: things can be @emph{deprecated}, | |
396 | meaning that their use is considered harmful and should be avoided, | |
397 | even in old code; or they can be merely @emph{discouraged}, meaning | |
398 | that they are fine in and of themselves, but that there are better | |
399 | alternatives that should be used in new code. | |
400 | ||
401 | When you use a feature that is deprecated, you will likely get a | |
402 | warning message at run-time. Also, deprecated features are not ready | |
403 | for production use: they might be very slow. When something is merely | |
404 | discouraged, it performs normally and you wont get any messages at | |
405 | run-time. | |
406 | ||
407 | The primary source for information about just what things are | |
408 | discouraged or deprecated in a given release is the file | |
409 | @file{NEWS}. That file also documents what you should use instead | |
410 | of the obsoleted things. | |
411 | ||
412 | The file @file{README} contains instructions on how to control the | |
413 | inclusion or removal of the deprecated and/or discouraged features | |
5aa76027 MV |
414 | from the public API of Guile, and how to control the warning messages |
415 | for deprecated features. | |
416 | ||
417 | The idea behind those mechanisms is that normally all deprecated and | |
418 | discouraged features are available, but that you can omit them on | |
419 | purpose to check whether your code still relies on them. | |
235da338 | 420 | |
064f84ae NJ |
421 | @node Manual Conventions |
422 | @section Conventions used in this Manual | |
423 | ||
424 | We use some conventions in this manual. | |
425 | ||
426 | @itemize @bullet | |
427 | ||
428 | @item | |
429 | For some procedures, notably type predicates, we use ``iff'' to mean | |
430 | ``if and only if''. The construct is usually something like: `Return | |
431 | @var{val} iff @var{condition}', where @var{val} is usually | |
432 | ``@nicode{#t}'' or ``non-@nicode{#f}''. This typically means that | |
433 | @var{val} is returned if @var{condition} holds, and that @samp{#f} is | |
434 | returned otherwise. To clarify: @var{val} will @strong{only} be | |
435 | returned when @var{condition} is true. | |
436 | @cindex iff | |
437 | ||
438 | @item | |
439 | In examples and procedure descriptions and all other places where the | |
440 | evaluation of Scheme expression is shown, we use some notation for | |
441 | denoting the output and evaluation results of expressions. | |
442 | ||
443 | The symbol @samp{@result{}} is used to tell which value is returned by | |
444 | an evaluation: | |
445 | ||
446 | @lisp | |
447 | (+ 1 2) | |
448 | @result{} 3 | |
449 | @end lisp | |
450 | ||
451 | Some procedures produce some output besides returning a value. This | |
452 | is denoted by the symbol @samp{@print{}}. | |
453 | ||
454 | @lisp | |
455 | (begin (display 1) (newline) 'hooray) | |
456 | @print{} 1 | |
457 | @result{} hooray | |
458 | @end lisp | |
459 | ||
460 | As you can see, this code prints @samp{1} (denoted by | |
461 | @samp{@print{}}), and returns @code{hooray} (denoted by | |
462 | @samp{@result{}}). Do not confuse the two. | |
463 | ||
464 | @c Add other conventions here. | |
465 | ||
466 | @end itemize | |
467 | ||
38a93523 | 468 | @node Reporting Bugs |
3229f68b | 469 | @section Reporting Bugs |
38a93523 NJ |
470 | |
471 | Any problems with the installation should be reported to | |
9dfa64ca | 472 | @email{bug-guile@@gnu.org}. |
38a93523 | 473 | |
2da0d971 | 474 | Whenever you have found a bug in Guile you are encouraged to report it |
5134bfa7 | 475 | to the Guile developers, so they can fix it. They may also be able to |
7bb16613 | 476 | suggest workarounds when it is not possible for you to apply the bug-fix |
5134bfa7 | 477 | or install a new version of Guile yourself. |
2da0d971 MG |
478 | |
479 | Before sending in bug reports, please check with the following list that | |
480 | you really have found a bug. | |
481 | ||
482 | @itemize @bullet | |
483 | @item | |
7bb16613 | 484 | Whenever documentation and actual behavior differ, you have certainly |
2da0d971 MG |
485 | found a bug, either in the documentation or in the program. |
486 | ||
487 | @item | |
488 | When Guile crashes, it is a bug. | |
489 | ||
490 | @item | |
491 | When Guile hangs or takes forever to complete a task, it is a bug. | |
492 | ||
493 | @item | |
494 | When calculations produce wrong results, it is a bug. | |
495 | ||
496 | @item | |
497 | When Guile signals an error for valid Scheme programs, it is a bug. | |
498 | ||
499 | @item | |
2da0d971 MG |
500 | When Guile does not signal an error for invalid Scheme programs, it may |
501 | be a bug, unless this is explicitly documented. | |
502 | ||
503 | @item | |
504 | When some part of the documentation is not clear and does not make sense | |
fb02eb66 | 505 | to you even after re-reading the section, it is a bug. |
2da0d971 MG |
506 | @end itemize |
507 | ||
508 | When you write a bug report, please make sure to include as much of the | |
509 | information described below in the report. If you can't figure out some | |
510 | of the items, it is not a problem, but the more information we get, the | |
5134bfa7 | 511 | more likely we can diagnose and fix the bug. |
2da0d971 MG |
512 | |
513 | @itemize @bullet | |
514 | @item | |
515 | The version number of Guile. Without this, we won't know whether there | |
516 | is any point in looking for the bug in the current version of Guile. | |
517 | ||
518 | You can get the version number by invoking the command | |
519 | ||
520 | @example | |
521 | $ guile --version | |
53befeb7 | 522 | Guile 1.9.0 |
45867c2a NJ |
523 | Copyright (c) 1995, 1996, 1997, 2000, 2001, 2002, 2003, 2004, |
524 | 2005, 2006, 2007, 2008, 2009 Free Software Foundation | |
53befeb7 NJ |
525 | Guile may be distributed under the terms of the GNU Lesser General |
526 | Public Licence. For details, see the files `COPYING.LESSER' and | |
45867c2a NJ |
527 | `COPYING', which are included in the Guile distribution. There is |
528 | no warranty, to the extent permitted by law. | |
2da0d971 MG |
529 | @end example |
530 | ||
531 | @item | |
532 | The type of machine you are using, and the operating system name and | |
533 | version number. On GNU systems, you can get it with @file{uname}. | |
534 | ||
535 | @example | |
536 | $ uname -a | |
537 | Linux tortoise 2.2.17 #1 Thu Dec 21 17:29:05 CET 2000 i586 unknown | |
538 | @end example | |
539 | ||
540 | @item | |
541 | The operands given to the @file{configure} command when Guile was | |
5134bfa7 TTN |
542 | installed. It's often useful to augment this with the output of the |
543 | command @code{guile-config info}. | |
2da0d971 MG |
544 | |
545 | @item | |
546 | A complete list of any modifications you have made to the Guile source. | |
547 | (We may not have time to investigate the bug unless it happens in an | |
548 | unmodified Guile. But if you've made modifications and you don't tell | |
549 | us, you are sending us on a wild goose chase.) | |
550 | ||
551 | Be precise about these changes. A description in English is not | |
fb02eb66 | 552 | enough---send a context diff for them. |
2da0d971 MG |
553 | |
554 | Adding files of your own, or porting to another machine, is a | |
555 | modification of the source. | |
556 | ||
557 | @item | |
558 | Details of any other deviations from the standard procedure for | |
559 | installing Guile. | |
560 | ||
561 | @item | |
562 | The complete text of any source files needed to reproduce the bug. | |
563 | ||
564 | If you can tell us a way to cause the problem without loading any source | |
565 | files, please do so. This makes it much easier to debug. If you do | |
566 | need files, make sure you arrange for us to see their exact contents. | |
567 | ||
568 | @item | |
569 | The precise Guile invocation command line we need to type to reproduce | |
570 | the bug. | |
571 | ||
572 | @item | |
573 | A description of what behavior you observe that you believe is | |
574 | incorrect. For example, "The Guile process gets a fatal signal," or, | |
575 | "The resulting output is as follows, which I think is wrong." | |
576 | ||
577 | Of course, if the bug is that Guile gets a fatal signal, then one can't | |
578 | miss it. But if the bug is incorrect results, the maintainer might fail | |
579 | to notice what is wrong. Why leave it to chance? | |
580 | ||
b45898ca | 581 | If the manifestation of the bug is a Guile error message, it is |
2da0d971 MG |
582 | important to report the precise text of the error message, and a |
583 | backtrace showing how the Scheme program arrived at the error. | |
584 | ||
585 | This can be done using the procedure @code{backtrace} in the REPL. | |
586 | ||
587 | @item | |
588 | Check whether any programs you have loaded into Guile, including your | |
5134bfa7 | 589 | @file{.guile} file, set any variables that may affect the functioning of |
2da0d971 | 590 | Guile. Also, see whether the problem happens in a freshly started Guile |
5134bfa7 TTN |
591 | without loading your @file{.guile} file (start Guile with the @code{-q} |
592 | switch to prevent loading the init file). If the problem does | |
593 | @emph{not} occur then, you must report the precise contents of any | |
594 | programs that you must load into Guile in order to cause the problem to | |
595 | occur. | |
2da0d971 MG |
596 | |
597 | @item | |
b45898ca | 598 | If the problem does depend on an init file or other Scheme programs that |
2da0d971 MG |
599 | are not part of the standard Guile distribution, then you should make |
600 | sure it is not a bug in those programs by complaining to their | |
601 | maintainers first. After they verify that they are using Guile in a way | |
602 | that is supposed to work, they should report the bug. | |
603 | ||
604 | @item | |
605 | If you wish to mention something in the Guile source, show the line of | |
606 | code with a few lines of context. Don't just give a line number. | |
607 | ||
b45898ca | 608 | The line numbers in the development sources might not match those in your |
2da0d971 MG |
609 | sources. It would take extra work for the maintainers to determine what |
610 | code is in your version at a given line number, and we could not be | |
611 | certain. | |
612 | ||
613 | @item | |
614 | Additional information from a C debugger such as GDB might enable | |
615 | someone to find a problem on a machine which he does not have available. | |
fb02eb66 | 616 | If you don't know how to use GDB, please read the GDB manual---it is not |
2da0d971 MG |
617 | very long, and using GDB is easy. You can find the GDB distribution, |
618 | including the GDB manual in online form, in most of the same places you | |
619 | can find the Guile distribution. To run Guile under GDB, you should | |
5134bfa7 | 620 | switch to the @file{libguile} subdirectory in which Guile was compiled, then |
b45898ca | 621 | do @code{gdb guile} or @code{gdb .libs/guile} (if using GNU Libtool). |
2da0d971 MG |
622 | |
623 | However, you need to think when you collect the additional information | |
624 | if you want it to show what causes the bug. | |
625 | ||
626 | For example, many people send just a backtrace, but that is not very | |
627 | useful by itself. A simple backtrace with arguments often conveys | |
628 | little about what is happening inside Guile, because most of the | |
629 | arguments listed in the backtrace are pointers to Scheme objects. The | |
630 | numeric values of these pointers have no significance whatever; all that | |
631 | matters is the contents of the objects they point to (and most of the | |
632 | contents are themselves pointers). | |
633 | @end itemize | |
634 | ||
38a93523 NJ |
635 | |
636 | ||
637 | @c Local Variables: | |
638 | @c TeX-master: "guile.texi" | |
639 | @c End: |