Introduction to Guile
*********************

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 Revised^5 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 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, 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.

Obtaining and Installing Guile
==============================

Guile can be obtained from the main GNU archive site ftp://ftp.gnu.org 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://ftp.gnu.org/pub/gnu/guile/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
     make install

This will install the Guile executable guile, the Guile library libguile 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 R5RS, or the ``Revised^5 Report on the Algorithmic Language Scheme'', we have included the report in the Guile distribution; see Introduction (Revised(5) Report on the Algorithmic Language Scheme). This will also be installed in your info directory.

A Whirlwind Tour
================

This chapter presents a quick tour of all the ways that Guile can be used.  There are additional examples in the examples/ directory in the Guile source distribution.

The following examples assume that Guile has been installed in /usr/local/.

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 $ and guile> prompts:

     $ 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> C-d
     $

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

Here is a trivial Guile script, for more details see Guile Scripting.

     #!/usr/local/bin/guile -s
     !#
     (display "Hello, world!")
     (newline)

Linking Guile into Programs
---------------------------

The Guile interpreter is available as an object library, to be linked into applications using Scheme as a configuration or extension language.

Here is simple-guile.c, source code for a program that will produce a complete Guile interpreter.  In addition to all usual functions provided by Guile, it will also offer the function my-hostname.

     #include <stdlib.h>
     #include <libguile.h>

     static SCM
     my_hostname (void)
     {
       char *s = getenv ("HOSTNAME");
       if (s == NULL)
         return SCM_BOOL_F;
       else
         return scm_from_locale_string (s);
     }

     static void
     inner_main (void *data, int argc, char **argv)
     {
       scm_c_define_gsubr ("my-hostname", 0, 0, 0, my_hostname);
       scm_shell (argc, argv);
     }

     int
     main (int argc, char **argv)
     {
       scm_boot_guile (argc, argv, inner_main, 0);
       return 0; /* never reached */
     }

When Guile is correctly installed on your system, the above program can be compiled and linked like this:

     $ gcc -o simple-guile simple-guile.c -lguile

When it is run, it behaves just like the guile program except that you can also call the new my-hostname function.

     $ ./simple-guile
     guile> (+ 1 2 3)
     6
     guile> (my-hostname)
     "burns"

Writing Guile Extensions
------------------------

You can link Guile into your program and make Scheme available to the 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 extensions, but it really just is an ordinary object library.

The following example shows how to write a simple extension for Guile that makes the j0 function available to Scheme code.

     #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);
     }

This C source file needs to be compiled into a shared library.  Here is how to do it on GNU/Linux:

     gcc -shared -o libguile-bessel.so -fPIC bessel.c

For creating shared libraries portably, we recommend the use of GNU Libtool (see Introduction (GNU Libtool)).

A shared library can be loaded into a running Guile process with the function load-extension.  The j0 is then immediately available:

     $ guile
     guile> (load-extension "./libguile-bessel" "init_bessel")
     guile> (j0 2)
     0.223890779141236

Using the Guile Module System
-----------------------------

Guile has support for dividing a program into 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 see Modules.

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

Here is a sample interactive session that shows how to use the (ice-9 popen) module which provides the means for communicating with other processes over pipes together with the (ice-9 rdelim) module that provides the function read-line.

     $ 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"

Writing new Modules
...................

You can create new modules using the syntactic form define-module.  All definitions following this form until the next define-module are placed into the new module.

One module is usually placed into one file, and that file is installed in a location where Guile can automatically find it.  The following session shows a simple example.

     $ cat /usr/local/share/guile/foo/bar.scm

     (define-module (foo bar))
     (export frob)

     (define (frob x) (* 2 x))

     $ guile
     guile> (use-modules (foo bar))
     guile> (frob 12)
     24

Putting Extensions into Modules
...............................

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 and call load-extension directly in the body of the module.

     $ cat /usr/local/share/guile/math/bessel.scm

     (define-module (math bessel))
     (export j0)

     (load-extension "libguile-bessel" "init_bessel")

     $ file /usr/local/lib/libguile-bessel.so
     ... ELF 32-bit LSB shared object ...
     $ guile
     guile> (use-modules (math bessel))
     guile> (j0 2)
     0.223890779141236

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.

Reporting Bugs
==============

Any problems with the installation should be reported to 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.

  * Whenever documentation and actual behavior differ, you have certainly found a bug, either in the documentation or in the program.

  * When Guile crashes, it is a bug.

  * When Guile hangs or takes forever to complete a task, it is a bug.

  * When calculations produce wrong results, it is a bug.

  * When Guile signals an error for valid Scheme programs, it is a bug.

  * When Guile does not signal an error for invalid Scheme programs, it may be a bug, unless this is explicitly documented.

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

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.

  * 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

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

  * The type of machine you are using, and the operating system name and version number.  On GNU systems, you can get it with uname.

          $ uname -a
          Linux tortoise 2.2.17 #1 Thu Dec 21 17:29:05 CET 2000 i586 unknown

  * The operands given to the configure command when Guile was installed.  It's often useful to augment this with the output of the command guile-config info.

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

  * Details of any other deviations from the standard procedure for installing Guile.

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

  * The precise Guile invocation command line we need to type to reproduce the bug.

  * 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 backtrace in the REPL.

  * Check whether any programs you have loaded into Guile, including your .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 .guile file (start Guile with the -q switch to prevent loading the init file).  If the problem does 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.

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

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

  * 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 libguile subdirectory in which Guile was compiled, then do gdb guile or 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).

Typographical Conventions
=========================

We use some conventions in this manual.

  * For some procedures, notably type predicates, we use ``iff'' to mean ``if and only if''.  The construct is usually something like: `Return VAL iff CONDITION', where VAL is usually ``#t'' or ``non-#f''.  This typically means that VAL is returned if CONDITION holds, and that #f is returned otherwise.  To clarify: VAL will only be returned when CONDITION is true.

  * In examples and procedure descriptions and all other places where the evaluation of Scheme expression is shown, we use some notation for denoting the output and evaluation results of expressions.

     The symbol => is used to tell which value is returned by an evaluation:

          (+ 1 2)
          => 3

     Some procedures produce some output besides returning a value.  This is denoted by the symbol -|.

          (begin (display 1) (newline) 'hooray)
          -| 1
          => hooray

     As you can see, this code prints 1 (denoted by -|), and returns hooray (denoted by =>).  Do not confuse the two.