Creating Guile Modules - Guile Reference Manual

Next: Variables, Previous: Using Guile Modules, Up: Modules

31.8 Creating Guile Modules

In previous sections we have described a module's interface as seen by client code. This section is a bit different in that we explicitly address implementation details, the machinery underlying the module's interface. We look at the two basic types of implementation in turn: Scheme modules, in the form of a human-readable text files; and compiled modules, typically in the form of a machine-dependent shared object libraries. Both types share the same goal of providing a public interface (see Using Guile Modules) for client code to access, while keeping messy details encapsulated within.

31.8.1 Scheme Modules

To create a Scheme module, 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, export, or a #:export clause in the define-module form (all documented below). Each method has its proponents; whichever you choose is mostly a matter of style.

— Scheme Macro: define-module module-name [options ...]

Associate forms following the define-module with module-name, a list of symbols. See Finding Guile Modules. The options are zero or more keywords and argument(s) which specify more about the defined module. The recognized options and their meanings are shown in the following table.

#:use-module interface-specification
Equivalent to a (use-modules interface-specification) (see Using Guile Modules).
#:use-syntax sup-name
Use supporting module sup-name when loading the currently defined module, and install it as the syntax transformer. sup-name is a list of symbols.
#:autoload sup-name list
Load module sup-name whenever one of the symbols in list is first accessed. This loading is done without selection or renaming. sup-name is a list of symbols.
#: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.

— Scheme Macro: export [names...]

Add all names (which must be symbols) to the list of exported bindings of the current module.

— Scheme Macro: define-public foo ...

Equivalent to (begin (define foo ...) (export foo)).

31.8.2 Compiled Modules

To create a compiled module (written in the C programming language), take the following steps:

include compiled module support
```
          #include <guile/modsup.h>
```
This pulls in various useful macros, chief among them GH_DEFPROC, GH_MODULE_LINK_FUNC and GH_NEEDY_MODULE_LINK_FUNC.
write C functions using either GH_DEFPROC or SCM_DEFINE
These C macros both work in similar ways. The difference is that SCM_DEFINE does not declare static, while GH_DEFPROC does. A good idea is to start with GH_DEFPROC and switch to SCM_DEFINE only if the need arises. See Init Snarfing.
add GH_MODULE_LINK_FUNC or GH_NEEDY_MODULE_LINK_FUNC
If the module does not depend on other modules — i.e., it is free of GH_USE_MODULE calls — then you can use GH_MODULE_LINK_FUNC otherwise you need to use GH_NEEDY_MODULE_LINK_FUNC.

See Compiled Code Modules, for more detailed information on compiled modules, including what to place in Makefiles. The rest of this subsection documents the macros in <guile/modsup.h> [probably this should be moved elsewhere —ttn].

— C Macro: GH_DEFPROC (fname, primname, req, opt, var, arglist, docstring)

Declare, define and document a C function callable from Scheme.
The C function is declared `static' and is "exported" later by the the module initialization routine. fname is the name of the C function (must be a valid C identifier). primname, a string, is the name visible from Scheme code. req, opt and var are each integers quantifying the number of required, optional and rest args are in the arglist. Note that var can be only 0 or 1. arglist is the C-style argument list for the function. The type for every element must be SCM. docstring is one or more strings that describe the function. Each string except the last must end in \n.

— C Macro: GH_MODULE_LINK_FUNC (module_name, fname_frag, module_init_func)

Define the C function to be called at link time for a non-needy module.
This function registers the module_name (a string) and arranges for module_init_func to be called at the right time to actually do the module-specific initializations. fname_frag is the C translation of module_name with unrepresentable characters replaced by underscore. It should have the same length as module_name.
The macro also generates a forward declaration of the function, immediately prior to the function definition, so that you don't have to.
Note that module_name must be a string literal.

— C Macro: GH_NEEDY_MODULE_LINK_FUNC (module_name, fname_frag, module_init_func, up)

Define the C function to be called at link time for a needy module.
This function registers the module_name (a string) and arranges for module_init_func to be called at the right time to actually do the module-specific initializations. fname_frag is the C translation of module_name with unrepresentable characters replaced by underscore. It should have the same length as module_name. up is a static array of strings (elements have type char *) that name the upstream modules whose interfaces are required to be resolved before commencing initialization of this one. The last element of the array must be NULL.
The macro also generates a forward declaration of the function, immediately prior to the function definition, so that you don't have to.
Note that module_name must be a string literal.

— C Macro: GH_STONED (obj)

Return the obj given, but marked as "permanent". This means that it can never be garbage collected.

— C Macro: GH_USE_MODULE (cvar, fullname)

Declare and later arrange for cvar (type SCM) to hold a resolved module object for fullname, a C string such as "(ice-9 q)". The string is saved in a C variable named by prefixing "s_" to cvar. You must use cvar as the second arg to GH_SELECT_MODULE_VAR.

— C Macro: GH_SELECT_MODULE_VAR (cvar, m_cvar, s_name)

Declare and later arrange for cvar (type SCM) to have the same value as the imported module m_cvar variable s_name. m_cvar is the SCM object declared with GH_USE_MODULE, and s_name is a string such as "q-empty?".

— C Macro: GH_CALLER0_FROM_VAR (cvar, proc_cvar)

Declare and define a procedure cvar that takes 0 (zero) args, which returns the result of calling gh_call0 on proc_cvar. proc_cvar is the SCM object declared with GH_SELECT_MODULE_VAR.

— C Macro: GH_CALLER1_FROM_VAR (cvar, proc_cvar)

Declare and define a procedure cvar that takes 1 (one) SCM arg, which returns the result of calling gh_call1 on proc_cvar and this arg. proc_var is the SCM object declared with GH_SELECT_MODULE_VAR.

— C Macro: GH_CALLER2_FROM_VAR (cvar, proc_cvar)

Declare and define a procedure cvar that takes 2 (two) SCM args, which returns the result of calling gh_call2 on proc_cvar and the args. proc_var is the SCM object declared with GH_SELECT_MODULE_VAR.

— C Macro: GH_CALLER3_FROM_VAR (cvar, proc_cvar)

Declare and define a procedure cvar that takes 3 (three) SCM args, which returns the result of calling gh_call3 on proc_cvar and the args. proc_var is the SCM object declared with GH_SELECT_MODULE_VAR.

The following are experimental (read: possibly will not be available for Guile 1.4.2 release) support for easily writing the forth argument to GH_NEEDY_MODULE_LINK_FUNC. Some compilers will complain about structure initialization not being strictly ANSI C. We'll see...

— C Macro: GH_UPSTREAM_MODULE_REF_COMMA (x)

Expand module handle x into the name of its string-holding C var followed by a comma. This is a convenience (or pre-processor abusive, depending on your point of view) macro meant to be used when forming the fourth argument to GH_NEEDY_MODULE_LINK_FUNC. x is the same as the first arg to GH_USE_MODULE.

— C Macro: GH_UPSTREAM_MODULE_REFS1 (m1)

Expand the module handle m1 into a static string array terminated by NULL, suitable for use as the fourth argument to GH_NEEDY_MODULE_LINK_FUNC.

— C Macro: GH_UPSTREAM_MODULE_REFS2 (m1, m2)

Expand the module handles m1 and m2 into a static string array terminated by NULL, suitable for use as the fourth argument to GH_NEEDY_MODULE_LINK_FUNC.

— C Macro: GH_UPSTREAM_MODULE_REFS3 (m1, m2, m3)

Expand the module handles m1 through m3 into a static string array terminated by NULL, suitable for use as the fourth argument to GH_NEEDY_MODULE_LINK_FUNC.

— C Macro: GH_UPSTREAM_MODULE_REFS4 (m1, m2, m3, m4)

Expand the module handles m1 through m4 into a static string array terminated by NULL, suitable for use as the fourth argument to GH_NEEDY_MODULE_LINK_FUNC.