summaryrefslogtreecommitdiff
path: root/doc/ref/intro.texi
diff options
context:
space:
mode:
Diffstat (limited to 'doc/ref/intro.texi')
-rw-r--r--doc/ref/intro.texi1023
1 files changed, 1023 insertions, 0 deletions
diff --git a/doc/ref/intro.texi b/doc/ref/intro.texi
new file mode 100644
index 000000000..28e30d06b
--- /dev/null
+++ b/doc/ref/intro.texi
@@ -0,0 +1,1023 @@
+@c $Id: intro.texi,v 1.1 2001-08-24 09:40:29 ossau Exp $
+
+@page
+@node What is Guile?
+@chapter What is Guile?
+
+Guile is an interpreter for the Scheme programming language, packaged
+for use in a wide variety of environments. Guile implements Scheme as
+described in the
+@tex
+Revised$^5$
+@end tex
+@ifinfo
+Revised^5
+@end ifinfo
+Report on the Algorithmic Language Scheme (usually known as R5RS),
+providing clean and general data and control structures. Guile goes
+beyond the rather austere language presented in R5RS, extending it with
+a module system, full access to POSIX system calls, networking support,
+multiple threads, dynamic linking, a foreign function call interface,
+powerful string processing, and many other features needed for
+programming in the real world.
+
+Like a shell, Guile can run interactively, reading expressions from the
+user, evaluating them, and displaying the results, or as a script
+interpreter, reading and executing Scheme code from a file. However,
+Guile is also packaged as an object library, allowing other applications
+to easily incorporate a complete Scheme interpreter. An application can
+use Guile as an extension language, a clean and powerful configuration
+language, or as multi-purpose ``glue'', connecting primitives provided
+by the application. It is easy to call Scheme code from C code and vice
+versa, giving the application designer full control of how and when to
+invoke the interpreter. Applications can add new functions, data types,
+control structures, and even syntax to Guile, creating a domain-specific
+language tailored to the task at hand, but based on a robust language
+design.
+
+Guile's module system allows one to break up a large program into
+manageable sections with well-defined interfaces between them. Modules
+may contain a mixture of interpreted and compiled code; Guile can use
+either static or dynamic linking to incorporate compiled code. Modules
+also encourage developers to package up useful collections of routines
+for general distribution; as of this writing, one can find Emacs
+interfaces, database access routines, compilers, GUI toolkit interfaces,
+and HTTP client functions, among others.
+
+In the future, we hope to expand Guile to support other languages like
+Tcl and Perl by translating them to Scheme code. This means that users
+can program applications which use Guile in the language of their
+choice, rather than having the tastes of the application's author
+imposed on them.
+
+@page
+@node Whirlwind Tour
+@chapter A Whirlwind Tour
+
+This chapter presents a quick tour of all the ways that Guile can be
+used.
+
+@menu
+* Running Guile Interactively::
+* Guile Scripts::
+* Linking Programs With Guile::
+* Writing Extensions for Guile::
+* Guile Modules::
+@end menu
+
+
+@node Running Guile Interactively
+@section Running Guile Interactively
+
+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:
+
+@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}
+$
+@end example
+
+@c [[When we get a fancier read-eval-print loop, with features for bouncing
+@c around among modules, referring to the value of the last expression,
+@c etc. then this section will get longer.]]
+
+
+@node Guile Scripts
+@section Guile Scripts
+
+Like AWK, Perl, or any shell, Guile can interpret script files. A Guile
+script is simply a file of Scheme code with some extra information at
+the beginning which tells the operating system how to invoke Guile, and
+then tells Guile how to handle the Scheme code.
+
+Before we present the details, here is a trivial Guile script:
+
+@example
+#!/usr/local/bin/guile -s
+!#
+(display "Hello, world!")
+(newline)
+@end example
+
+@menu
+* The Top of a Script File:: How to start a Guile script.
+* Scripting Examples:: Simple Guile scripts, explained.
+@end menu
+
+
+@node The Top of a Script File
+@subsection The Top of a Script File
+
+The first line of a Guile script must tell the operating system to use
+Guile to evaluate the script, and then tell Guile how to go about doing
+that. Here is the simplest case:
+
+@itemize @bullet
+
+@item
+The first two characters of the file must be @samp{#!}.
+
+The operating system interprets this to mean that the rest of the line
+is the name of an executable that can interpret the script. Guile,
+however, interprets these characters as the beginning of a multi-line
+comment, terminated by the characters @samp{!#} on a line by themselves.
+(This is an extension to the syntax described in R5RS, added to support
+shell scripts.)
+
+@item
+Immediately after those two characters must come the full pathname to
+the Guile interpreter. On most systems, this would be
+@samp{/usr/local/bin/guile}.
+
+@item
+Then must come a space, followed by a command-line argument to pass to
+Guile; this should be @samp{-s}. This switch tells Guile to run a
+script, instead of soliciting the user for input from the terminal.
+There are more elaborate things one can do here; see @ref{The Meta
+Switch}.
+
+@item
+Follow this with a newline.
+
+@item
+The second line of the script should contain only the characters
+@samp{!#} --- just like the top of the file, but reversed. The
+operating system never reads this far, but Guile treats this as the end
+of the comment begun on the first line by the @samp{#!} characters.
+
+@item
+The rest of the file should be a Scheme program.
+
+@end itemize
+
+Guile reads the program, evaluating expressions in the order that they
+appear. Upon reaching the end of the file, Guile exits.
+
+The function @code{command-line} returns the name of the script file and
+any command-line arguments passed by the user, as a list of strings.
+
+For example, consider the following script file:
+@example
+#!/usr/local/bin/guile -s
+!#
+(write (command-line))
+(newline)
+@end example
+
+If you put that text in a file called @file{foo} in the current
+directory, then you could make it executable and try it out like this:
+@example
+$ chmod a+x foo
+$ ./foo
+("./foo")
+$ ./foo bar baz
+("./foo" "bar" "baz")
+$
+@end example
+
+As another example, here is a simple replacement for the POSIX
+@code{echo} command:
+@example
+#!/usr/local/bin/guile -s
+!#
+(for-each (lambda (s) (display s) (display " "))
+ (cdr (command-line)))
+(newline)
+@end example
+
+@deffn procedure command-line
+@deffnx primitive program-arguments
+Return a list of the command-line arguments passed to the currently
+running program. If the program invoked Guile with the @samp{-s},
+@samp{-c} or @samp{--} switches, these procedures ignore everything up
+to and including those switches.
+@end deffn
+
+
+@node Scripting Examples
+@subsection Scripting Examples
+
+To start with, here are some examples of invoking Guile directly:
+
+@table @code
+
+@item guile -- a b c
+Run Guile interactively; @code{(command-line)} will return @*
+@code{("/usr/local/bin/guile" "a" "b" "c")}.
+
+@item guile -s /u/jimb/ex2 a b c
+Load the file @file{/u/jimb/ex2}; @code{(command-line)} will return @*
+@code{("/u/jimb/ex2" "a" "b" "c")}.
+
+@item guile -c '(write %load-path) (newline)'
+Write the value of the variable @code{%load-path}, print a newline,
+and exit.
+
+@item guile -e main -s /u/jimb/ex4 foo
+Load the file @file{/u/jimb/ex4}, and then call the function
+@code{main}, passing it the list @code{("/u/jimb/ex4" "foo")}.
+
+@item guile -l first -ds -l last -s script
+Load the files @file{first}, @file{script}, and @file{last}, in that
+order. The @code{-ds} switch says when to process the @code{-s}
+switch. For a more motivated example, see the scripts below.
+
+@end table
+
+
+Here is a very simple Guile script:
+@example
+#!/usr/local/bin/guile -s
+!#
+(display "Hello, world!")
+(newline)
+@end example
+The first line marks the file as a Guile script. When the user invokes
+it, the system runs @file{/usr/local/bin/guile} to interpret the script,
+passing @code{-s}, the script's filename, and any arguments given to the
+script as command-line arguments. When Guile sees @code{-s
+@var{script}}, it loads @var{script}. Thus, running this program
+produces the output:
+@example
+Hello, world!
+@end example
+
+Here is a script which prints the factorial of its argument:
+@example
+#!/usr/local/bin/guile -s
+!#
+(define (fact n)
+ (if (zero? n) 1
+ (* n (fact (- n 1)))))
+
+(display (fact (string->number (cadr (command-line)))))
+(newline)
+@end example
+In action:
+@example
+$ fact 5
+120
+$
+@end example
+
+However, suppose we want to use the definition of @code{fact} in this
+file from another script. We can't simply @code{load} the script file,
+and then use @code{fact}'s definition, because the script will try to
+compute and display a factorial when we load it. To avoid this problem,
+we might write the script this way:
+
+@example
+#!/usr/local/bin/guile \
+-e main -s
+!#
+(define (fact n)
+ (if (zero? n) 1
+ (* n (fact (- n 1)))))
+
+(define (main args)
+ (display (fact (string->number (cadr args))))
+ (newline))
+@end example
+This version packages the actions the script should perform in a
+function, @code{main}. This allows us to load the file purely for its
+definitions, without any extraneous computation taking place. Then we
+used the meta switch @code{\} and the entry point switch @code{-e} to
+tell Guile to call @code{main} after loading the script.
+@example
+$ fact 50
+30414093201713378043612608166064768844377641568960512000000000000
+@end example
+
+Suppose that we now want to write a script which computes the
+@code{choose} function: given a set of @var{m} distinct objects,
+@code{(choose @var{n} @var{m})} is the number of distinct subsets
+containing @var{n} objects each. It's easy to write @code{choose} given
+@code{fact}, so we might write the script this way:
+@example
+#!/usr/local/bin/guile \
+-l fact -e main -s
+!#
+(define (choose n m)
+ (/ (fact m) (* (fact (- m n)) (fact n))))
+
+(define (main args)
+ (let ((n (string->number (cadr args)))
+ (m (string->number (caddr args))))
+ (display (choose n m))
+ (newline)))
+@end example
+
+The command-line arguments here tell Guile to first load the file
+@file{fact}, and then run the script, with @code{main} as the entry
+point. In other words, the @code{choose} script can use definitions
+made in the @code{fact} script. Here are some sample runs:
+@example
+$ choose 0 4
+1
+$ choose 1 4
+4
+$ choose 2 4
+6
+$ choose 3 4
+4
+$ choose 4 4
+1
+$ choose 50 100
+100891344545564193334812497256
+@end example
+
+
+@node Linking Programs With Guile
+@section Linking Programs With Guile
+
+The Guile interpreter is available as an object library, to be linked
+into applications using Scheme as a configuration or extension
+language. This chapter covers the mechanics of linking your program
+with Guile on a typical POSIX system.
+
+Parts III and IV of this manual describe the C functions Guile provides.
+Furthermore, any Scheme function described in this manual as a
+``Primitive'' is also callable from C; see @ref{Scheme Primitives}.
+
+The header file @code{<libguile.h>} provides declarations for all of
+Guile's functions and constants. You should @code{#include} it at the
+head of any C source file that uses identifiers described in this
+manual. Once you've compiled your source files, you need to link them
+against the Guile object code library, @code{libguile}.
+
+On most systems, you should not need to do tell the compiler and linker
+explicitely where they can find @file{libguile.h} and @file{libguile}.
+When Guile has been installed in a peculiar way, or when you are on a
+peculiar system, things might not be so easy and you might need to pass
+additional @code{-I} or @code{-L} options to the compiler. Guile
+provides the utility program @code{guile-config} to help you find the
+right values for these options. You would typically run
+@code{guile-config} during the configuration phase of your program and
+use the obtained information in the Makefile.
+
+@menu
+* Guile Initialization Functions:: What to call first.
+* A Sample Guile Main Program:: Sources and makefiles.
+@end menu
+
+
+@node Guile Initialization Functions
+@subsection Guile Initialization Functions
+
+To initialize Guile, you can use one of two functions. The first,
+@code{scm_boot_guile}, is the most portable way to initialize Guile. It
+should be used whenever you have control over the main function of your
+program because it never returns. The second function,
+@code{scm_init_guile}, does return and can thus be used in more
+situations. However, @code{scm_init_guile} is not as widely available
+as @code{scm_boot_guile} because it needs to rely on non-portable code
+to find the stack bounds. When Guile does not know how to find these
+bounds on your system, it will not provide @code{scm_init_guile}.
+
+When you can tolerate the limits of @code{scm_boot_guile}, you should
+use it in favor of @code{scm_init_guile} since that will make your
+program more portable.
+
+@deftypefun void scm_boot_guile (int @var{argc}, char **@var{argv}, void (*@var{main_func}) (), void *@var{closure})
+Initialize the Guile Scheme interpreter. Then call @var{main_func},
+passing it @var{closure}, @var{argc}, and @var{argv}. @var{main_func}
+should do all the work of the program (initializing other packages,
+defining application-specific functions, reading user input, and so on)
+before returning. When @var{main_func} returns, call @code{exit (0)};
+@code{scm_boot_guile} never returns. If you want some other exit value,
+have @var{main_func} call exit itself.
+
+@code{scm_boot_guile} arranges for the Scheme @code{command-line}
+function to return the strings given by @var{argc} and @var{argv}. If
+@var{main_func} modifies @var{argc} or @var{argv}, it should call
+@code{scm_set_program_arguments} with the final list, so Scheme code
+will know which arguments have been processed.
+
+Why must the caller do all the real work from @var{main_func}? Guile's
+garbage collector scans the stack to find all local variables that
+reference Scheme objects. To do this, it needs to know the bounds of
+the stack that might contain such references. Because there is no
+protable way in C to find the base of the stack, @code{scm_boot_guile}
+assumes that all references are above its own stack frame. If you try
+to manipulate Scheme objects after this function returns, it's the luck
+of the draw whether Guile's storage manager will be able to find the
+objects you allocate. So, @code{scm_boot_guile} function exits, rather
+than returning, to discourage you from making that mistake.
+
+See @code{scm_init_guile}, below, for a function that can find the real
+base of the stack, but not in a portable way.
+@end deftypefun
+
+@deftypefun void scm_init_guile ()
+Initialize the Guile Scheme interpreter.
+
+In contrast to @code{scm_boot_guile}, this function knows how to find
+the true base of the stack and thus does not need to usurp the control
+flow of your program. However, since finding the stack base can not be
+done portably, this function might not be available in all installations
+of Guile. If you can, you should use @code{scm_boot_guile} instead.
+
+Note that @code{scm_init_guile} does not inform Guile about the command
+line arguments that should be returned by the Scheme function
+@code{comamnd-line}. You can use @code{scm_set_program_arguments} to do
+this.
+@end deftypefun
+
+One common way to use Guile is to write a set of C functions which
+perform some useful task, make them callable from Scheme, and then link
+the program with Guile. This yields a Scheme interpreter just like
+@code{guile}, but augmented with extra functions for some specific
+application --- a special-purpose scripting language.
+
+In this situation, the application should probably process its
+command-line arguments in the same manner as the stock Guile
+interpreter. To make that straightforward, Guile provides this
+function:
+
+@deftypefun void scm_shell (int @var{argc}, char **@var{argv})
+Process command-line arguments in the manner of the @code{guile}
+executable. This includes loading the normal Guile initialization
+files, interacting with the user or running any scripts or expressions
+specified by @code{-s} or @code{-e} options, and then exiting.
+@xref{Invoking Guile}, for more details.
+
+Since this function does not return, you must do all
+application-specific initialization before calling this function.
+@end deftypefun
+
+
+@node A Sample Guile Main Program
+@subsection A Sample Guile Main Program
+
+Here is @file{simple-guile.c}, source code for a @code{main} and an
+@code{inner_main} function that will produce a complete Guile
+interpreter.
+
+@example
+/* simple-guile.c --- how to start up the Guile
+ interpreter from C code. */
+
+/* Get declarations for all the scm_ functions. */
+#include <libguile.h>
+
+static void
+inner_main (void *closure, int argc, char **argv)
+@{
+ /* module initializations would go here */
+ scm_shell (argc, argv);
+@}
+
+int
+main (int argc, char **argv)
+@{
+ scm_boot_guile (argc, argv, inner_main, 0);
+ return 0; /* never reached */
+@}
+@end example
+
+The @code{main} function calls @code{scm_boot_guile} to initialize
+Guile, passing it @code{inner_main}. Once @code{scm_boot_guile} is
+ready, it invokes @code{inner_main}, which calls @code{scm_shell} to
+process the command-line arguments in the usual way.
+
+Here is a Makefile which you can use to compile the above program. It
+uses @code{guile-config} to learn about the necessary compiler and
+linker flags.
+@example
+# Use GCC, if you have it installed.
+CC=gcc
+
+# Tell the C compiler where to find <libguile.h>
+CFLAGS=`guile-config compile`
+
+# Tell the linker what libraries to use and where to find them.
+LIBS=`guile-config link`
+
+simple-guile: simple-guile.o
+ $@{CC@} simple-guile.o $@{LIBS@} -o simple-guile
+
+simple-guile.o: simple-guile.c
+ $@{CC@} -c $@{CFLAGS@} simple-guile.c
+@end example
+
+If you are using the GNU Autoconf package to make your application more
+portable, Autoconf will settle many of the details in the Makefile above
+automatically, making it much simpler and more portable; we recommend
+using Autoconf with Guile. Guile also provides the @code{GUILE_FLAGS}
+macro for autoconf that performs all necessary checks. Here is a
+@file{configure.in} file for @code{simple-guile} that uses this macro.
+Autoconf can use as this file as template to generate a @code{configure}
+script. In order for Autoconf to find the @code{GUILE_FLAGS} macro, you
+will need to run @code{aclocal} first. This is not really Guile
+specific, so you should refer to the Autoconf documentation REFFIXME
+when in doubt.
+@example
+AC_INIT(simple-guile.c)
+
+# Find a C compiler.
+AC_PROG_CC
+
+# Check for Guile
+GUILE_FLAGS
+
+# Generate a Makefile, based on the results.
+AC_OUTPUT(Makefile)
+@end example
+
+Here is a @code{Makefile.in} template, from which the @code{configure}
+script produces a Makefile customized for the host system:
+@example
+# The configure script fills in these values.
+CC=@@CC@@
+CFLAGS=@@GUILE_CFLAGS@@
+LIBS=@@GUILE_LDFLAGS@@
+
+simple-guile: simple-guile.o
+ $@{CC@} simple-guile.o $@{LIBS@} -o simple-guile
+simple-guile.o: simple-guile.c
+ $@{CC@} -c $@{CFLAGS@} simple-guile.c
+@end example
+
+The developer should use Autoconf to generate the @file{configure}
+script from the @file{configure.in} template, and distribute
+@file{configure} with the application. Here's how a user might go about
+building the application:
+
+@example
+$ ls
+Makefile.in configure* configure.in simple-guile.c
+$ ./configure
+creating cache ./config.cache
+checking for gcc... (cached) gcc
+checking whether the C compiler (gcc ) works... yes
+checking whether the C compiler (gcc ) is a cross-compiler... no
+checking whether we are using GNU C... (cached) yes
+checking whether gcc accepts -g... (cached) yes
+checking for Guile... yes
+creating ./config.status
+creating Makefile
+$ make
+gcc -c -I/usr/local/include simple-guile.c
+gcc simple-guile.o -L/usr/local/lib -lguile -lqthreads -lpthread -lm -o simple-guile
+$ ./simple-guile
+guile> (+ 1 2 3)
+6
+guile> (getpwnam "jimb")
+#("jimb" "83Z7d75W2tyJQ" 4008 10 "Jim Blandy" "/u/jimb"
+ "/usr/local/bin/bash")
+guile> (exit)
+$
+@end example
+
+@node Writing Extensions for Guile
+@section Writing Extensions for Guile
+
+The previous sections have briefly explained how to write programs that
+make use of an embedded Guile interpreter. But sometimes, all you want
+to do is make new primitive procedures and data types available to the
+Scheme programmer. Writing a new version of @code{guile} is
+inconvenient in this case and it would in fact make the life of the
+users of your new features needlessly hard.
+
+@c [[ the following is probably a bit longwinded ]]
+
+For example, suppose that there is a program @code{guile-db} that is a
+version of Guile with additional features for accessing a database.
+People who want to write Scheme programs that use these features would
+have to use @code{guile-db} instead of the usual @code{guile} program.
+Now suppose that there is also a program @code{guile-gtk} that extends
+Guile with access to the popular Gtk+ toolkit for graphical user
+interfaces. People who want to write GUIs in Scheme would have to use
+@code{guile-gtk}. Now, what happens when you want to write a Scheme
+application that uses a GUI to let the user accessa a database? You
+would have to write a @emph{third} program that incorporates both the
+database stuff and the GUI stuff. This might not be easy (because
+@code{guile-gtk} might be a quite obscure program, say) and taking this
+example further makes it easy to see that this approach can not work in
+practice.
+
+It would have been much better if both the database features and the GUI
+feature had been provided as libraries that can just be linked with
+@code{guile}. Guile makes it easy to do just this, and we encourage you
+to make your extensions to Guile available as libraries whenever
+possible.
+
+You write the new primitive procedures and data types in the normal
+fashion, and link them into a shared library instead of into a
+standalone program. The shared library can then be loaded dynamically
+by Guile.
+
+@menu
+* A Sample Guile Extension::
+@end menu
+
+@node A Sample Guile Extension
+@subsection A Sample Guile Extension
+
+This section explains how to make the Bessel functions of the C library
+available to Scheme. First we need to write the appropriate glue code
+to convert the arguments and return values of the functions from Scheme
+to C and back. Additionally, we need a function that will add them to
+the set of Guile primitives. Because this is just an example, we will
+only implement this for the @code{j0} function, tho.
+
+Consider the following file @file{bessel.c}.
+
+@smallexample
+#include <math.h>
+#include <libguile.h>
+
+SCM
+j0_wrapper (SCM x)
+@{
+ return scm_make_real (j0 (scm_num2dbl (x, "j0")));
+@}
+
+void
+init_bessel ()
+@{
+ scm_c_define_gsubr ("j0", 1, 0, 0, j0_wrapper);
+@}
+@end smallexample
+
+This C source file needs to be compiled into a shared library. Here is
+how to do it on GNU/Linux:
+
+@smallexample
+gcc -shared -o libguile-bessel.so -fPIC bessel.c
+@end smallexample
+
+For creating shared libraries portably, we recommend the use of
+@code{GNU Libtool}.
+
+A shared library can be loaded into a running Guile process with the
+function @code{load-extension}. In addition to the name of the
+library to load, this function also expects the name of function from
+that library that will be called to initialize it. For our example,
+we are going to call the function @code{init_bessel} which will make
+@code{j0_wrapper} available to Scheme programs with the name
+@code{j0}. Note that we do not specify a filename extension such as
+@file{.so} when invoking @code{load-extension}. The right extension for
+the host platform will be provided automatically.
+
+@smalllisp
+(load-extension "libguile-bessel" "init_bessel")
+(j0 2)
+@result{} 0.223890779141236
+@end smalllisp
+
+For this to work, @code{load-extension} must be able to find
+@file{libguile-bessel}, of course. It will look in the places that
+are usual for your operating system, and it will additionally look
+into the directories listed in the @code{LTDL_LIBRRAY_PATH}
+environment variable.
+
+To see how these Guile extensions via shared libraries relate to the
+module system, see below @xref{Intro to Modules and Extensions}.
+
+@node Guile Modules
+@section Guile Modules
+
+Guile has support for dividing a program into @dfn{modules}. By using
+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 compatability.)
+
+Details on the module system beyond this introductory material can be found in
+@xref{Modules}.
+
+
+@menu
+* Intro to Using Guile Modules::
+* Intro to Writing New Modules::
+* Intro to Modules and Extensions::
+@end menu
+
+@node Intro to Using Guile Modules
+@subsection Intro to Using Existing Modules
+
+Guile comes with a lot of useful modules, for example for string
+processing or command line parsing. Additionally, there exist many
+Guile modules written by other Guile hackers, but which have to be
+installed manually.
+
+Existing modules have to be placed in places where Guile looks for them
+by default or in colon-separated directories in the environment variable
+@code{GUILE_LOAD_PATH}. When this variable is set, those directories
+are searched first, then the the default. The following command
+shows the complete list of directories searched:
+
+@smallexample
+guile -c '(write %load-path) (newline)'
+@end smallexample
+
+Suppose you want to use the procedures and variables exported by the
+module @code{(ice-9 popen)}, which provides the means for communicating
+with other processes over pipes. Add the following line to your
+currently running Guile REPL or the top of you script file.
+
+@lisp
+(use-modules (ice-9 popen))
+@end lisp
+
+This will load the module and make the procedures exported by
+@code{(ice-9 popen)} automatically available. The next step could be to
+open a pipe to @file{ls} and read the contents of the current directory,
+one line at a time.
+
+@lisp
+(define p (open-input-pipe "ls -l"))
+(read-line p)
+@result{}
+"total 30"
+(read-line p)
+@result{}
+"drwxr-sr-x 2 mgrabmue mgrabmue 1024 Mar 29 19:57 CVS"
+@end lisp
+
+
+@node Intro to Writing New Modules
+@subsection Intro to Writing New Modules
+
+Of course it is possible to write modules yourself. Using modules for
+structuring your programs makes them more readable and lets you
+distribute them more easily. Also, explicitly defining the procedures
+and variables which are exported from a module adds documentation to the
+source and specifies the interface a module provides.
+
+In Guile, you can create new modules and switch to exisiting modules in
+order to add bindings to them using the syntactic form
+@code{define-module}.
+
+@lisp
+(define-module (foo bar))
+
+(define (frob x) x)
+@end lisp
+
+Will create the module @code{(foo bar)}.@footnote{It is only convention
+that the module names in this section have two elements. One or more
+than two elements are perfectly fine, such as @code{(foo)} or @code{(foo
+bar braz)}} All definitions following this statement will add bindings
+to the module @code{(foo bar)}, and these bindings will not be visible
+outside of the module. To make the bindings accessible to other
+modules, you have to export them explicitly using one of the following
+means:
+
+@itemize @bullet
+@item
+Export them with the @code{export} form:
+@lisp
+(export frob)
+@end lisp
+
+@item
+Include them into the @code{define-module} form with the keyword
+@code{export}:
+@lisp
+(define-module (foo bar)
+ #:export (frob))
+@end lisp
+
+@item
+Change the definition of @code{frob} to use @code{define-public}, which
+is a combination of @code{define} and @code{export}.
+@lisp
+(define-public (frob x) x)
+@end lisp
+@end itemize
+
+After exporting, other modules can access the exported items simply by
+using @code{use-modules} to load the module @code{(foo bar)}.
+
+
+@node Intro to Modules and Extensions
+@subsection Intro to Modules and Extensions
+
+In addition to Scheme code you can also put things that are defined in
+C into a module.
+
+You do this by writing a small Scheme file that defines the module.
+That Scheme file in turn invokes @code{load-extension} to make the
+features defined in C available. This works since all definitions
+made by @code{scm_c_define_gsubr} etc. go into the @emph{current
+module} and @code{define-module} causes the newly defined module to be
+current while the code that follows it is executed.
+
+Suppose we want to put the Bessel function @code{j0} from the example
+extension into a module called @code{(math bessel)}. We would have to
+write a Scheme file with this contents
+
+@smallexample
+(define-module (math bessel))
+
+(export j0)
+
+(load-extension "libguile-bessel" "init_bessel")
+@end smallexample
+
+This file should of course be saved in the right place for
+autoloading, for example as
+@file{/usr/local/share/guile/math/bessel.scm}.
+
+When @code{init_bessel} is called, the new @code{(math bessel)} module
+is the current one. Thus, the call to @code{scm_c_define_gsubr} will
+put the new definition for @code{j0} into it, just as we want it.
+
+The definitions made in the C code are not automatically exported from
+a module. You need to explicitely list the ones you want to export in
+@code{export} statements or with the @code{:export} option of
+@code{define-module}.
+
+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.
+
+@page
+@node Reporting Bugs
+@chapter Reporting Bugs
+
+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 bugfix
+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.
+
+@itemize @bullet
+@item
+Whenever documentation and actual behaviour differ, you have certainly
+found a bug, either in the documentation or in the program.
+
+@item
+When Guile crashes, it is a bug.
+
+@item
+When Guile hangs or takes forever to complete a task, it is a bug.
+
+@item
+When calculations produce wrong results, it is a bug.
+
+@item
+When Guile signals an error for valid Scheme programs, it is a bug.
+
+@item
+When Guile does not signal an error for invalid Scheme programs, it may
+be a bug, unless this is explicitly documented.
+
+@item
+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
+
+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
+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.
+
+You can get the version number by invoking the command
+
+@example
+$ guile --version
+Guile 1.4.1
+Copyright (c) 1995, 1996, 1997, 2000 Free Software Foundation
+Guile may be distributed under the terms of the GNU General Public Licence;
+certain other uses are permitted as well. For details, see the file
+`COPYING', which is included in the Guile distribution.
+There is no warranty, to the extent permitted by law.
+@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}.
+
+@example
+$ uname -a
+Linux tortoise 2.2.17 #1 Thu Dec 21 17:29:05 CET 2000 i586 unknown
+@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}.
+
+@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?
+
+If the manifestation of the bug is an 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 Lisp 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 don't 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 .libs/guile}.
+@c fixme: libguile/.libs is for libtool-enabled systems -- what about rest?
+
+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:
+@c TeX-master: "guile.texi"
+@c End: