mirror/guile
mirror/guile
1
Fork 0
mirror of https://git.savannah.gnu.org/git/guile.git synced 2025-05-01 20:30:28 +02:00
Code Activity

tour.texi updates

Browse source 
* 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 2010-07-16 12:41:04 +02:00
parent 3c0b7725ef
commit 04ca20430b
1 changed files with 81 additions and 134 deletions
Download patch file Download diff file Expand all files Collapse all files

215
doc/ref/tour.texi
View file

@ -34,20 +34,20 @@ In its simplest form, Guile acts as an interactive interpreter for the
Scheme programming language, reading and evaluating Scheme expressions Scheme programming language, reading and evaluating Scheme expressions
the user enters from the terminal. Here is a sample interaction between 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 Guile and a user; the user's input appears after the @code{$} and
@code{guile>} prompts: @code{scheme@@(guile-user)>} prompts:
@example @example
$ guile $ guile
guile> (+ 1 2 3) ; add some numbers scheme@@(guile-user)> (+ 1 2 3) ; add some numbers
6 $1 = 6
guile> (define (factorial n) ; define a function scheme@@(guile-user)> (define (factorial n) ; define a function
(if (zero? n) 1 (* n (factorial (- n 1))))) (if (zero? n) 1 (* n (factorial (- n 1)))))
guile> (factorial 20) scheme@@(guile-user)> (factorial 20)
2432902008176640000 $2 = 2432902008176640000
guile> (getpwnam "jimb") ; find my entry in /etc/passwd scheme@@(guile-user)> (getpwnam "jimb") ; find my entry in /etc/passwd
#("jimb" ".0krIpK2VqNbU" 4008 10 "Jim Blandy" "/u/jimb" $3 = ("jimb" ".0krIpK2VqNbU" 4008 10 "Jim Blandy" "/u/jimb"
"/usr/local/bin/bash") "/usr/local/bin/bash")
guile> @kbd{C-d} scheme@@(guile-user)> @kbd{C-d}
$ $
@end example @end example
@ -124,9 +124,9 @@ that you can also call the new @code{my-hostname} function.
@example @example
$ ./simple-guile $ ./simple-guile
guile> (+ 1 2 3) scheme@@(guile-user)> (+ 1 2 3)
6 $1 = 6
guile> (my-hostname) scheme@@(guile-user)> (my-hostname)
"burns" "burns"
@end example @end example
@ -176,9 +176,9 @@ available:
@smallexample @smallexample
$ guile $ guile
guile> (load-extension "./libguile-bessel" "init_bessel") scheme@@(guile-user)> (load-extension "./libguile-bessel" "init_bessel")
guile> (j0 2) scheme@@(guile-user)> (j0 2)
0.223890779141236 $1 = 0.223890779141236
@end smallexample @end smallexample
@ -217,13 +217,13 @@ rdelim)} module that provides the function @code{read-line}.
@smallexample @smallexample
$ guile $ guile
guile> (use-modules (ice-9 popen)) scheme@@(guile-user)> (use-modules (ice-9 popen))
guile> (use-modules (ice-9 rdelim)) scheme@@(guile-user)> (use-modules (ice-9 rdelim))
guile> (define p (open-input-pipe "ls -l")) scheme@@(guile-user)> (define p (open-input-pipe "ls -l"))
guile> (read-line p) scheme@@(guile-user)> (read-line p)
"total 30" $1 = "total 30"
guile> (read-line p) scheme@@(guile-user)> (read-line p)
"drwxr-sr-x 2 mgrabmue mgrabmue 1024 Mar 29 19:57 CVS" $2 = "drwxr-sr-x 2 mgrabmue mgrabmue 1024 Mar 29 19:57 CVS"
@end smallexample @end smallexample
@node Writing new Modules @node Writing new Modules
@ -246,9 +246,9 @@ $ cat /usr/local/share/guile/foo/bar.scm
(define (frob x) (* 2 x)) (define (frob x) (* 2 x))
$ guile $ guile
guile> (use-modules (foo bar)) scheme@@(guile-user)> (use-modules (foo bar))
guile> (frob 12) scheme@@(guile-user)> (frob 12)
24 $1 = 24
@end smallexample @end smallexample
@node Putting Extensions into Modules @node Putting Extensions into Modules
@ -271,9 +271,9 @@ $ cat /usr/local/share/guile/math/bessel.scm
$ file /usr/local/lib/libguile-bessel.so $ file /usr/local/lib/libguile-bessel.so
@dots{} ELF 32-bit LSB shared object @dots{} @dots{} ELF 32-bit LSB shared object @dots{}
$ guile $ guile
guile> (use-modules (math bessel)) scheme@@(guile-user)> (use-modules (math bessel))
guile> (j0 2) scheme@@(guile-user)> (j0 2)
0.223890779141236 $1 = 0.223890779141236
@end smallexample @end smallexample
There is also a way to manipulate the module system from C but only 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 Any problems with the installation should be reported to
@email{bug-guile@@gnu.org}. @email{bug-guile@@gnu.org}.
Whenever you have found a bug in Guile you are encouraged to report it If you find a bug in Guile, please report it to the Guile developers, so
to the Guile developers, so they can fix it. They may also be able to they can fix it. They may also be able to suggest workarounds when it
suggest workarounds when it is not possible for you to apply the bug-fix is not possible for you to apply the bug-fix or install a new version of
or install a new version of Guile yourself. Guile yourself.
Before sending in bug reports, please check with the following list that Before sending in bug reports, please check with the following list that
you really have found a bug. 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. to you even after re-reading the section, it is a bug.
@end itemize @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 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 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 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 @itemize @bullet
@item @item
The version number of Guile. Without this, we won't know whether there The version number of Guile. You can get this information from invoking
is any point in looking for the bug in the current version of Guile. @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 @example
$ guile --version $ build-aux/config.guess
Guile 1.9.0 x86_64-unknown-linux-gnu
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.
@end example @end example
@item @item
The type of machine you are using, and the operating system name and If you installed Guile from a binary package, the version of that
version number. On GNU systems, you can get it with @file{uname}. 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 @example
$ uname -a $ ./config.status --config
Linux tortoise 2.2.17 #1 Thu Dec 21 17:29:05 CET 2000 i586 unknown '--enable-error-on-warning' '--disable-deprecated' '--prefix=/opt/guile' '--libdir=/opt/guile/lib64' 'CC=ccache gcc'
@end example @end example
@item @item
The operands given to the @file{configure} command when Guile was A complete description of how to reproduce the bug.
installed. It's often useful to augment this with the output of the
command @code{guile-config info}. 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 @item
A complete list of any modifications you have made to the Guile source. A description of the incorrect behavior. For example, "The Guile
(We may not have time to investigate the bug unless it happens in an process gets a fatal signal," or, "The resulting output is as follows,
unmodified Guile. But if you've made modifications and you don't tell which I think is wrong."
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?
If the manifestation of the bug is a Guile error message, it is 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 important to report the precise text of the error message, and a
backtrace showing how the Scheme program arrived at the error. backtrace showing how the Scheme program arrived at the error. This can
be done using the @code{,backtrace} command in Guile's debugger.
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).
@end itemize @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 Local Variables:
@c TeX-master: "guile.texi" @c TeX-master: "guile.texi"