@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2010
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2010, 2011,
+@c 2012 Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@raisesections
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
- (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"
- "/usr/local/bin/bash")
-guile> @kbd{C-d}
+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)))))
+scheme@@(guile-user)> (factorial 20)
+$2 = 2432902008176640000
+scheme@@(guile-user)> (getpwnam "root") ; look in /etc/passwd
+$3 = #("root" "x" 0 0 "root" "/root" "/bin/bash")
+scheme@@(guile-user)> @kbd{C-d}
$
@end example
the beginning which tells the operating system how to invoke Guile, and
then tells Guile how to handle the Scheme code.
-Here is a trivial Guile script, for more details @xref{Guile Scripting}.
+Here is a trivial Guile script. @xref{Guile Scripting}, for more details.
@example
#!/usr/local/bin/guile -s
@example
$ gcc -o simple-guile simple-guile.c \
- `pkg-config --cflags --libs guile-2.0`
+ `pkg-config --cflags --libs guile-@value{EFFECTIVE-VERSION}`
@end example
When it is run, it behaves just like the @code{guile} program except
@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
users of your program. You can also link your library into Guile and
make its functionality available to all users of Guile.
-A library that is linked into Guile is called an @dfn{extensions}, but
-it really just is an ordinary object library.
+A library that is linked into Guile is called an @dfn{extension}, but it
+really just is an ordinary object library.
The following example shows how to write a simple extension for Guile
that makes the @code{j0} function available to Scheme code.
SCM
j0_wrapper (SCM x)
@{
- return scm_make_real (j0 (scm_num2dbl (x, "j0")));
+ return scm_from_double (j0 (scm_to_double (x)));
@}
void
how to do it on GNU/Linux:
@smallexample
-gcc -shared -o libguile-bessel.so -fPIC bessel.c
+gcc `pkg-config --cflags guile-@value{EFFECTIVE-VERSION}` \
+ -shared -o libguile-bessel.so -fPIC bessel.c
@end smallexample
For creating shared libraries portably, we recommend the use of GNU
@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
+For more on how to install your extension, @pxref{Installing Site
+Packages}.
+
@node Using the Guile Module System
@subsection Using the Guile Module System
modules, you can group related code together and manage the
composition of complete programs from largely independent parts.
-(Although the module system implementation is in flux, feel free to use it
-anyway. Guile will provide reasonable backwards compatibility.)
-
-Details on the module system beyond this introductory material can be found in
+For more details on the module system beyond this introductory material,
@xref{Modules}.
@menu
@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
session shows a simple example.
@smallexample
-$ cat /usr/local/share/guile/foo/bar.scm
+$ cat /usr/local/share/guile/site/foo/bar.scm
-(define-module (foo bar))
-(export frob)
+(define-module (foo bar)
+ #:export (frob))
(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
+For more on how to install your module, @pxref{Installing Site
+Packages}.
+
+
@node Putting Extensions into Modules
@subsubsection Putting Extensions into Modules
call @code{load-extension} directly in the body of the module.
@smallexample
-$ cat /usr/local/share/guile/math/bessel.scm
+$ cat /usr/local/share/guile/site/math/bessel.scm
-(define-module (math bessel))
-(export j0)
+(define-module (math bessel)
+ #:export (j0))
(load-extension "libguile-bessel" "init_bessel")
-$ file /usr/local/lib/libguile-bessel.so
+$ file /usr/local/lib/guile/@value{EFFECTIVE-VERSION}/extensions/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
-Scheme files can be autoloaded. Thus, we recommend that you define
-your modules in Scheme.
+@xref{Modules and Extensions}, for more information.
@lowersections
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.
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
@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.
-
-You can get the version number by invoking the command
-
-@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.
-@end example
+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.
@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}.
+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
-$ uname -a
-Linux tortoise 2.2.17 #1 Thu Dec 21 17:29:05 CET 2000 i586 unknown
+$ build-aux/config.guess
+x86_64-unknown-linux-gnu
@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}.
+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
-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.
+If you built Guile yourself, the build configuration that you used:
-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.
+@example
+$ ./config.status --config
+'--enable-error-on-warning' '--disable-deprecated'...
+@end example
@item
-The complete text of any source files needed to reproduce the bug.
+A complete description of how 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.
+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.
-@item
-The precise Guile invocation command line we need to type to reproduce
-the bug.
+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 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 procedure @code{backtrace} in the REPL.
-
-@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.
+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
-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.
+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.
-@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
@c Local Variables:
HCoop / bpt / guile.git / blobdiff