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.
Scheme, as defined in R5RS, does not have a module system at all.
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.
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 Guile version 1.4.
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.
A Guile module is a collection of named procedures, variables and macros, altogether called the bindings, since they bind, or associate, a symbol (the name) to a Scheme object (procedure, variable, or macro). 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 section 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 section 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 (REFFIXME). The resulting file name is then
searched in all directories in the variable %load-path. For
example, the (ice-9 popen) module would result in the filename
ice-9/popen.scm and searched in the installation directory 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 section Creating Guile Modules).
Please note that there are some problems with the current module system you should keep in mind (see section Module System Quirks). We hope to address these eventually.
To use a Guile module is to access either its public interface or a
custom interface (see section 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 (REFFIXME %load-path).
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 section 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)
:rename (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.
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] [:rename 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 :rename 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.
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.
When you want to create your own modules, you have to take the following steps:
define-module form at the beginning.
define-public or export (both documented below).
(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
(use-modules interface-specification)
(see section Using Guile Modules).
#:use-syntax module
#:autoload module symbol
#:export list
(export list) in the module body.
#:no-backtrace
#:pure
(begin (define foo ...) (export foo)).
The procedures in this section are useful if you want to dig into the innards of Guile's module system. If you don't know precisely what you do, you should probably avoid using any of them.
Although the programming interfaces are relatively stable, the Guile module system itself is still evolving. Here are some situations where usage surpasses design.
Some modules are included in the Guile distribution; here are references to the entries in this manual which describe them in more detail:
and-let* (see section SRFI-2 - and-let*).
receive (see section SRFI-8 - receive).
define-record-type (see section SRFI-9 - define-record-type).
#,() (see section SRFI-10 - Hash-Comma Reader Extension).
let-values and let-values*
(see section SRFI-11 - let-values).
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(13)
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.
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.
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'.
#t if obj is a dynamic library handle, or #f
otherwise.
dynamic-link. After dynamic-unlink has been
called on dobj, its content is no longer accessible.
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.
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).
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.
The new primitives that you add to Guile with gh_new_procedure
or with any of the other mechanisms are normally placed into the same
module as all the other builtin procedures (like display).
However, it is also possible to put new primitives into their own
module.
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 gh_new_procedure 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 gh_new_procedure for our new primitives.
Unfortunately, there is not yet an easy way to access the module system
from C, so we are better off with a more indirect approach. Instead of
adding our primitives at initialization time we merely register with
Guile that we are ready to provide the contents of a certain module,
should it ever be needed.
The function initfunc should perform the usual initialization
actions for your new primitives, like calling gh_new_procedure or
including the file produced by the snarfer. When initfunc is
called, the current module is a newly created module with a name as
indicated by name. Each definition that is added to it will be
automatically exported.
The string name indicates the hierarchical name of the new module.
It should consist of the individual components of the module name
separated by single spaces. That is, the Scheme module name (foo
bar), which is a list, should be written as "foo bar" for the
name parameter.
You can call scm_register_module_xxx at any time, even before
Guile has been initialized. This might be useful when you want to put
the call to it in some initialization code that is magically called
before main, like constructors for global C++ objects.
An example for scm_register_module_xxx appears in the next section.
Now, instead of calling the initialization function at program startup,
you should simply call scm_register_module_xxx and pass it the
initialization function. When the named module is later requested by
Scheme code with use-modules for example, Guile will notice that
it knows how to create this module and will call the initialization
function at the right time in the right context.
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 <guile/gh.h>
SCM
j0_wrapper (SCM x)
{
return gh_double2scm (j0 (gh_scm2double (x)));
}
void
init_math_bessel ()
{
gh_new_procedure1_0 ("j0", 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) -| the-root-module: 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 gh_new_procedure is called. To put j0 into its
own module named `(math bessel)', we need to make a call to
scm_register_module_xxx. Additionally, to have Guile perform
the dynamic linking automatically, we need to put `libbessel.so'
into a place where Guile can find it. The call to
scm_register_module_xxx should be contained in 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 add the following code to
`bessel.c':
void scm_init_math_bessel_module ()
{
scm_register_module_xxx ("math bessel", init_math_bessel);
}
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'. It should call
scm_register_module_xxx with the correct module name and the
appropriate initialization function. When that initialization function
will be called, a newly created module with the right name will be the
current module so that all definitions that the initialization
functions makes will end up in the correct module.
After `libbessel.so' has been rebuild, we need to place the shared
library into the right place. When Guile tries to autoload the
`(math bessel)' module, it looks not only for a file called
`math/bessel.scm' in its %load-path, but also for
`math/libbessel.so'. So all we need to do is to create a directory
called `math' somewhere in Guile's %load-path and place
`libbessel.so' there. Normally, the current directory `.' is
in the %load-path, so we just use that for this example.
% mkdir maths % cd maths % ln -s ../libbessel.so . % cd .. % guile guile> (use-modules (math bessel)) guile> (j0 2) 0.223890779141236 guile> (apropos 'j0) -| bessel: j0 #<primitive-procedure j0>
That's it!
Note that we used a symlink to make `libbessel.so' appear in the right spot. This is probably not a bad idea in general. The directories that the `%load-path' normally contains are supposed to contain only architecture independent files. They are not really the right place for a shared library. You might want to install the libraries somewhere below `exec_prefix' and then symlink to them from the architecture independent directory. This will at least work on heterogenous systems where the architecture dependent stuff resides in the same place on all machines (which seems like a good idea to me anyway).
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 section The Guile module system).
#t iff var is bound to a value.
Throws an error if var is not a variable object.
make-variable
and make-undefined-variable.
#t iff obj is a variable object, else
return #f.
Go to the first, previous, next, last section, table of contents.