mirror of
https://git.savannah.gnu.org/git/guile.git
synced 2025-04-30 03:40:34 +02:00
tour.texi updates
* doc/ref/tour.texi: Update Guile prompts for scheme@(guile-user)>. Update output to assume value-history is on. Lop and crop the bug reporting section -- it was too long.
This commit is contained in:
Andy Wingo
parent
3c0b7725ef
commit
04ca20430b
1 changed files with 81 additions and 134 deletions
|
|
@ -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"
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue