diff --git a/doc/ref/tour.texi b/doc/ref/tour.texi index 3ccb4f2c6..41a8e8054 100644 --- a/doc/ref/tour.texi +++ b/doc/ref/tour.texi @@ -34,20 +34,20 @@ In its simplest form, Guile acts as an interactive interpreter for the Scheme programming language, reading and evaluating Scheme expressions the user enters from the terminal. Here is a sample interaction between Guile and a user; the user's input appears after the @code{$} and -@code{guile>} prompts: +@code{scheme@@(guile-user)>} prompts: @example $ guile -guile> (+ 1 2 3) ; add some numbers -6 -guile> (define (factorial n) ; define a function +scheme@@(guile-user)> (+ 1 2 3) ; add some numbers +$1 = 6 +scheme@@(guile-user)> (define (factorial n) ; define a function (if (zero? n) 1 (* n (factorial (- n 1))))) -guile> (factorial 20) -2432902008176640000 -guile> (getpwnam "jimb") ; find my entry in /etc/passwd -#("jimb" ".0krIpK2VqNbU" 4008 10 "Jim Blandy" "/u/jimb" +scheme@@(guile-user)> (factorial 20) +$2 = 2432902008176640000 +scheme@@(guile-user)> (getpwnam "jimb") ; find my entry in /etc/passwd +$3 = ("jimb" ".0krIpK2VqNbU" 4008 10 "Jim Blandy" "/u/jimb" "/usr/local/bin/bash") -guile> @kbd{C-d} +scheme@@(guile-user)> @kbd{C-d} $ @end example @@ -124,9 +124,9 @@ that you can also call the new @code{my-hostname} function. @example $ ./simple-guile -guile> (+ 1 2 3) -6 -guile> (my-hostname) +scheme@@(guile-user)> (+ 1 2 3) +$1 = 6 +scheme@@(guile-user)> (my-hostname) "burns" @end example @@ -176,9 +176,9 @@ available: @smallexample $ guile -guile> (load-extension "./libguile-bessel" "init_bessel") -guile> (j0 2) -0.223890779141236 +scheme@@(guile-user)> (load-extension "./libguile-bessel" "init_bessel") +scheme@@(guile-user)> (j0 2) +$1 = 0.223890779141236 @end smallexample @@ -217,13 +217,13 @@ rdelim)} module that provides the function @code{read-line}. @smallexample $ guile -guile> (use-modules (ice-9 popen)) -guile> (use-modules (ice-9 rdelim)) -guile> (define p (open-input-pipe "ls -l")) -guile> (read-line p) -"total 30" -guile> (read-line p) -"drwxr-sr-x 2 mgrabmue mgrabmue 1024 Mar 29 19:57 CVS" +scheme@@(guile-user)> (use-modules (ice-9 popen)) +scheme@@(guile-user)> (use-modules (ice-9 rdelim)) +scheme@@(guile-user)> (define p (open-input-pipe "ls -l")) +scheme@@(guile-user)> (read-line p) +$1 = "total 30" +scheme@@(guile-user)> (read-line p) +$2 = "drwxr-sr-x 2 mgrabmue mgrabmue 1024 Mar 29 19:57 CVS" @end smallexample @node Writing new Modules @@ -246,9 +246,9 @@ $ cat /usr/local/share/guile/foo/bar.scm (define (frob x) (* 2 x)) $ guile -guile> (use-modules (foo bar)) -guile> (frob 12) -24 +scheme@@(guile-user)> (use-modules (foo bar)) +scheme@@(guile-user)> (frob 12) +$1 = 24 @end smallexample @node Putting Extensions into Modules @@ -271,9 +271,9 @@ $ cat /usr/local/share/guile/math/bessel.scm $ file /usr/local/lib/libguile-bessel.so @dots{} ELF 32-bit LSB shared object @dots{} $ guile -guile> (use-modules (math bessel)) -guile> (j0 2) -0.223890779141236 +scheme@@(guile-user)> (use-modules (math bessel)) +scheme@@(guile-user)> (j0 2) +$1 = 0.223890779141236 @end smallexample There is also a way to manipulate the module system from C but only @@ -288,10 +288,10 @@ your modules in Scheme. Any problems with the installation should be reported to @email{bug-guile@@gnu.org}. -Whenever you have found a bug in Guile you are encouraged to report it -to the Guile developers, so they can fix it. They may also be able to -suggest workarounds when it is not possible for you to apply the bug-fix -or install a new version of Guile yourself. +If you find a bug in Guile, please report it to the Guile developers, so +they can fix it. They may also be able to suggest workarounds when it +is not possible for you to apply the bug-fix or install a new version of +Guile yourself. Before sending in bug reports, please check with the following list that you really have found a bug. @@ -322,6 +322,15 @@ When some part of the documentation is not clear and does not make sense to you even after re-reading the section, it is a bug. @end itemize +Before reporting the bug, check whether any programs you have loaded +into Guile, including your @file{.guile} file, set any variables that +may affect the functioning of Guile. Also, see whether the problem +happens in a freshly started Guile without loading your @file{.guile} +file (start Guile with the @code{-q} switch to prevent loading the init +file). If the problem does @emph{not} occur then, you must report the +precise contents of any programs that you must load into Guile in order +to cause the problem to occur. + When you write a bug report, please make sure to include as much of the information described below in the report. If you can't figure out some of the items, it is not a problem, but the more information we get, the @@ -329,126 +338,64 @@ more likely we can diagnose and fix the bug. @itemize @bullet @item -The version number of Guile. Without this, we won't know whether there -is any point in looking for the bug in the current version of Guile. +The version number of Guile. You can get this information from invoking +@samp{guile --version} at your shell, or calling @code{(version)} from +within Guile. -You can get the version number by invoking the command +@item +Your machine type, as determined by the @code{config.guess} shell +script. If you have a Guile checkout, this file is located in +@code{build-aux}; otherwise you can fetch the latest version from +@uref{http://git.savannah.gnu.org/gitweb/?p=config.git;a=blob_plain;f=config.guess;hb=HEAD}. @example -$ guile --version -Guile 1.9.0 -Copyright (c) 1995, 1996, 1997, 2000, 2001, 2002, 2003, 2004, -2005, 2006, 2007, 2008, 2009 Free Software Foundation -Guile may be distributed under the terms of the GNU Lesser General -Public Licence. For details, see the files `COPYING.LESSER' and -`COPYING', which are included in the Guile distribution. There is -no warranty, to the extent permitted by law. +$ build-aux/config.guess +x86_64-unknown-linux-gnu @end example @item -The type of machine you are using, and the operating system name and -version number. On GNU systems, you can get it with @file{uname}. +If you installed Guile from a binary package, the version of that +package. On systems that use RPM, use @code{rpm -qa | grep guile}. On systems +that use DPKG, @code{dpkg -l | grep guile}. + +@item +If you built Guile yourself, the build configuration that you used: @example -$ uname -a -Linux tortoise 2.2.17 #1 Thu Dec 21 17:29:05 CET 2000 i586 unknown +$ ./config.status --config +'--enable-error-on-warning' '--disable-deprecated' '--prefix=/opt/guile' '--libdir=/opt/guile/lib64' 'CC=ccache gcc' @end example @item -The operands given to the @file{configure} command when Guile was -installed. It's often useful to augment this with the output of the -command @code{guile-config info}. +A complete description of how to reproduce the bug. + +If you have a Scheme program that produces the bug, please include it in +the bug report. If your program is too big to include. please try to +reduce your code to a minimal test case. + +If you can reproduce your problem at the REPL, that is best. Give a +transcript of the expressions you typed at the REPL. @item -A complete list of any modifications you have made to the Guile source. -(We may not have time to investigate the bug unless it happens in an -unmodified Guile. But if you've made modifications and you don't tell -us, you are sending us on a wild goose chase.) - -Be precise about these changes. A description in English is not -enough---send a context diff for them. - -Adding files of your own, or porting to another machine, is a -modification of the source. - -@item -Details of any other deviations from the standard procedure for -installing Guile. - -@item -The complete text of any source files needed to reproduce the bug. - -If you can tell us a way to cause the problem without loading any source -files, please do so. This makes it much easier to debug. If you do -need files, make sure you arrange for us to see their exact contents. - -@item -The precise Guile invocation command line we need to type to reproduce -the bug. - -@item -A description of what behavior you observe that you believe is -incorrect. For example, "The Guile process gets a fatal signal," or, -"The resulting output is as follows, which I think is wrong." - -Of course, if the bug is that Guile gets a fatal signal, then one can't -miss it. But if the bug is incorrect results, the maintainer might fail -to notice what is wrong. Why leave it to chance? +A description of the incorrect behavior. For example, "The Guile +process gets a fatal signal," or, "The resulting output is as follows, +which I think is wrong." If the manifestation of the bug is a Guile error message, it is important to report the precise text of the error message, and a -backtrace showing how the Scheme program arrived at the error. - -This can be done using the @code{backtrace} command in Guile's debugger. - -@item -Check whether any programs you have loaded into Guile, including your -@file{.guile} file, set any variables that may affect the functioning of -Guile. Also, see whether the problem happens in a freshly started Guile -without loading your @file{.guile} file (start Guile with the @code{-q} -switch to prevent loading the init file). If the problem does -@emph{not} occur then, you must report the precise contents of any -programs that you must load into Guile in order to cause the problem to -occur. - -@item -If the problem does depend on an init file or other Scheme programs that -are not part of the standard Guile distribution, then you should make -sure it is not a bug in those programs by complaining to their -maintainers first. After they verify that they are using Guile in a way -that is supposed to work, they should report the bug. - -@item -If you wish to mention something in the Guile source, show the line of -code with a few lines of context. Don't just give a line number. - -The line numbers in the development sources might not match those in your -sources. It would take extra work for the maintainers to determine what -code is in your version at a given line number, and we could not be -certain. - -@item -Additional information from a C debugger such as GDB might enable -someone to find a problem on a machine which he does not have available. -If you don't know how to use GDB, please read the GDB manual---it is not -very long, and using GDB is easy. You can find the GDB distribution, -including the GDB manual in online form, in most of the same places you -can find the Guile distribution. To run Guile under GDB, you should -switch to the @file{libguile} subdirectory in which Guile was compiled, then -do @code{gdb guile} or @code{gdb .libs/guile} (if using GNU Libtool). - -However, you need to think when you collect the additional information -if you want it to show what causes the bug. - -For example, many people send just a backtrace, but that is not very -useful by itself. A simple backtrace with arguments often conveys -little about what is happening inside Guile, because most of the -arguments listed in the backtrace are pointers to Scheme objects. The -numeric values of these pointers have no significance whatever; all that -matters is the contents of the objects they point to (and most of the -contents are themselves pointers). +backtrace showing how the Scheme program arrived at the error. This can +be done using the @code{,backtrace} command in Guile's debugger. @end itemize +If your bug causes Guile to crash, additional information from a +low-level debugger such as GDB might be helpful. If you have built Guile +yourself, you can run Guile under GDB via the +@code{meta/gdb-uninstalled-guile} script. Instead of invoking Guile as +usual, invoke the wrapper script, type @code{run} to start the process, +then @code{backtrace} when the crash comes. Include that backtrace in +your report. + + @c Local Variables: @c TeX-master: "guile.texi"