Updated: $Date: 2009/06/30 22:13:45 $ $Author: ossau $ (guile-faq.texi.ChangeLog).

Welcome to the Guile FAQ.

If you have a question, you may also like to check Guile's mailing list archives:

  * http://sources.redhat.com/ml/guile/ - no longer active, but may still contain useful information

  * http://lists.gnu.org/archive/html/guile-users/ - the current list for Guile usage questions and discussions

  * http://lists.gnu.org/archive/html/guile-devel/ - the current list for Guile development questions and discussions.

If you don't find a suitable or complete answer, please write to one of the current mailing lists.  Details for how to do that are here (/software/guile/mail/mail.html).

Historical Note: The document formerly at this url (http://www.gnu.org/software/guile/docs/faq/OLD-guile-faq.html) contains many interesting bits that we will be updating and distributing over the rest of the guile web pages.  Thanks go to Russ McManus for his work collecting and creating that page and the support package for it.

What can I do with this document?
*********************************

Copyright (C) 2000, 2009 Free Software Foundation

This document is free documentation; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

As a special exception, the programs contained in this document are in the public domain.  There are no restrictions on how you may use these programs.  This exception applies only to the machine executable programs contained in the body of the document.

This document and any included programs in the document are distributed in the hope that they will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.

Where can I get more information about Guile?
*********************************************

http://www.gnu.org/software/guile/guile.html
     The official guile home page.

http://www.gnu.org/software/guile/docs/faq/guile-faq.html
     The guile FAQ.  Most likely you're looking at it right now.

http://www.gnu.org/software/guile/gnu-guile-projects.html
     Free software projects using guile, including related projects, applications, tools, and libraries.

http://home.thezone.net/~gharvey/guile/qdocs/index.html
     Greg Harvey's documentation of guile internals.  These are incomplete, but very useful if you want to know how guile works.

How do I add a question to the FAQ?
***********************************

Please send your suggestion to the guile-user or guile-devel mailing list.

The most helpful way of preparing your suggested question is as a diff against the Texinfo sources (http://www.gnu.org/software/guile/docs/faq/guile-faq.texi), so if you are comfortable with Texinfo please do that.  If not, a simple text email is fine too.

Can Guile work with SLIB?
*************************

Yes.  If SLIB is unpacked into /some/path/to/slib, make sure /some/path/to is in %load-path, either by setting %load-path directly, or setting environment variable GUILE_LOAD_PATH before starting the Guile session.  Once this is done, use module (ice-9 slib) to access the require form. For example:

     (define-module (my module)
       :use-module (ice-9 slib))
     (require 'glob)
     (write-line (replace-suffix "a.c" "c" "o"))

See also the SLIB home page (http://www-swiss.ai.mit.edu/~jaffer/SLIB.html).

How do I create a procedure that takes keyword arguments?
*********************************************************

This question and its answer were nicely put (http://sources.redhat.com/ml/guile/2000-03/msg00119.html) by Lalo Martins.  You can use lambda*, as in this example:

     guile> (use-modules (ice-9 optargs))
     guile> (define my-proc (lambda* (req #&amp;key foo bar)
     ...   (display "req = ") (display req) (newline)
     ...   (if (bound? foo) (begin (display "foo = ") (display foo)
     (newline)))
     ...   (if (bound? bar) (begin (display "bar = ") (display bar)
     (newline)))
     ... )
     ... )
     guile> (my-proc 1)
     1
     guile> (my-proc 1 2)
     1
     guile> (my-proc 1 #:foo 2)
     1
     foo = 2
     guile> (my-proc 1 #:bar 2)
     1
     bar = 2
     guile> (my-proc 1 #:bar 2 #:foo 3)
     1
     foo = 3
     bar = 2
     guile> (my-proc 1 #:bar 2 #:foo 3 #:bar 0)
     1
     foo = 3
     bar = 0

How do I write a generic method in C?
*************************************

Mikael Djurfeldt says that as of 25-Jul-2000, there is no C API for GOOPS. However, it can be done:

     To create a generic:

     gf = scm_make (SCM_LIST3 (scm_class_generic, k_name, NAME));

     To add a method:

     scm_add_method (gf, scm_make (SCM_LIST5 (scm_class_method,
                                              k_specializers,
                                              SCM_LISTn (SPEC1, SPEC2, ...),
                                              k_procedure, PROC)));

Does SWIG work with Guile?
**************************

The Simplified Wrapper and Interface Generator (http://www.swig.org) is a compiler that integrates C and C++ with languages including Perl, Python, Tcl, Guile, Mzscheme, Java and Ruby.  SWIG reads annotated C/C++ header files and creates wrapper code (glue code) in order to make the corresponding C/C++ libraries available to the listed languages, or to extend C/C++ programs with a scripting language.

Though SWIG 1.1p5 had some Guile support, it is strongly recommended to use version 1.3.6 instead.  It represents C/C++ pointers as Guile smobs. Memory leaks and type conversion bugs have been fixed.  The Guile module system, including dynamic loading, and exceptions are supported.  A typemap-driven procedure-documentation system has been added (requires Guile 1.4).  Procedures-with-setters can be generated for accessing C/C++ variables.

SWIG 1.3.6 supports Guile 1.3.4 and newer.

Is there an easy way to call a C routine as a Scheme function?
**************************************************************

It is one of the main goals of Guile to be an extensions language, and one important part of that is that it is easy to add new functions and data types to it from C.

A large part of the Guile Reference Manual (http://www.gnu.org/software/guile/docs/docs.html) is dedicated to this topic (but the manual is unfortunately not in its best shape yet).  There is great progress being made on the reference manual, and we hope to be able to point you to real documentation soon.

The short answer is to use gh_new_procedure or scm_make_gsubr to create a Scheme function that invokes a C function when called from Scheme.  The arugments to and the return value from the C function are Scheme objects which need to be converted.  For example:

     SCM
     minus_one_still_positive_p (SCM number)
     {
       double n = gh_scm2double (number);

       return gh_bool2scm (n - 1.0 > 0.0);
     }

     scm_make_gsubr ("-1-still-positive?", 1, 0, 0,
                     (SCM (*)() ) minus_one_still_positive_p);

Note that we omit proper type-checking for brevity.

Is there a Scheme code profiler that works with Guile?
******************************************************

Keisuke Nishida asks and answers (http://sources.redhat.com/ml/guile/2000-07/msg00206.html) his own question, supplying a patch to implement such a profiler. Hmm, how would that look on a call-graph? (smile)

Harvey Stein posts (http://sources.redhat.com/ml/guile/2000-07/msg00219.html) version 0.9 of wrappers.scm, a library for wrapping functions and executing forms, useful for implementing tracing and profiling.

Because profiling and tracing have similar requirements, Mikael Djurfeldt mentions apply-frame-handler (http://sources.redhat.com/ml/guile/2000-07/msg00412.html) and enter-frame-handler (http://sources.redhat.com/ml/guile/2000-07/msg00415.html), which are used in the guile (ice-9 debug) module.  Use the forms (trap-enable 'apply-frame) and (trap-enable 'enter-frame) to enable calling of the respective handlers.

Another approach is to use the statistical profiler written by Rob Browning. He says:

It's in guile cvs in a top-level module named, as I recall, guile-statprof.  I requires a version of guile at least as new as the current unstable version 1.5.4.

How do I look up a variable from C using gh_module_lookup?
**********************************************************

John Daschbach asks (http://sources.redhat.com/ml/guile/2000-07/msg00198.html) about the C function gh_module_lookup, which takes vec as its first argument.  He points out that there are inconsistencies with C and Scheme access to the module system and wonders if it is possible to turn off the module system altogether.  He also offers more analysis (http://sources.redhat.com/ml/guile/2000-07/msg00232.html).

The ultimate answer to this and other module system questions is: Wait for the new module system, nicknamed "Godot" for some reason, which will be built on the first-class environments that are to be incorporated by Jul-Aug timeframe.

[TODO: Answer this specific question!]

How do I make foo.scm into an executable script?
************************************************

First, add these two lines to the beginning of foo.scm:

     #!/usr/bin/guile -s
     !#

Next, make foo.scm executable:

     chmod +x foo.scm

How do I define procedures with optional and/or rest arguments?
***************************************************************

This question was nicely answered (http://mail.gnu.org/pipermail/guile-user/2000-October/000374.html) by Steve Tell.  Basically:

     (use-modules (ice-9 optargs))
     (define* (func1 arg1 arg2 #:optional arg3 #:rest more-args) ...)
     (define* (func2 arg1 arg2 #:optional arg3 . more-args) ...)

In this case, both func1 and func2 have the same argument signature.  The (ice-9 optargs) module also provides keyword argument support (see previous question).

What is the significance of the different version numbers?
**********************************************************

Guile versioning philosophy has changed.  It used to be simple MAJOR.MINOR in the classic GNU style, but starting post 1.4, it is MAJOR.MINOR.MICRO, w/ semantics similar to that of the Linux kernel.

So, all the 1.5.x series are "unstable" and w/ enough feedback and bugfixes, a 1.6.x series will be released at some point.  All released versions are available to everyone, of course, but those w/ even middle numbers are "stable" and in the eyes of the maintainers, most suitable for universal distribution.  1.7.x is the next unstable series, work on it to begin in earnest once the first 1.6.x is released, and eventually leading to a 1.8.x series.  And so on.

What this means to you: If you are new to guile or have used 1.4 (or earlier) in the past, you should use 1.5.x and then demand 1.6.x from your distribution packagers once it comes out.  If you package guile for a distribution, you should tell the package maintainers in your distribution who use guile read this post, and then distribute 1.6.x.

Please see NEWS in the distribution for more info on versioning details and other changes (many significant) since 1.4.

Why does readline break going from 1.4 to 1.5.x?
************************************************

In guile-1.4 you could just type into a repl:

     (use-modules (ice-9 readline))
     (activate-readline)

This doesn't work in guile-1.5.x out of the box because the default curent module for the repl is now (guile-user).  The workaround is to place in your .guile file:

     (define-module (guile-user))

See NEWS for more info.

What is the policy on C API changes between Guile releases?
***********************************************************

(The following consensus of the Guile developers emerged from guile-user mailing list discussion, January 2005.)

 1. We do not regard it as an overriding aim to maintain C API compatibility between Guile releases (that is, between versions w.x and y.z where ((w != y) || (x != z))); we believe it is more important to improve Guile's overall utility, which sometimes conflicts with retaining API compatibility.

 2. Consequently, the developer of a non-trivial Guile application must in practice choose a particular Guile release and write their C code according to that release's C API, and should expect some work to be required when enhancing their application to target a new Guile release.

 3. On the other hand, we will obviously not pointlessly change the C API between releases, for at least four pragmatic reasons.

       * We don't want to annoy our users for no reason!

       * Any API change itself requires work by the core Guile developers.

       * The core Guile code uses its own APIs, so any unnecessary changes would require unnecessary work in Guile's own internals.

       * Most of the core Guile developers also write Guile applications, so any unnecessary changes would require unnecessary work in those applications as well.

 4. Consequently the upgrade work mentioned in (2), while non-zero, should always be as small as it could reasonably be.

 5. Where possible, we will support the old C API, for the next one or more releases, as a deprecated interface.  Guile's deprecation infrastructure both highlights to the developer that they are using a deprecated interface, and gives them a one-line hint as to what they should be doing instead.

 6. We will aim to document API changes completely.  The first point of reference for this is usually the NEWS file in each new release.  Such documentation may be imperfect in practice, but only for the same reasons that make documentation in general imperfect.

Build problems
**************

readline.c: error: `rl_pending_input' undeclared
================================================

This occurs if the Readline library detected by Guile's configure script is actually the BSD Editline project's supposedly Readline-compatible library.  The immediate fix is to uninstall Editline and install the real GNU Readline instead.  When you do this, please note that it probably won't work to keep Editline in /usr and install GNU Readline in /usr/local (or some similar arrangement), because the Editline library will then still be picked up at link and run time; it's best (subject to other constraints) to remove Editline completely.

For the longer term, please also report this problem to the Editline project, to encourage them to fix it in the next release of their Readline compatibility library.

Building guile-1.4 gives a previous declaration of inet_aton error?
===================================================================

This is a known buglet in guile-1.4.  The workaround is to comment out the offending line (libguile/net_db.c, line 85) and restart the build.

Building guile-1.4 fails with an AWK internal error?
====================================================

This is a known problem when building guile-1.4 with a comparatively recent version of GCC.

Between Guile versions 1.4 and 1.6, GCC's preprocessor behaviour changed so that macro expansions go on a single line in the output, which doesn't agree with Guile 1.4's doc snarfing mechanism.

From 1.5.x onwards we implemented a new doc snarfing mechanism that copes with this.

Obviously we can't fix the 1.4 distribution retrospectively.  So the fix is either to downgrade to an older GCC or to move to guile-1.5.x, or Guile 1.6 when that becomes available.