[bpt/guile.git] / doc / ref / intro.texi

@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
@ifnottex
Revised^5
@end ifnottex
Report on the Algorithmic Language Scheme (usually known as @acronym{R5RS}),
providing clean and general data and control structures.  Guile goes
beyond the rather austere language presented in @acronym{R5RS}, extending it with
a module system, full access to @acronym{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
then 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, @acronym{GUI}
toolkit interfaces, and @acronym{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.  There are additional examples in the @file{examples/}
directory in the Guile source distribution.

@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 {Scheme Procedure} command-line
@deffnx {Scheme Procedure} 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{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 tell the compiler and linker
explicitly 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
portable 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{command-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 long-winded ]]

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 access 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
stand-alone 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.

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_LIBRARY_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 compatibility.)

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 your 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.  For the latter, we use the function
@code{read-line}, which can be found in the module @code{(ice-9
rdelim)}, so we use that module as well.

@lisp
(use-modules (ice-9 rdelim))
(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

The macro @code{use-modules} can take any number of modules to use.
Therefore, we could have written the two @code{use-modules} statements
in the code above as

@lisp
(use-modules (ice-9 popen) (ice-9 rdelim))
@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 existing 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 explicitly 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 Obtaining and Installing Guile
@chapter Obtaining and Installing Guile

Here is the information you will need to get and install Guile and extra
packages and documentation you might need or find interesting.

@menu
* The Basic Guile Package::
* Packages not shipped with Guile::
@end menu


@node The Basic Guile Package
@section The Basic Guile Package

Guile can be obtained from the main GNU archive site
@url{ftp://ftp.gnu.org} or any of its mirrors.  The file
will be named guile-version.tar.gz.  The current version is
@value{VERSION}, so the file you should grab is:

@url{ftp://ftp.gnu.org/pub/gnu/guile-@value{VERSION}.tar.gz}

To unbundle Guile use the instruction

@example
zcat guile-@value{VERSION}.tar.gz | tar xvf -
@end example

which will create a directory called @file{guile-@value{VERSION}} with
all the sources.  You can look at the file @file{INSTALL} for detailed
instructions on how to build and install Guile, but you should be able
to just do

@example
cd guile-@value{VERSION}
./configure
make
make install
@end example

This will install the Guile executable @file{guile}, the Guile library
@file{-lguile} and various associated header files and support
libraries. It will also install the Guile tutorial and reference
manual.

@c [[include instructions for getting R5RS]]

Since this manual frequently refers to the Scheme ``standard'', also
known as R5RS, or the
@iftex
``Revised$^5$ Report on the Algorithmic Language Scheme'',
@end iftex
@ifnottex
``Revised^5 Report on the Algorithmic Language Scheme'',
@end ifnottex
we have included the report in the Guile distribution;
@xref{Top, , Introduction, r5rs, Revised(5) Report on the Algorithmic
Language Scheme}.
This will also be installed in your info directory.


@node Packages not shipped with Guile
@section Packages not shipped with Guile

We ship the Guile tutorial and reference manual with the Guile
distribution.  Since the Scheme standard (R5RS) is a stable document, we
ship that too.

Here are references (usually World Wide Web URLs) to some other freely
redistributable documents and packages which you might find useful if
you are using Guile.

@table @strong
@item SCSH
the Scheme Shell.  Gary Houston has ported SCSH to Guile.  The relevant
chapter (@pxref{The Scheme shell (scsh)}) has references to the SCSH web
page with all its documentation.

@item SLIB
a portable Scheme library maintained by Aubrey Jaffer.  SLIB can be
obtained by ftp from @url{ftp://prep.ai.mit.edu/pub/gnu/jacal/}.

The SLIB package should be unpacked somewhere in Guile's load path.  It
will typically be unpacked in @file{/usr/local/share/guile/site}, so
that it will be @file{/usr/local/share/guile/site/slib}.

Guile might have been installed with a different prefix, in which case
the load path can be checked from inside the interpreter with:

@smalllisp
guile> %load-path
("/usr/local/share/guile/site" "/usr/local/share/guile/1.3a" "/usr/local/share/guile" ".")
@end smalllisp

The relevant chapter (@pxref{SLIB}) has details on how to use SLIB with
Guile.

@item JACAL
a symbolic math package by Aubrey Jaffer.  The latest version of Jacal
can be obtained from @url{ftp://prep.ai.mit.edu/pub/gnu/jacal/}, and
should be unpacked in @file{/usr/local/share/guile/site/slib} so that
it will be in @file{/usr/local/share/guile/site/slib/jacal}.

The relevant section (@pxref{JACAL}) has details on how to use Jacal.
@end table


@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 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.

@itemize @bullet
@item
Whenever documentation and actual behavior 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 License;
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 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.

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



@c Local Variables:
@c TeX-master: "guile.texi"
@c End: