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.

The Basic Guile Package
=======================

Guile can be obtained from the main GNU archive site ftp://prep.ai.mit.edu/pub/gnu or any of its mirrors.  The file will be named guile-version.tar.gz.  The current version is VERSION, so the file you should grab is:

ftp://prep.ai.mit.edu/pub/gnu/guile-VERSION.tar.gz

To unbundle Guile use the instruction

     zcat guile-VERSION.tar.gz | tar xvf -

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

     cd guile-VERSION
     ./configure
     make install

This will install the Guile executable guile, the Guile library libguile.a and various associated header files and support libraries. It will also install the Guile tutorial and reference manual.

Since this manual frequently refers to the Scheme ``standard'', also known as R4RS, or the ``Revised^4 Report on the Algorithmic Language Scheme'', we have included the report in the Guile distribution; see Introduction (Revised(4) Report on the Algorithmic Language Scheme). This will also be installed in your info directory.

Packages not shipped with Guile
===============================

We ship the Guile tutorial and reference manual with the Guile distribution [FIXME: this is not currently true (Sat Sep 20 14:13:33 MDT 1997), but will be soon.]  Since the Scheme standard (R4RS) 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.

SCSH
     the Scheme Shell.  Gary Houston has ported SCSH to Guile.  The relevant chapter (see The Scheme shell (scsh)) has references to the SCSH web page with all its documentation.

SLIB
     a portable Scheme library maintained by Aubrey Jaffer.  SLIB can be obtained by ftp from 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 /usr/local/share/guile/site, so that it will be /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:

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

     The relevant chapter (see SLIB) has details on how to use SLIB with Guile.

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

     The relevant section (see JACAL) has details on how to use Jacal.

Reporting Bugs
**************

Any problems with the installation should be reported to bug-guile@gnu.ai.mit.edu

[[how about an explanation of what makes a good bug report?]] [[don't complain to us about problems with contributed modules?]]

Internals
*********

This appendix describes many functions that may be used to inspect and modify Guile's internal structure.  These will mainly be of interest to people interested in extending, modifying or debugging Guile.

Symbols
=======

Guile symbol tables are hash tables.  Each hash table, also called an obarray (for `object array'), is a vector of association lists. Each entry in the alists is a pair (SYMBOL . VALUE).  To intern a symbol in a symbol table means to return its (SYMBOL . VALUE) pair, adding a new entry to the symbol table (with an undefined value) if none is yet present.

 -- primitive: string->obarray-symbol obarray string [soft?]
     Intern a new symbol in OBARRAY, a symbol table, with name STRING.

     If OBARRAY is #f, use the default system symbol table.  If OBARRAY is #t, the symbol should not be interned in any symbol table; merely return the pair (SYMBOL . #<UNDEFINED>).

     The SOFT? argument determines whether new symbol table entries should be created when the specified symbol is not already present in OBARRAY.  If SOFT? is specified and is a true value, then new entries should not be added for symbols not already present in the table; instead, simply return #f.

 -- primitive: intern-symbol obarray string
     Add a new symbol to OBARRAY with name STRING, bound to an unspecified initial value.  The symbol table is not modified if a symbol with this name is already present.

 -- primitive: unintern-symbol obarray string
     Remove the symbol with name STRING from OBARRAY.  This function returns #t if the symbol was present and #f otherwise.

 -- primitive: symbol-binding obarray string
     Look up in OBARRAY the symbol whose name is STRING, and return the value to which it is bound.  If OBARRAY is #f, use the global symbol table.  If STRING is not interned in OBARRAY, an error is signalled.

 -- primitive: symbol-interned? obarray string
     Return #T if OBARRAY contains a symbol with name STRING, and #F otherwise.

 -- primitive: symbol-bound? obarray string
     Return #T if OBARRAY contains a symbol with name STRING bound to a defined value.  This differs from SYMBOL-BOUND? in that the mere mention of a symbol usually causes it to be interned; symbol-bound? determines whether a symbol has been given any meaningful value.

 -- primitive: symbol-set! obarray string value
     Find the symbol in OBARRAY whose name is STRING, and rebind it to VALUE.  An error is signalled if STRING is not present in OBARRAY.

 -- primitive: symbol-fref symbol
     Return the contents of SYMBOL's function slot.

 -- primitive: symbol-pref symbol
     Return the property list currently associated with SYMBOL.

 -- primitive: symbol-fset! symbol
     Change the binding of SYMBOL's function slot.

 -- primitive: symbol-pset! symbol
     Change the binding of SYMBOL's property slot.

 -- primitive: symbol-hash symbol
     Return the hash value derived from SYMBOL's name, i.e. the integer index into SYMBOL's obarray at which it is stored.

 -- primitive: builtin-bindings
     Create and return a copy of the global symbol table, removing all unbound symbols.

 -- primitive: builtin-weak-bindings

 -- primitive: gensym [name [obarray]]
     Create a new, unique symbol in OBARRAY, using the global symbol table by default.  If NAME is specified, it should be used as a prefix for the new symbol's name.  The default prefix is %%gensym.

debugger user interface
***********************

When debugging a program, programmers often find it helpful to examine the program's internal status while it runs: the values of internal variables, the choices made in if and cond statements, and so forth.  Guile Scheme provides a debugging interface that programmers can use to single-step through Scheme functions and examine symbol bindings.  This is different from the Internal Debugging Interface, which permits programmers to debug the Guile interpreter itself.  Most programmers will be more interested in debugging their own Scheme programs than the interpreter which evaluates them.

[FIXME: should we include examples of traditional debuggers and explain why they can't be used to debug interpreted Scheme or Lisp?]

Single-Step
===========

Trace
=====

When a function is traced, it means that every call to that function is reported to the user during a program run.  This can help a programmer determine whether a function is being called at the wrong time or with the wrong set of arguments.

 -- Function: trace function
     Enable debug tracing on function.  While a program is being run, Guile will print a brief report at each call to a traced function, advising the user which function was called and the arguments that were passed to it.

 -- Function: untrace function
     Disable debug tracing for function.

Example:

     (define (rev ls)
       (if (null? ls)
           '()
           (append (rev (cdr ls))
                   (cons (car ls) '())))) => rev

     (trace rev) => (rev)

     (rev '(a b c d e))
     => [rev (a b c d e)]
        |  [rev (b c d e)]
        |  |  [rev (c d e)]
        |  |  |  [rev (d e)]
        |  |  |  |  [rev (e)]
        |  |  |  |  |  [rev ()]
        |  |  |  |  |  ()
        |  |  |  |  (e)
        |  |  |  (e d)
        |  |  (e d c)
        |  (e d c b)
        (e d c b a)
        (e d c b a)

Note the way Guile indents the output, illustrating the depth of execution at each function call.  This can be used to demonstrate, for example, that Guile implements self-tail-recursion properly:

     (define (rev ls sl)
       (if (null? ls)
           sl
           (rev (cdr ls)
                (cons (car ls) sl)))) => rev

     (trace rev) => (rev)

     (rev '(a b c d e) '())
     => [rev (a b c d e) ()]
        [rev (b c d e) (a)]
        [rev (c d e) (b a)]
        [rev (d e) (c b a)]
        [rev (e) (d c b a)]
        [rev () (e d c b a)]
        (e d c b a)
        (e d c b a)

Since the tail call is effectively optimized to a goto statement, there is no need for Guile to create a new stack frame for each iteration.  Using trace here helps us see why this is so.

Backtrace
=========

Stacks and Frames
=================

When a running program is interrupted, usually upon reaching an error or breakpoint, its state is represented by a stack of suspended function calls, each of which is called a frame.  The programmer can learn more about the program's state at the point of interruption by inspecting and modifying these frames.

 -- primitive: stack? obj
     Return #t if OBJ is a calling stack.

 -- primitive: make-stack

 -- syntax: start-stack id exp
     Evaluate EXP on a new calling stack with identity ID.  If EXP is interrupted during evaluation, backtraces will not display frames farther back than EXP's top-level form.  This macro is a way of artificially limiting backtraces and stack procedures, largely as a convenience to the user.

 -- primitive: stack-id stack
     Return the identifier given to STACK by start-stack.

 -- primitive: stack-ref

 -- primitive: stack-length

 -- primitive: frame?

 -- primitive: last-stack-frame

 -- primitive: frame-number

 -- primitive: frame-source

 -- primitive: frame-procedure

 -- primitive: frame-arguments

 -- primitive: frame-previous

 -- primitive: frame-next

 -- primitive: frame-real?

 -- primitive: frame-procedure?

 -- primitive: frame-evaluating-args?

 -- primitive: frame-overflow

Procedure Index
***************

This is an alphabetical list of all the procedures and macros in Guile. [[Remind people to look for functions under their Scheme names as well as their C names.]]

Variable Index
**************

This is an alphabetical list of all the important variables and constants in Guile. [[Remind people to look for variables under their Scheme names as well as their C names.]]

Type Index
**********

This is an alphabetical list of all the important data types defined in the Guile Programmers Manual.