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