76 |
|
|
77 |
In 1996 Tom Lord implemented a full-featured module system for Guile which |
In 1996 Tom Lord implemented a full-featured module system for Guile which |
78 |
allows loading Scheme source files into a private name space. This system has |
allows loading Scheme source files into a private name space. This system has |
79 |
been in available since Guile version 1.4. |
been in available since at least Guile version 1.1. |
|
@c fixme: Actually, was it available before? 1.4 seems a bit late... |
|
80 |
|
|
81 |
For Guile version 1.5.0 and later, the system has been improved to have better |
For Guile version 1.5.0 and later, the system has been improved to have better |
82 |
integration from C code, more fine-grained user control over interfaces, and |
integration from C code, more fine-grained user control over interfaces, and |
499 |
complete control over which library is loaded when and what gets done |
complete control over which library is loaded when and what gets done |
500 |
with it. |
with it. |
501 |
|
|
502 |
@deffn {Scheme Procedure} dynamic-link library |
@deffn {Scheme Procedure} dynamic-link filename |
503 |
@deffnx {C Function} scm_dynamic_link (library) |
@deffnx {C Function} scm_dynamic_link (filename) |
504 |
Find the shared library denoted by @var{library} (a string) and link it |
Find the shared object (shared library) denoted by |
505 |
into the running Guile application. When everything works out, return a |
@var{filename} and link it into the running Guile |
506 |
Scheme object suitable for representing the linked object file. |
application. The returned |
507 |
Otherwise an error is thrown. How object files are searched is system |
scheme object is a ``handle'' for the library which can |
508 |
dependent. |
be passed to @code{dynamic-func}, @code{dynamic-call} etc. |
509 |
|
|
510 |
Normally, @var{library} is just the name of some shared library file |
Searching for object files is system dependent. Normally, |
511 |
that will be searched for in the places where shared libraries usually |
if @var{filename} does have an explicit directory it will |
512 |
reside, such as in @file{/usr/lib} and @file{/usr/local/lib}. |
be searched for in locations |
513 |
|
such as @file{/usr/lib} and @file{/usr/local/lib}. |
514 |
@end deffn |
@end deffn |
515 |
|
|
516 |
@deffn {Scheme Procedure} dynamic-object? obj |
@deffn {Scheme Procedure} dynamic-object? obj |
517 |
@deffnx {C Function} scm_dynamic_object_p (obj) |
@deffnx {C Function} scm_dynamic_object_p (obj) |
518 |
Return @code{#t} if @var{obj} is a dynamic library handle, or @code{#f} |
Return @code{#t} if @var{obj} is a dynamic object handle, |
519 |
otherwise. |
or @code{#f} otherwise. |
520 |
@end deffn |
@end deffn |
521 |
|
|
522 |
@deffn {Scheme Procedure} dynamic-unlink dobj |
@deffn {Scheme Procedure} dynamic-unlink dobj |
523 |
@deffnx {C Function} scm_dynamic_unlink (dobj) |
@deffnx {C Function} scm_dynamic_unlink (dobj) |
524 |
Unlink the indicated object file from the application. The |
Unlink a dynamic object from the application, if possible. The |
525 |
argument @var{dobj} must have been obtained by a call to |
object must have been linked by @code{dynamic-link}, with |
526 |
@code{dynamic-link}. After @code{dynamic-unlink} has been |
@var{dobj} the corresponding handle. After this procedure |
527 |
called on @var{dobj}, its content is no longer accessible. |
is called, the handle can no longer be used to access the |
528 |
|
object. |
529 |
@end deffn |
@end deffn |
530 |
|
|
531 |
@deffn {Scheme Procedure} dynamic-func name dobj |
@deffn {Scheme Procedure} dynamic-func name dobj |
532 |
@deffnx {C Function} scm_dynamic_func (name, dobj) |
@deffnx {C Function} scm_dynamic_func (name, dobj) |
533 |
Search the dynamic object @var{dobj} for the C function |
Return a ``handle'' for the function @var{name} in the |
534 |
indicated by the string @var{name} and return some Scheme |
shared object referred to by @var{dobj}. The handle |
535 |
handle that can later be used with @code{dynamic-call} to |
can be passed to @code{dynamic-call} to actually |
536 |
actually call the function. |
call the function. |
537 |
|
|
538 |
Regardless whether your C compiler prepends an underscore @samp{_} to |
Regardless whether your C compiler prepends an underscore |
539 |
the global names in a program, you should @strong{not} include this |
@samp{_} to the global names in a program, you should |
540 |
underscore in @var{function}. Guile knows whether the underscore is |
@strong{not} include this underscore in @var{name} |
541 |
needed or not and will add it when necessary. |
since it will be added automatically when necessary. |
542 |
@end deffn |
@end deffn |
543 |
|
|
544 |
@deffn {Scheme Procedure} dynamic-call func dobj |
@deffn {Scheme Procedure} dynamic-call func dobj |
584 |
When dynamic linking is disabled or not supported on your system, |
When dynamic linking is disabled or not supported on your system, |
585 |
the above functions throw errors, but they are still available. |
the above functions throw errors, but they are still available. |
586 |
|
|
587 |
Here is a small example that works on GNU/Linux: |
Here is a small example that may work on GNU/Linux: |
588 |
|
|
589 |
@smallexample |
@smallexample |
590 |
(define libc-obj (dynamic-link "libc.so")) |
(define libc-obj (dynamic-link "libc.so")) |
658 |
|
|
659 |
Therefore, all we need to do is to make sure that the right module is |
Therefore, all we need to do is to make sure that the right module is |
660 |
current when calling @code{gh_new_procedure} for our new primitives. |
current when calling @code{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. |
|
|
|
|
|
@deftypefun void scm_register_module_xxx (char *@var{name}, void (*@var{initfunc})(void)) |
|
|
Register with Guile that @var{initfunc} will provide the contents of the |
|
|
module @var{name}. |
|
|
|
|
|
The function @var{initfunc} should perform the usual initialization |
|
|
actions for your new primitives, like calling @code{gh_new_procedure} or |
|
|
including the file produced by the snarfer. When @var{initfunc} is |
|
|
called, the current module is a newly created module with a name as |
|
|
indicated by @var{name}. Each definition that is added to it will be |
|
|
automatically exported. |
|
|
|
|
|
The string @var{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 @code{(foo |
|
|
bar)}, which is a list, should be written as @code{"foo bar"} for the |
|
|
@var{name} parameter. |
|
|
|
|
|
You can call @code{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 @code{scm_register_module_xxx} appears in the next section. |
|
|
@end deftypefun |
|
|
|
|
|
Now, instead of calling the initialization function at program startup, |
|
|
you should simply call @code{scm_register_module_xxx} and pass it the |
|
|
initialization function. When the named module is later requested by |
|
|
Scheme code with @code{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. |
|
661 |
|
|
662 |
@node Dynamic Linking and Compiled Code Modules |
@node Dynamic Linking and Compiled Code Modules |
663 |
@subsection Dynamic Linking and Compiled Code Modules |
@subsection Dynamic Linking and Compiled Code Modules |
738 |
As you can see, @code{j0} is contained in the root module, where all |
As you can see, @code{j0} is contained in the root module, where all |
739 |
the other Guile primitives like @code{display}, etc live. In general, |
the other Guile primitives like @code{display}, etc live. In general, |
740 |
a primitive is put into whatever module is the @dfn{current module} at |
a primitive is put into whatever module is the @dfn{current module} at |
741 |
the time @code{gh_new_procedure} is called. To put @code{j0} into its |
the time @code{gh_new_procedure} is called. |
742 |
own module named @samp{(math bessel)}, we need to make a call to |
|
743 |
@code{scm_register_module_xxx}. Additionally, to have Guile perform |
A compiled module should have a specially named @dfn{module init |
744 |
the dynamic linking automatically, we need to put @file{libbessel.so} |
function}. Guile knows about this special name and will call that |
745 |
into a place where Guile can find it. The call to |
function automatically after having linked in the shared library. For |
746 |
@code{scm_register_module_xxx} should be contained in a specially |
our example, we add the following code to @file{bessel.c}: |
|
named @dfn{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 |
|
|
@file{bessel.c}: |
|
747 |
|
|
748 |
@smallexample |
@smallexample |
749 |
void scm_init_math_bessel_module () |
void scm_init_math_bessel_module () |
750 |
@{ |
@{ |
751 |
scm_register_module_xxx ("math bessel", init_math_bessel); |
/* contents currently unavailable. */ |
752 |
@} |
@} |
753 |
@end smallexample |
@end smallexample |
754 |
|
|
755 |
The general pattern for the name of a module init function is: |
The general pattern for the name of a module init function is: |
756 |
@samp{scm_init_}, followed by the name of the module where the |
@samp{scm_init_}, followed by the name of the module where the |
757 |
individual hierarchical components are concatenated with underscores, |
individual hierarchical components are concatenated with underscores, |
758 |
followed by @samp{_module}. It should call |
followed by @samp{_module}. |
|
@code{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 |
|
|
@emph{current module} so that all definitions that the initialization |
|
|
functions makes will end up in the correct module. |
|
759 |
|
|
760 |
After @file{libbessel.so} has been rebuild, we need to place the shared |
After @file{libbessel.so} has been rebuild, we need to place the shared |
761 |
library into the right place. When Guile tries to autoload the |
library into the right place. |
762 |
@samp{(math bessel)} module, it looks not only for a file called |
|
763 |
@file{math/bessel.scm} in its @code{%load-path}, but also for |
Once the module has been correctly installed, it should be possible to |
764 |
@file{math/libbessel.so}. So all we need to do is to create a directory |
use it like this: |
|
called @file{math} somewhere in Guile's @code{%load-path} and place |
|
|
@file{libbessel.so} there. Normally, the current directory @file{.} is |
|
|
in the @code{%load-path}, so we just use that for this example. |
|
765 |
|
|
766 |
@smallexample |
@smallexample |
|
% mkdir maths |
|
|
% cd maths |
|
|
% ln -s ../libbessel.so . |
|
|
% cd .. |
|
|
% guile |
|
767 |
guile> (use-modules (math bessel)) |
guile> (use-modules (math bessel)) |
768 |
guile> (j0 2) |
guile> (j0 2) |
769 |
0.223890779141236 |
0.223890779141236 |
773 |
|
|
774 |
That's it! |
That's it! |
775 |
|
|
|
Note that we used a symlink to make @file{libbessel.so} appear in the |
|
|
right spot. This is probably not a bad idea in general. The |
|
|
directories that the @file{%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 @samp{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). |
|
|
|
|
|
|
|
776 |
@node Variables |
@node Variables |
777 |
@section Variables |
@section Variables |
778 |
@tpindex Variables |
@tpindex Variables |