Putting Compiled Code into Modules
----------------------------------
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.
- Function: void scm_register_module_xxx (char *NAME, void
(*INITFUNC)(void))
Register with Guile that INITFUNC will provide the contents of the
module NAME.
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 hierachical 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.