Modules
=======

When programs become large, naming conflicts can occur when a function or global variable defined in one file has the same name as a function or global variable in another file.  Even just a similarity between function names can cause hard-to-find bugs, since a programmer might type the wrong function name.

The approach used to tackle this problem is called information encapsulation, which consists of packaging functional units into a given name space that is clearly separated from other name spaces.

The language features that allow this are usually called the module system because programs are broken up into modules that are compiled separately (or loaded separately in an interpreter).

Older languages, like C, have limited support for name space manipulation and protection.  In C a variable or function is public by default, and can be made local to a module with the static keyword.  But you cannot reference public variables and functions from another module with different names.

More advanced module systems have become a common feature in recently designed languages: ML, Python, Perl, and Modula 3 all allow the renaming of objects from a foreign module, so they will not clutter the global name space.

In addition, Guile offers variables as first-class objects.  They can be used for interacting with the module system.

provide and require
-------------------

Aubrey Jaffer, mostly to support his portable Scheme library SLIB, implemented a provide/require mechanism for many Scheme implementations. Library files in SLIB provide a feature, and when user programs require that feature, the library file is loaded in.

For example, the file random.scm in the SLIB package contains the line

     (provide 'random)

so to use its procedures, a user would type

     (require 'random)

and they would magically become available, but still have the same names!  So this method is nice, but not as good as a full-featured module system.

When SLIB is used with Guile, provide and require can be used to access its facilities.

Environments
------------

Scheme, as defined in R5RS, does not have a full module system. However it does define the concept of a top-level environment. Such an environment maps identifiers (symbols) to Scheme objects such as procedures and lists: About Closure.  In other words, it implements a set of bindings.

Environments in R5RS can be passed as the second argument to eval (see Fly Evaluation).  Three procedures are defined to return environments: scheme-report-environment, null-environment and interaction-environment (see Fly Evaluation).

In addition, in Guile any module can be used as an R5RS environment, i.e., passed as the second argument to eval.

Note: the following two procedures are available only when the (ice-9 r5rs) module is loaded:

     (use-modules (ice-9 r5rs))

 -- Scheme Procedure: scheme-report-environment version
 -- Scheme Procedure: null-environment version
     VERSION must be the exact integer `5', corresponding to revision 5 of the Scheme report (the Revised^5 Report on Scheme). scheme-report-environment returns a specifier for an environment that is empty except for all bindings defined in the report that are either required or both optional and supported by the implementation. null-environment returns a specifier for an environment that is empty except for the (syntactic) bindings for all syntactic keywords defined in the report that are either required or both optional and supported by the implementation.

     Currently Guile does not support values of VERSION for other revisions of the report.

     The effect of assigning (through the use of eval) a variable bound in a scheme-report-environment (for example car) is unspecified.  Currently the environments specified by scheme-report-environment are not immutable in Guile.

The Guile module system
-----------------------

The Guile module system extends the concept of environments, discussed in the previous section, with mechanisms to define, use and customise sets of bindings.

In 1996 Tom Lord implemented a full-featured module system for Guile which allows loading Scheme source files into a private name space.  This system has been in available since at least Guile version 1.1.

For Guile version 1.5.0 and later, the system has been improved to have better integration from C code, more fine-grained user control over interfaces, and documentation.

Although it is anticipated that the module system implementation will change in the future, the Scheme programming interface described in this manual should be considered stable.  The C programming interface is considered relatively stable, although at the time of this writing, there is still some flux.

General Information about Modules
.................................

A Guile module can be thought of as a collection of named procedures, variables and macros.  More precisely, it is a set of bindings of symbols (names) to Scheme objects.

An environment is a mapping from identifiers (or symbols) to locations, i.e., a set of bindings. There are top-level environments and lexical environments. The environment in which a lambda is executed is remembered as part of its definition.

Within a module, all bindings are visible.  Certain bindings can be declared public, in which case they are added to the module's so-called export list; this set of public bindings is called the module's public interface (see Creating Guile Modules).

A client module uses a providing module's bindings by either accessing the providing module's public interface, or by building a custom interface (and then accessing that).  In a custom interface, the client module can select which bindings to access and can also algorithmically rename bindings.  In contrast, when using the providing module's public interface, the entire export list is available without renaming (see Using Guile Modules).

To use a module, it must be found and loaded.  All Guile modules have a unique module name, which is a list of one or more symbols. Examples are (ice-9 popen) or (srfi srfi-11).  When Guile searches for the code of a module, it constructs the name of the file to load by concatenating the name elements with slashes between the elements and appending a number of file name extensions from the list %load-extensions (see Loading).  The resulting file name is then searched in all directories in the variable %load-path (see Build Config).  For example, the (ice-9 popen) module would result in the filename ice-9/popen.scm and searched in the installation directories of Guile and in all other directories in the load path.

Every module has a so-called syntax transformer associated with it. This is a procedure which performs all syntax transformation for the time the module is read in and evaluated.  When working with modules, you can manipulate the current syntax transformer using the use-syntax syntactic form or the #:use-syntax module definition option (see Creating Guile Modules).

Please note that there are some problems with the current module system you should keep in mind (see Module System Quirks).  We hope to address these eventually.

Using Guile Modules
...................

To use a Guile module is to access either its public interface or a custom interface (see General Information about Modules).  Both types of access are handled by the syntactic form use-modules, which accepts one or more interface specifications and, upon evaluation, arranges for those interfaces to be available to the current module. This process may include locating and loading code for a given module if that code has not yet been loaded, following %load-path (see Build Config).

An interface specification has one of two forms.  The first variation is simply to name the module, in which case its public interface is the one accessed.  For example:

     (use-modules (ice-9 popen))

Here, the interface specification is (ice-9 popen), and the result is that the current module now has access to open-pipe, close-pipe, open-input-pipe, and so on (see Included Guile Modules).

Note in the previous example that if the current module had already defined open-pipe, that definition would be overwritten by the definition in (ice-9 popen).  For this reason (and others), there is a second variation of interface specification that not only names a module to be accessed, but also selects bindings from it and renames them to suit the current module's needs.  For example:

     (use-modules ((ice-9 popen)
                   :select ((open-pipe . pipe-open) close-pipe)
                   :renamer (symbol-prefix-proc 'unixy:)))

Here, the interface specification is more complex than before, and the result is that a custom interface with only two bindings is created and subsequently accessed by the current module.  The mapping of old to new names is as follows:

     (ice-9 popen) sees:             current module sees:
     open-pipe                       unixy:pipe-open
     close-pipe                      unixy:close-pipe

This example also shows how to use the convenience procedure symbol-prefix-proc.

You can also directly refer to bindings in a module by using the @ syntax.  For example, instead of using the use-modules statement from above and writing unixy:pipe-open to refer to the pipe-open from the (ice-9 popen), you could also write (@ (ice-9 popen) open-pipe).  Thus an alternative to the complete use-modules statement would be

     (define unixy:pipe-open (@ (ice-9 popen) open-pipe))
     (define unixy:close-pipe (@ (ice-9 popen) close-pipe))

There is also @@, which can be used like @, but does not check whether the variable that is being accessed is actually exported.  Thus, @@ can be thought of as the impolite version of @ and should only be used as a last resort or for debugging, for example.

Note that just as with a use-modules statement, any module that has not yet been loaded yet will be loaded when referenced by a @ or @@ form.

You can also use the @ and @@ syntaxes as the target of a set! when the binding refers to a variable.

 -- Scheme Procedure: symbol-prefix-proc prefix-sym
     Return a procedure that prefixes its arg (a symbol) with PREFIX-SYM.

 -- syntax: use-modules spec ...
     Resolve each interface specification SPEC into an interface and arrange for these to be accessible by the current module.  The return value is unspecified.

     SPEC can be a list of symbols, in which case it names a module whose public interface is found and used.

     SPEC can also be of the form:

           (MODULE-NAME [:select SELECTION] [:renamer RENAMER])

     in which case a custom interface is newly created and used. MODULE-NAME is a list of symbols, as above; SELECTION is a list of selection-specs; and RENAMER is a procedure that takes a symbol and returns its new name.  A selection-spec is either a symbol or a pair of symbols (ORIG . SEEN), where ORIG is the name in the used module and SEEN is the name in the using module.  Note that SEEN is also passed through RENAMER.

     The :select and :renamer clauses are optional.  If both are omitted, the returned interface has no bindings.  If the :select clause is omitted, RENAMER operates on the used module's public interface.

     Signal error if module name is not resolvable.

 -- syntax: use-syntax module-name
     Load the module module-name and use its system transformer as the system transformer for the currently defined module, as well as installing it as the current system transformer.

 -- syntax: @ module-name binding-name
     Refer to the binding named BINDING-NAME in module MODULE-NAME.  The binding must have been exported by the module.

 -- syntax: @@ module-name binding-name
     Refer to the binding named BINDING-NAME in module MODULE-NAME.  The binding must not have been exported by the module.  This syntax is only intended for debugging purposes or as a last resort.

Creating Guile Modules
......................

When you want to create your own modules, you have to take the following steps:

  * Create a Scheme source file and add all variables and procedures you wish to export, or which are required by the exported procedures.

  * Add a define-module form at the beginning.

  * Export all bindings which should be in the public interface, either by using define-public or export (both documented below).

 -- syntax: define-module module-name [options ...]
     MODULE-NAME is of the form (hierarchy file).  One example of this is

          (define-module (ice-9 popen))

     define-module makes this module available to Guile programs under the given MODULE-NAME.

     The OPTIONS are keyword/value pairs which specify more about the defined module.  The recognized options and their meaning is shown in the following table.

     #:use-module INTERFACE-SPECIFICATION
          Equivalent to a (use-modules INTERFACE-SPECIFICATION) (see Using Guile Modules).

     #:use-syntax MODULE
          Use MODULE when loading the currently defined module, and install it as the syntax transformer.

     #:autoload MODULE SYMBOL-LIST
          Load MODULE when any of SYMBOL-LIST are accessed.  For example,

               (define-module (my mod)
                 #:autoload (srfi srfi-1) (partition delete-duplicates))
               ...
               (if something
                   (set! foo (delete-duplicates ...)))

          When a module is autoloaded, all it's bindings become available. SYMBOL-LIST is just those that will first trigger the load.

          An autoload is a good way to put off loading a big module until it's really needed, for instance for faster startup or if it will only be needed in certain circumstances.

          @ can do a similar thing (see Using Guile Modules), but in that case an @ form must be written every time a binding from the module is used.

     #:export LIST
          Export all identifiers in LIST, which must be a list of symbols. This is equivalent to (export LIST) in the module body.

     #:no-backtrace
          Tell Guile not to record information for procedure backtraces when executing the procedures in this module.

     #:pure
          Create a pure module, that is a module which does not contain any of the standard procedure bindings except for the syntax forms.  This is useful if you want to create safe modules, that is modules which do not know anything about dangerous procedures.

 -- syntax: export variable ...
     Add all VARIABLEs (which must be symbols) to the list of exported bindings of the current module.

 -- syntax: define-public ...
     Equivalent to (begin (define foo ...) (export foo)).

Module System Reflection
........................

The previous sections have described a declarative view of the module system.  You can also work with it programmatically by accessing and modifying various parts of the Scheme objects that Guile uses to implement the module system.

At any time, there is a current module.  This module is the one where a top-level define and similar syntax will add new bindings.  You can find other module objects with resolve-module, for example.

These module objects can be used as the second argument to eval.

 -- Scheme Procedure: current-module
     Return the current module object.

 -- Scheme Procedure: set-current-module module
     Set the current module to MODULE and return the previous current module.

 -- Scheme Procedure: resolve-module name
     Find the module named NAME and return it.  When it has not already been defined, try to auto-load it.  When it can't be found that way either, create an empty module.  The name is a list of symbols.

 -- Scheme Procedure: resolve-interface name
     Find the module named NAME as with resolve-module and return its interface.  The interface of a module is also a module object, but it contains only the exported bindings.

 -- Scheme Procedure: module-use! module interface
     Add INTERFACE to the front of the use-list of MODULE.  Both arguments should be module objects, and INTERFACE should very likely be a module returned by resolve-interface.

Module System Quirks
....................

Although the programming interfaces are relatively stable, the Guile module system itself is still evolving.  Here are some situations where usage surpasses design.

  * When using a module which exports a macro definition, the other module must export all bindings the macro expansion uses, too, because the expanded code would otherwise not be able to see these definitions and issue a ``variable unbound'' error, or worse, would use another binding which might be present in the scope of the expansion.

  * When two or more used modules export bindings with the same names, the last accessed module wins, and the exported binding of that last module will silently be used.  This might lead to hard-to-find errors because wrong procedures or variables are used.  To avoid this kind of name-clash situation, use a custom interface specification (see Using Guile Modules).  (We include this entry for the possible benefit of users of Guile versions previous to 1.5.0, when custom interfaces were added to the module system.)

  * [Add other quirks here.]

Included Guile Modules
......................

Some modules are included in the Guile distribution; here are references to the entries in this manual which describe them in more detail:

boot-9
     boot-9 is Guile's initialization module, and it is always loaded when Guile starts up.

(ice-9 debug)
     Mikael Djurfeldt's source-level debugging support for Guile (see Debugging Features).

(ice-9 expect)
     Actions based on matching input from a port (see Expect).

(ice-9 format)
     Formatted output in the style of Common Lisp (see Formatted Output).

(ice-9 ftw)
     File tree walker (see File Tree Walk).

(ice-9 getopt-long)
     Command line option processing (see getopt-long).

(ice-9 history)
     Refer to previous interactive expressions (see Value History).

(ice-9 popen)
     Pipes to and from child processes (see Pipes).

(ice-9 pretty-print)
     Nicely formatted output of Scheme expressions and objects (see Pretty Printing).

(ice-9 q)
     First-in first-out queues (see Queues).

(ice-9 threads)
     Guile's support for multi threaded execution (see Scheduling).

(ice-9 rdelim)
     Line- and character-delimited input (see Line/Delimited).

(ice-9 readline)
     readline interactive command line editing (see Readline Support).

(ice-9 receive)
     Multiple-value handling with receive (see Multiple Values).

(ice-9 regex)
     Regular expression matching (see Regular Expressions).

(ice-9 rw)
     Block string input/output (see Block Reading and Writing).

(ice-9 streams)
     Sequence of values calculated on-demand (see Streams).

(ice-9 syncase)
     R5RS syntax-rules macro system (see Syntax Rules).

(ice-9 documentation)
     Online documentation (REFFIXME).

(srfi srfi-1)
     A library providing a lot of useful list and pair processing procedures (see SRFI-1).

(srfi srfi-2)
     Support for and-let* (see SRFI-2).

(srfi srfi-4)
     Support for homogeneous numeric vectors (see SRFI-4).

(srfi srfi-6)
     Support for some additional string port procedures (see SRFI-6).

(srfi srfi-8)
     Multiple-value handling with receive (see SRFI-8).

(srfi srfi-9)
     Record definition with define-record-type (see SRFI-9).

(srfi srfi-10)
     Read hash extension #,() (see SRFI-10).

(srfi srfi-11)
     Multiple-value handling with let-values and let-values* (see SRFI-11).

(srfi srfi-13)
     String library (see SRFI-13).

(srfi srfi-14)
     Character-set library (see SRFI-14).

(srfi srfi-16)
     case-lambda procedures of variable arity (see SRFI-16).

(srfi srfi-17)
     Getter-with-setter support (see SRFI-17).

(srfi srfi-19)
     Time/Date library (see SRFI-19).

(srfi srfi-26)
     Convenient syntax for partial application (see SRFI-26)

(srfi srfi-31)
     rec convenient recursive expressions (see SRFI-31)

(ice-9 slib)
     This module contains hooks for using Aubrey Jaffer's portable Scheme library SLIB from Guile (see SLIB).

Accessing Modules from C
........................

The last sections have described how modules are used in Scheme code, which is the recommended way of creating and accessing modules.  You can also work with modules from C, but it is more cumbersome.

The following procedures are available.

 -- C Procedure: SCM scm_current_module ()
     Return the module that is the current module.

 -- C Procedure: SCM scm_set_current_module (SCM MODULE)
     Set the current module to MODULE and return the previous current module.

 -- C Procedure: SCM scm_c_call_with_current_module (SCM MODULE, SCM (*FUNC)(void *), void *DATA)
     Call FUNC and make MODULE the current module during the call.  The argument DATA is passed to FUNC.  The return value of scm_c_call_with_current_module is the return value of FUNC.

 -- C Procedure: SCM scm_c_lookup (const char *NAME)
     Return the variable bound to the symbol indicated by NAME in the current module.  If there is no such binding or the symbol is not bound to a variable, signal an error.

 -- C Procedure: SCM scm_lookup (SCM NAME)
     Like scm_c_lookup, but the symbol is specified directly.

 -- C Procedure: SCM scm_c_module_lookup (SCM MODULE, const char *NAME)
 -- C Procedure: SCM scm_module_lookup (SCM MODULE, SCM NAME)
     Like scm_c_lookup and scm_lookup, but the specified module is used instead of the current one.

 -- C Procedure: SCM scm_c_define (const char *NAME, SCM VAL)
     Bind the symbol indicated by NAME to a variable in the current module and set that variable to VAL.  When NAME is already bound to a variable, use that.  Else create a new variable.

 -- C Procedure: SCM scm_define (SCM NAME, SCM VAL)
     Like scm_c_define, but the symbol is specified directly.

 -- C Procedure: SCM scm_c_module_define (SCM MODULE, const char *NAME, SCM VAL)
 -- C Procedure: SCM scm_module_define (SCM MODULE, SCM NAME, SCM VAL)
     Like scm_c_define and scm_define, but the specified module is used instead of the current one.

 -- C Procedure: SCM scm_module_reverse_lookup (SCM MODULE, SCM VARIABLE)
     Find the symbol that is bound to VARIABLE in MODULE.  When no such binding is found, return #F.

 -- C Procedure: SCM scm_c_define_module (const char *NAME, void (*INIT)(void *), void *DATA)
     Define a new module named NAME and make it current while INIT is called, passing it DATA.  Return the module.

     The parameter NAME is a string with the symbols that make up the module name, separated by spaces.  For example, "foo bar" names the module (foo bar).

     When there already exists a module named NAME, it is used unchanged, otherwise, an empty module is created.

 -- C Procedure: SCM scm_c_resolve_module (const char *NAME)
     Find the module name NAME and return it.  When it has not already been defined, try to auto-load it.  When it can't be found that way either, create an empty module.  The name is interpreted as for scm_c_define_module.

 -- C Procedure: SCM scm_resolve_module (SCM NAME)
     Like scm_c_resolve_module, but the name is given as a real list of symbols.

 -- C Procedure: SCM scm_c_use_module (const char *NAME)
     Add the module named NAME to the uses list of the current module, as with (use-modules NAME).  The name is interpreted as for scm_c_define_module.

 -- C Procedure: SCM scm_c_export (const char *NAME, ...)
     Add the bindings designated by NAME, ... to the public interface of the current module.  The list of names is terminated by NULL.

Dynamic Libraries
-----------------

Most modern Unices have something called shared libraries.  This ordinarily means that they have the capability to share the executable image of a library between several running programs to save memory and disk space.  But generally, shared libraries give a lot of additional flexibility compared to the traditional static libraries.  In fact, calling them `dynamic' libraries is as correct as calling them `shared'.

Shared libraries really give you a lot of flexibility in addition to the memory and disk space savings.  When you link a program against a shared library, that library is not closely incorporated into the final executable.  Instead, the executable of your program only contains enough information to find the needed shared libraries when the program is actually run.  Only then, when the program is starting, is the final step of the linking process performed.  This means that you need not recompile all programs when you install a new, only slightly modified version of a shared library.  The programs will pick up the changes automatically the next time they are run.

Now, when all the necessary machinery is there to perform part of the linking at run-time, why not take the next step and allow the programmer to explicitly take advantage of it from within his program?  Of course, many operating systems that support shared libraries do just that, and chances are that Guile will allow you to access this feature from within your Scheme programs.  As you might have guessed already, this feature is called dynamic linking. (Some people also refer to the final linking stage at program startup as `dynamic linking', so if you want to make yourself perfectly clear, it is probably best to use the more technical term dlopening, as suggested by Gordon Matzigkeit in his libtool documentation.)

As with many aspects of Guile, there is a low-level way to access the dynamic linking apparatus, and a more high-level interface that integrates dynamically linked libraries into the module system.

Low level dynamic linking
.........................

When using the low level procedures to do your dynamic linking, you have complete control over which library is loaded when and what gets done with it.

 -- Scheme Procedure: dynamic-link library
 -- C Function: scm_dynamic_link (library)
     Find the shared library denoted by LIBRARY (a string) and link it into the running Guile application.  When everything works out, return a Scheme object suitable for representing the linked object file. Otherwise an error is thrown.  How object files are searched is system dependent.

     Normally, LIBRARY is just the name of some shared library file that will be searched for in the places where shared libraries usually reside, such as in /usr/lib and /usr/local/lib.

 -- Scheme Procedure: dynamic-object? obj
 -- C Function: scm_dynamic_object_p (obj)
     Return #t if OBJ is a dynamic library handle, or #f otherwise.

 -- Scheme Procedure: dynamic-unlink dobj
 -- C Function: scm_dynamic_unlink (dobj)
     Unlink the indicated object file from the application.  The argument DOBJ must have been obtained by a call to dynamic-link.  After dynamic-unlink has been called on DOBJ, its content is no longer accessible.

 -- Scheme Procedure: dynamic-func name dobj
 -- C Function: scm_dynamic_func (name, dobj)
     Search the dynamic object DOBJ for the C function indicated by the string NAME and return some Scheme handle that can later be used with dynamic-call to actually call the function.

     Regardless whether your C compiler prepends an underscore _ to the global names in a program, you should not include this underscore in FUNCTION.  Guile knows whether the underscore is needed or not and will add it when necessary.

 -- Scheme Procedure: dynamic-call func dobj
 -- C Function: scm_dynamic_call (func, dobj)
     Call the C function indicated by FUNC and DOBJ. The function is passed no arguments and its return value is ignored.  When FUNCTION is something returned by dynamic-func, call that function and ignore DOBJ. When FUNC is a string , look it up in DYNOBJ; this is equivalent to

          (dynamic-call (dynamic-func FUNC DOBJ) #f)

     Interrupts are deferred while the C function is executing (with SCM_DEFER_INTS/SCM_ALLOW_INTS).

 -- Scheme Procedure: dynamic-args-call func dobj args
 -- C Function: scm_dynamic_args_call (func, dobj, args)
     Call the C function indicated by FUNC and DOBJ, just like dynamic-call, but pass it some arguments and return its return value.  The C function is expected to take two arguments and return an int, just like main:

          int c_func (int argc, char **argv);

     The parameter ARGS must be a list of strings and is converted into an array of char *.  The array is passed in ARGV and its size in ARGC.  The return value is converted to a Scheme number and returned from the call to dynamic-args-call.

When dynamic linking is disabled or not supported on your system, the above functions throw errors, but they are still available.

Here is a small example that works on GNU/Linux:

     (define libc-obj (dynamic-link "libc.so"))
     libc-obj
     => #<dynamic-object "libc.so">
     (dynamic-args-call 'rand libc-obj '())
     => 269167349
     (dynamic-unlink libc-obj)
     libc-obj
     => #<dynamic-object "libc.so" (unlinked)>

As you can see, after calling dynamic-unlink on a dynamically linked library, it is marked as (unlinked) and you are no longer able to use it with dynamic-call, etc.  Whether the library is really removed from you program is system-dependent and will generally not happen when some other parts of your program still use it.  In the example above, libc is almost certainly not removed from your program because it is badly needed by almost everything.

The functions to call a function from a dynamically linked library, dynamic-call and dynamic-args-call, are not very powerful. They are mostly intended to be used for calling specially written initialization functions that will then add new primitives to Guile. For example, we do not expect that you will dynamically link libX11 with dynamic-link and then construct a beautiful graphical user interface just by using dynamic-call and dynamic-args-call.  Instead, the usual way would be to write a special Guile<->X11 glue library that has intimate knowledge about both Guile and X11 and does whatever is necessary to make them inter-operate smoothly.  This glue library could then be dynamically linked into a vanilla Guile interpreter and activated by calling its initialization function.  That function would add all the new types and primitives to the Guile interpreter that it has to offer.

From this setup the next logical step is to integrate these glue libraries into the module system of Guile so that you can load new primitives into a running system just as you can load new Scheme code.

There is, however, another possibility to get a more thorough access to the functions contained in a dynamically linked library.  Anthony Green has written libffi, a library that implements a foreign function interface for a number of different platforms.  With it, you can extend the Spartan functionality of dynamic-call and dynamic-args-call considerably.  There is glue code available in the Guile contrib archive to make libffi accessible from Guile.

Putting Compiled Code into Modules
..................................

The new primitives that you add to Guile with scm_c_define_gsubr (see Primitive Procedures) or with any of the other mechanisms are placed into the (guile-user) module by default.  However, it is also possible to put new primitives into other modules.

The mechanism for doing so is not very well thought out and is likely to change when the module system of Guile itself is revised, but it is simple and useful enough to document it as it stands.

What scm_c_define_gsubr and the functions used by the snarfer really do is to add the new primitives to whatever module is the current module when they are called.  This is analogous to the way Scheme code is put into modules: the define-module expression at the top of a Scheme source file creates a new module and makes it the current module while the rest of the file is evaluated.  The define expressions in that file then add their new definitions to this current module.

Therefore, all we need to do is to make sure that the right module is current when calling scm_c_define_gsubr for our new primitives.

Dynamic Linking and Compiled Code Modules
.........................................

The most interesting application of dynamically linked libraries is probably to use them for providing compiled code modules to Scheme programs.  As much fun as programming in Scheme is, every now and then comes the need to write some low-level C stuff to make Scheme even more fun.

Not only can you put these new primitives into their own module (see the previous section), you can even put them into a shared library that is only then linked to your running Guile image when it is actually needed.

An example will hopefully make everything clear.  Suppose we want to make the Bessel functions of the C library available to Scheme in the module (math bessel).  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 j0 function.

     #include <math.h>
     #include <libguile.h>

     SCM
     j0_wrapper (SCM x)
     {
       return scm_double2num (j0 (scm_num2dbl (x, "j0")));
     }

     void
     init_math_bessel ()
     {
       scm_c_define_gsubr ("j0", 1, 0, 0, j0_wrapper);
     }

We can already try to bring this into action by manually calling the low level functions for performing dynamic linking.  The C source file needs to be compiled into a shared library.  Here is how to do it on GNU/Linux, please refer to the libtool documentation for how to create dynamically linkable libraries portably.

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

Now fire up Guile:

     (define bessel-lib (dynamic-link "./libbessel.so"))
     (dynamic-call "init_math_bessel" bessel-lib)
     (j0 2)
     => 0.223890779141236

The filename ./libbessel.so should be pointing to the shared library produced with the gcc command above, of course.  The second line of the Guile interaction will call the init_math_bessel function which in turn will register the C function j0_wrapper with the Guile interpreter under the name j0.  This function becomes immediately available and we can call it from Scheme.

Fun, isn't it?  But we are only half way there.  This is what apropos has to say about j0:

     (apropos "j0")
     -| (guile-user): j0     #<primitive-procedure j0>

As you can see, j0 is contained in the root module, where all the other Guile primitives like display, etc live.  In general, a primitive is put into whatever module is the current module at the time scm_c_define_gsubr is called.

A compiled module should have a specially named module init function.  Guile knows about this special name and will call that function automatically after having linked in the shared library.  For our example, we replace init_math_bessel with the following code in bessel.c:

     void
     init_math_bessel (void *unused)
     {
       scm_c_define_gsubr ("j0", 1, 0, 0, j0_wrapper);
       scm_c_export ("j0", NULL);
     }

     void
     scm_init_math_bessel_module ()
     {
       scm_c_define_module ("math bessel", init_math_bessel, NULL);
     }

The general pattern for the name of a module init function is: scm_init_, followed by the name of the module where the individual hierarchical components are concatenated with underscores, followed by _module.

After libbessel.so has been rebuilt, we need to place the shared library into the right place.

Once the module has been correctly installed, it should be possible to use it like this:

     guile> (load-extension "./libbessel.so" "scm_init_math_bessel_module")
     guile> (use-modules (math bessel))
     guile> (j0 2)
     0.223890779141236
     guile> (apropos "j0")
     -| (math bessel): j0      #<primitive-procedure j0>

That's it!

 -- Scheme Procedure: load-extension lib init
 -- C Function: scm_load_extension (lib, init)
     Load and initialize the extension designated by LIB and INIT. When there is no pre-registered function for LIB/INIT, this is equivalent to

          (dynamic-call INIT (dynamic-link LIB))

     When there is a pre-registered function, that function is called instead.

     Normally, there is no pre-registered function.  This option exists only for situations where dynamic linking is unavailable or unwanted. In that case, you would statically link your program with the desired library, and register its init function right after Guile has been initialized.

     LIB should be a string denoting a shared library without any file type suffix such as ".so".  The suffix is provided automatically.  It should also not contain any directory components.  Libraries that implement Guile Extensions should be put into the normal locations for shared libraries.  We recommend to use the naming convention libguile-bla-blum for a extension related to a module `(bla blum)'.

     The normal way for a extension to be used is to write a small Scheme file that defines a module, and to load the extension into this module.  When the module is auto-loaded, the extension is loaded as well.  For example,

          (define-module (bla blum))

          (load-extension "libguile-bla-blum" "bla_init_blum")

Variables
---------

Each module has its own hash table, sometimes known as an obarray, that maps the names defined in that module to their corresponding variable objects.

A variable is a box-like object that can hold any Scheme value.  It is said to be undefined if its box holds a special Scheme value that denotes undefined-ness (which is different from all other Scheme values, including for example #f); otherwise the variable is defined.

On its own, a variable object is anonymous.  A variable is said to be bound when it is associated with a name in some way, usually a symbol in a module obarray.  When this happens, the relationship is mutual: the variable is bound to the name (in that module), and the name (in that module) is bound to the variable.

(That's the theory, anyway.  In practice, defined-ness and bound-ness sometimes get confused, because Lisp and Scheme implementations have often conflated --- or deliberately drawn no distinction between --- a name that is unbound and a name that is bound to a variable whose value is undefined.  We will try to be clear about the difference and explain any confusion where it is unavoidable.)

Variables do not have a read syntax.  Most commonly they are created and bound implicitly by define expressions: a top-level define expression of the form

     (define NAME VALUE)

creates a variable with initial value VALUE and binds it to the name NAME in the current module.  But they can also be created dynamically by calling one of the constructor procedures make-variable and make-undefined-variable.

First-class variables are especially useful for interacting with the current module system (see The Guile module system).

 -- Scheme Procedure: make-undefined-variable
 -- C Function: scm_make_undefined_variable ()
     Return a variable that is initially unbound.

 -- Scheme Procedure: make-variable init
 -- C Function: scm_make_variable (init)
     Return a variable initialized to value INIT.

 -- Scheme Procedure: variable-bound? var
 -- C Function: scm_variable_bound_p (var)
     Return #t iff VAR is bound to a value. Throws an error if VAR is not a variable object.

 -- Scheme Procedure: variable-ref var
 -- C Function: scm_variable_ref (var)
     Dereference VAR and return its value. VAR must be a variable object; see make-variable and make-undefined-variable.

 -- Scheme Procedure: variable-set! var val
 -- C Function: scm_variable_set_x (var, val)
     Set the value of the variable VAR to VAL. VAR must be a variable object, VAL can be any value. Return an unspecified value.

 -- Scheme Procedure: variable? obj
 -- C Function: scm_variable_p (obj)
     Return #t iff OBJ is a variable object, else return #f.