diff options
Diffstat (limited to 'doc/ref/scheme-modules.texi')
-rw-r--r-- | doc/ref/scheme-modules.texi | 826 |
1 files changed, 826 insertions, 0 deletions
diff --git a/doc/ref/scheme-modules.texi b/doc/ref/scheme-modules.texi new file mode 100644 index 000000000..c0b37bc3c --- /dev/null +++ b/doc/ref/scheme-modules.texi @@ -0,0 +1,826 @@ +@page +@node Modules +@chapter Modules +@cindex 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 @emph{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 @emph{information +encapsulation}, which consists of packaging functional units into a +given name space that is clearly separated from other name spaces. +@cindex encapsulation +@cindex information encapsulation +@cindex name space + +The language features that allow this are usually called @emph{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 @code{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 +@emph{renaming} of objects from a foreign module, so they will not +clutter the global name space. +@cindex name space - private + +@menu +* Scheme and modules:: How modules are handled in standard Scheme. +* The Guile module system:: How Guile does it. +* Dynamic Libraries:: Loading libraries of compiled code at run time. +@end menu + + +@node Scheme and modules +@section Scheme and modules + +Scheme, as defined in R5RS, does @emph{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 @emph{provide} a feature, and when user programs +@emph{require} that feature, the library file is loaded in. + +For example, the file @file{random.scm} in the SLIB package contains the +line + +@smalllisp +(provide 'random) +@end smalllisp + +so to use its procedures, a user would type + +@smalllisp +(require 'random) +@end smalllisp + +and they would magically become available, @emph{but still have the same +names!} So this method is nice, but not as good as a full-featured +module system. + + +@node The Guile module system +@section The Guile 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. +@c fixme: Actually, was it available before? 1.4 seems a bit late... + +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. +@c fixme: Review: Need better C code interface commentary. + +@menu +* General Information about Modules:: Guile module basics. +* Using Guile Modules:: How to use existing modules. +* Creating Guile Modules:: How to package your code into modules. +* More Module Procedures:: Low-level module code. +* Module System Quirks:: Strange things to be aware of. +* Included Guile Modules:: Which modules come with Guile? +@end menu + +@node General Information about Modules +@subsection General Information about Modules + +A Guile module is a collection of named procedures, variables and +macros, altogether called the @dfn{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 @dfn{public}, in which case they are added to the +module's so-called @dfn{export list}; this set of public bindings is +called the module's @dfn{public interface} (@pxref{Creating Guile +Modules}). + +A client module @dfn{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 @dfn{select} which bindings to access and can also +algorithmically @dfn{rename} bindings. In contrast, when using the +providing module's public interface, the entire export list is available +without renaming (@pxref{Using Guile Modules}). + +To use a module, it must be found and loaded. All Guile modules have a +unique @dfn{module name}, which is a list of one or more symbols. +Examples are @code{(ice-9 popen)} or @code{(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 +@code{%load-extensions} (REFFIXME). The resulting file name is then +searched in all directories in the variable @code{%load-path}. For +example, the @code{(ice-9 popen)} module would result in the filename +@code{ice-9/popen.scm} and searched in the installation directory of +Guile and in all other directories in the load path. + +@c FIXME::martin: Not sure about this, maybe someone knows better? +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 +@code{use-syntax} syntactic form or the @code{#:use-syntax} module +definition option (@pxref{Creating Guile Modules}). + +Please note that there are some problems with the current module system +you should keep in mind (@pxref{Module System Quirks}). We hope to +address these eventually. + + +@node Using Guile Modules +@subsection Using Guile Modules + +To use a Guile module is to access either its public interface or a +custom interface (@pxref{General Information about Modules}). Both +types of access are handled by the syntactic form @code{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 @dfn{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: + +@smalllisp +(use-modules (ice-9 popen)) +@end smalllisp + +Here, the interface specification is @code{(ice-9 popen)}, and the +result is that the current module now has access to @code{open-pipe}, +@code{close-pipe}, @code{open-input-pipe}, and so on (@pxref{Included +Guile Modules}). + +Note in the previous example that if the current module had already +defined @code{open-pipe}, that definition would be overwritten by the +definition in @code{(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: + +@smalllisp +(use-modules ((ice-9 popen) + :select ((open-pipe . pipe-open) close-pipe) + :rename (symbol-prefix-proc 'unixy:))) +@end smalllisp + +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: + +@c Use `smallexample' since `table' is ugly. --ttn +@smallexample +(ice-9 popen) sees: current module sees: +open-pipe unixy:pipe-open +close-pipe unixy:close-pipe +@end smallexample + +This example also shows how to use the convenience procedure +@code{symbol-prefix-proc}. + +@c begin (scm-doc-string "boot-9.scm" "symbol-prefix-proc") +@deffn procedure symbol-prefix-proc prefix-sym +Return a procedure that prefixes its arg (a symbol) with +@var{prefix-sym}. +@c Insert gratuitous C++ slam here. --ttn +@end deffn + +@c begin (scm-doc-string "boot-9.scm" "use-modules") +@deffn syntax use-modules spec @dots{} +Resolve each interface specification @var{spec} into an interface and +arrange for these to be accessible by the current module. The return +value is unspecified. + +@var{spec} can be a list of symbols, in which case it names a module +whose public interface is found and used. + +@var{spec} can also be of the form: + +@smalllisp + (MODULE-NAME [:select SELECTION] [:rename RENAMER]) +@end smalllisp + +in which case a custom interface is newly created and used. +@var{module-name} is a list of symbols, as above; @var{selection} is a +list of selection-specs; and @var{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 @code{(ORIG . SEEN)}, where @var{orig} is the name in +the used module and @var{seen} is the name in the using module. Note +that @var{seen} is also passed through @var{renamer}. + +The @code{:select} and @code{:rename} clauses are optional. If both are +omitted, the returned interface has no bindings. If the @code{:select} +clause is omitted, @var{renamer} operates on the used module's public +interface. + +Signal error if module name is not resolvable. +@end deffn + + +@c FIXME::martin: Is this correct, and is there more to say? +@c FIXME::martin: Define term and concept `system transformer' somewhere. + +@deffn syntax use-syntax module-name +Load the module @code{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. +@end deffn + + +@node Creating Guile Modules +@subsection Creating Guile Modules + +When you want to create your own modules, you have to take the following +steps: + +@itemize @bullet +@item +Create a Scheme source file and add all variables and procedures you wish +to export, or which are required by the exported procedures. + +@item +Add a @code{define-module} form at the beginning. + +@item +Export all bindings which should be in the public interface, either +by using @code{define-public} or @code{export} (both documented below). +@end itemize + +@c begin (scm-doc-string "boot-9.scm" "define-module") +@deffn syntax define-module module-name [options @dots{}] +@var{module-name} is of the form @code{(hierarchy file)}. One +example of this is + +@smalllisp +(define-module (ice-9 popen)) +@end smalllisp + +@code{define-module} makes this module available to Guile programs under +the given @var{module-name}. + +The @var{options} are keyword/value pairs which specify more about the +defined module. The recognized options and their meaning is shown in +the following table. + +@c fixme: Should we use "#:" or ":"? + +@table @code +@item #:use-module @var{interface-specification} +Equivalent to a @code{(use-modules @var{interface-specification})} +(@pxref{Using Guile Modules}). + +@item #:use-syntax @var{module} +Use @var{module} when loading the currently defined module, and install +it as the syntax transformer. + +@item #:autoload @var{module} @var{symbol} +Load @var{module} whenever @var{symbol} is accessed. + +@item #:export @var{list} +Export all identifiers in @var{list}, which must be a list of symbols. +This is equivalent to @code{(export @var{list})} in the module body. + +@item #:no-backtrace +Tell Guile not to record information for procedure backtraces when +executing the procedures in this module. + +@item #:pure +Create a @dfn{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 @dfn{safe} modules, that is modules which +do not know anything about dangerous procedures. +@end table + +@end deffn +@c end + +@deffn syntax export variable @dots{} +Add all @var{variable}s (which must be symbols) to the list of exported +bindings of the current module. +@end deffn + +@c begin (scm-doc-string "boot-9.scm" "define-public") +@deffn syntax define-public @dots{} +Equivalent to @code{(begin (define foo ...) (export foo))}. +@end deffn +@c end + + +@node More Module Procedures +@subsection More Module Procedures + +@c FIXME::martin: Review me! + +@c FIXME::martin: Should this procedure be documented and supported +@c at all? + +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. + +@deffn primitive standard-eval-closure module +Return an eval closure for the module @var{module}. +@end deffn + + +@node Module System Quirks +@subsection 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. + +@itemize @bullet + +@item +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. + +@item +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 +@dfn{name-clash} situation, use a custom interface specification +(@pxref{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.) + +@item +[Add other quirks here.] + +@end itemize + + +@node Included Guile Modules +@subsection Included Guile Modules + +@c FIXME::martin: Review me! + +Some modules are included in the Guile distribution; here are references +to the entries in this manual which describe them in more detail: + +@table @strong +@item boot-9 +boot-9 is Guile's initialization module, and it is always loaded when +Guile starts up. + +@item (ice-9 debug) +Mikael Djurfeldt's source-level debugging support for Guile +(@pxref{Debugger User Interface}). + +@item (ice-9 threads) +Guile's support for multi threaded execution (@pxref{Scheduling}). + +@item (ice-9 rdelim) +Line- and character-delimited input (@pxref{Line/Delimited}). + +@item (ice-9 rw) +Block string input/output (@pxref{Block Reading and Writing}). + +@item (ice-9 documentation) +Online documentation (REFFIXME). + +@item (srfi srfi-1) +A library providing a lot of useful list and pair processing +procedures (@pxref{SRFI-1}). + +@item (srfi srfi-2) +Support for @code{and-let*} (@pxref{SRFI-2}). + +@item (srfi srfi-4) +Support for homogeneous numeric vectors (@pxref{SRFI-4}). + +@item (srfi srfi-6) +Support for some additional string port procedures (@pxref{SRFI-6}). + +@item (srfi srfi-8) +Multiple-value handling with @code{receive} (@pxref{SRFI-8}). + +@item (srfi srfi-9) +Record definition with @code{define-record-type} (@pxref{SRFI-9}). + +@item (srfi srfi-10) +Read hash extension @code{#,()} (@pxref{SRFI-10}). + +@item (srfi srfi-11) +Multiple-value handling with @code{let-values} and @code{let-values*} +(@pxref{SRFI-11}). + +@item (srfi srfi-13) +String library (@pxref{SRFI-13}). + +@item (srfi srfi-14) +Character-set library (@pxref{SRFI-14}). + +@item (srfi srfi-17) +Getter-with-setter support (@pxref{SRFI-17}). + +@item (ice-9 slib) +This module contains hooks for using Aubrey Jaffer's portable Scheme +library SLIB from Guile (@pxref{SLIB}). + +@c FIXME::martin: This module is not in the distribution. Remove it +@c from here? +@item (ice-9 jacal) +This module contains hooks for using Aubrey Jaffer's symbolic math +packge Jacal from Guile (@pxref{JACAL}). +@end table + + +@node Dynamic Libraries +@section Dynamic Libraries + +Most modern Unices have something called @dfn{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 @dfn{dynamic linking}@footnote{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 @dfn{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. + +@menu +* Low level dynamic linking:: +* Compiled Code Modules:: +* Dynamic Linking and Compiled Code Modules:: +@end menu + +@node Low level dynamic linking +@subsection 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 get's done +with it. + +@deffn primitive dynamic-link library +Find the shared library denoted by @var{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, @var{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 @file{/usr/lib} and @file{/usr/local/lib}. +@end deffn + +@deffn primitive dynamic-object? val +Determine whether @var{val} represents a dynamically linked object file. +@end deffn + +@deffn primitive dynamic-unlink dynobj +Unlink the indicated object file from the application. The argument +@var{dynobj} should be one of the values returned by +@code{dynamic-link}. When @code{dynamic-unlink} has been called on +@var{dynobj}, it is no longer usable as an argument to the functions +below and you will get type mismatch errors when you try to. +@end deffn + +@deffn primitive dynamic-func function dynobj +Search the C function indicated by @var{function} (a string or symbol) +in @var{dynobj} and return some Scheme object that can later be used +with @code{dynamic-call} to actually call this function. Right now, +these Scheme objects are formed by casting the address of the function +to @code{long} and converting this number to its Scheme representation. + +Regardless whether your C compiler prepends an underscore @samp{_} to +the global names in a program, you should @strong{not} include this +underscore in @var{function}. Guile knows whether the underscore is +needed or not and will add it when necessary. +@end deffn + +@deffn primitive dynamic-call function dynobj +Call the C function indicated by @var{function} and @var{dynobj}. The +function is passed no arguments and its return value is ignored. When +@var{function} is something returned by @code{dynamic-func}, call that +function and ignore @var{dynobj}. When @var{function} is a string (or +symbol, etc.), look it up in @var{dynobj}; this is equivalent to + +@smallexample +(dynamic-call (dynamic-func @var{function} @var{dynobj} #f)) +@end smallexample + +Interrupts are deferred while the C function is executing (with +@code{SCM_DEFER_INTS}/@code{SCM_ALLOW_INTS}). +@end deffn + +@deffn primitive dynamic-args-call function dynobj args +Call the C function indicated by @var{function} and @var{dynobj}, just +like @code{dynamic-call}, but pass it some arguments and return its +return value. The C function is expected to take two arguments and +return an @code{int}, just like @code{main}: + +@smallexample +int c_func (int argc, char **argv); +@end smallexample + +The parameter @var{args} must be a list of strings and is converted into +an array of @code{char *}. The array is passed in @var{argv} and its +size in @var{argc}. The return value is converted to a Scheme number +and returned from the call to @code{dynamic-args-call}. +@end deffn + +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: + +@smallexample +(define libc-obj (dynamic-link "libc.so")) +libc-obj +@result{} #<dynamic-object "libc.so"> +(dynamic-args-call 'rand libc-obj '()) +@result{} 269167349 +(dynamic-unlink libc-obj) +libc-obj +@result{} #<dynamic-object "libc.so" (unlinked)> +@end smallexample + +As you can see, after calling @code{dynamic-unlink} on a dynamically +linked library, it is marked as @samp{(unlinked)} and you are no longer +able to use it with @code{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, @code{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, +@code{dynamic-call} and @code{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 +@file{libX11} with @code{dynamic-link} and then construct a beautiful +graphical user interface just by using @code{dynamic-call} and +@code{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 @file{libffi}, a library that implements a @dfn{foreign +function interface} for a number of different platforms. With it, you +can extend the Spartan functionality of @code{dynamic-call} and +@code{dynamic-args-call} considerably. There is glue code available in +the Guile contrib archive to make @file{libffi} accessible from Guile. + +@node Compiled Code Modules +@subsection Putting Compiled Code into Modules + +@c FIXME::martin: Change all gh_ references to their scm_ equivalents. + +The new primitives that you add to Guile with @code{gh_new_procedure} +or with any of the other mechanisms are normally placed into the same +module as all the other builtin procedures (like @code{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 @code{gh_new_procedure} and the functions used by the snarfer +really do is to add the new primitives to whatever module is the +@emph{current module} when they are called. This is analogous to the +way Scheme code is put into modules: the @code{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 +@code{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 @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 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 @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. + +@node Dynamic Linking and Compiled Code Modules +@subsection Dynamic Linking and Compiled Code Modules + +The most interesting application of dynamically linked libraries is +probably to use them for providing @emph{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 @samp{(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 @code{j0} function, tho. + +@c FIXME::martin: Change all gh_ references to their scm_ equivalents. + +@smallexample +#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); +@} +@end smallexample + +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 @code{libtool} documentation for how to +create dynamically linkable libraries portably. + +@smallexample +gcc -shared -o libbessel.so -fPIC bessel.c +@end smallexample + +Now fire up Guile: + +@smalllisp +(define bessel-lib (dynamic-link "./libbessel.so")) +(dynamic-call "init_math_bessel" bessel-lib) +(j0 2) +@result{} 0.223890779141236 +@end smalllisp + +The filename @file{./libbessel.so} should be pointing to the shared +library produced with the @code{gcc} command above, of course. The +second line of the Guile interaction will call the +@code{init_math_bessel} function which in turn will register the C +function @code{j0_wrapper} with the Guile interpreter under the name +@code{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 +@code{apropos} has to say about @code{j0}: + +@smallexample +(apropos 'j0) +@print{} the-root-module: j0 #<primitive-procedure j0> +@end smallexample + +As you can see, @code{j0} is contained in the root module, where all +the other Guile primitives like @code{display}, etc live. In general, +a primitive is put into whatever module is the @dfn{current module} at +the time @code{gh_new_procedure} is called. To put @code{j0} into its +own module named @samp{(math bessel)}, we need to make a call to +@code{scm_register_module_xxx}. Additionally, to have Guile perform +the dynamic linking automatically, we need to put @file{libbessel.so} +into a place where Guile can find it. The call to +@code{scm_register_module_xxx} should be contained in a specially +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}: + +@smallexample +void scm_init_math_bessel_module () +@{ + scm_register_module_xxx ("math bessel", init_math_bessel); +@} +@end smallexample + +The general pattern for the name of a module init function is: +@samp{scm_init_}, followed by the name of the module where the +individual hierarchical components are concatenated with underscores, +followed by @samp{_module}. It should call +@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. + +After @file{libbessel.so} has been rebuild, we need to place the shared +library into the right place. When Guile tries to autoload the +@samp{(math bessel)} module, it looks not only for a file called +@file{math/bessel.scm} in its @code{%load-path}, but also for +@file{math/libbessel.so}. So all we need to do is to create a directory +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. + +@smallexample +% mkdir maths +% cd maths +% ln -s ../libbessel.so . +% cd .. +% guile +guile> (use-modules (math bessel)) +guile> (j0 2) +0.223890779141236 +guile> (apropos 'j0) +@print{} bessel: j0 #<primitive-procedure j0> +@end smallexample + +That's it! + +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). + + +@c Local Variables: +@c TeX-master: "guile.texi" +@c End: |