Commit | Line | Data |
---|---|---|
38a93523 NJ |
1 | @page |
2 | @node Modules | |
3 | @chapter Modules | |
4 | @cindex modules | |
5 | ||
6 | [FIXME: somewhat babbling; should be reviewed by someone who understands | |
7 | modules, once the new module system is in place] | |
8 | ||
9 | When programs become large, naming conflicts can occur when a function | |
10 | or global variable defined in one file has the same name as a function | |
11 | or global variable in another file. Even just a @emph{similarity} | |
12 | between function names can cause hard-to-find bugs, since a programmer | |
13 | might type the wrong function name. | |
14 | ||
15 | The approach used to tackle this problem is called @emph{information | |
16 | encapsulation}, which consists of packaging functional units into a | |
17 | given name space that is clearly separated from other name spaces. | |
18 | @cindex encapsulation | |
19 | @cindex information encapsulation | |
20 | @cindex name space | |
21 | ||
22 | The language features that allow this are usually called @emph{the | |
23 | module system} because programs are broken up into modules that are | |
24 | compiled separately (or loaded separately in an interpreter). | |
25 | ||
26 | Older languages, like C, have limited support for name space | |
27 | manipulation and protection. In C a variable or function is public by | |
28 | default, and can be made local to a module with the @code{static} | |
29 | keyword. But you cannot reference public variables and functions from | |
30 | another module with different names. | |
31 | ||
32 | More advanced module systems have become a common feature in recently | |
33 | designed languages: ML, Python, Perl, and Modula 3 all allow the | |
34 | @emph{renaming} of objects from a foreign module, so they will not | |
35 | clutter the global name space. | |
36 | @cindex name space - private | |
37 | ||
38 | @menu | |
39 | * Scheme and modules:: | |
40 | * The Guile module system:: | |
41 | * Dynamic Libraries:: Loading libraries of compiled code at run time. | |
42 | * Dynamic Linking from Marius:: | |
43 | @end menu | |
44 | ||
45 | ||
46 | @node Scheme and modules | |
47 | @section Scheme and modules | |
48 | ||
49 | Scheme, as defined in R4RS, does @emph{not} have a module system at all. | |
50 | ||
51 | Aubrey Jaffer, mostly to support his portable Scheme library SLIB, | |
52 | implemented a provide/require mechanism for many Scheme implementations. | |
53 | Library files in SLIB @emph{provide} a feature, and when user programs | |
54 | @emph{require} that feature, the library file is loaded in. | |
55 | ||
56 | For example, the file @file{random.scm} in the SLIB package contains the | |
57 | line | |
58 | @smalllisp | |
59 | (provide 'random) | |
60 | @end smalllisp | |
61 | so to use its procedures, a user would type | |
62 | @smalllisp | |
63 | (require 'random) | |
64 | @end smalllisp | |
65 | and they would magically become available, @emph{but still have the same | |
66 | names!} So this method is nice, but not as good as a full-featured | |
67 | module system. | |
68 | ||
69 | ||
70 | @node The Guile module system | |
71 | @section The Guile module system | |
72 | ||
73 | In 1996 Tom Lord implemented a full-featured module system for Guile | |
74 | which allows loading Scheme source files into a private name space. | |
75 | ||
76 | This module system is regarded as being rather idiosyncratic, and will | |
77 | probably change to something more like the ML module system, so for now | |
78 | I will simply describe how it works for a couple of simple cases. | |
79 | ||
80 | First of all, the Guile module system sets up a hierarchical name space, | |
81 | and that name space can be represented like Unix pathnames preceded by a | |
82 | @key{#} character. The root name space for all Guile-supplied modules | |
83 | is called @code{ice-9}. | |
84 | ||
85 | So for example, the SLIB interface, contained in | |
86 | @file{$srcdir/ice-9/slib.scm}, starts out with | |
87 | @smalllisp | |
88 | (define-module (ice-9 slib)) | |
89 | @end smalllisp | |
90 | and a user program can use | |
91 | @smalllisp | |
92 | (use-modules (ice-9 slib)) | |
93 | @end smalllisp | |
94 | to have access to all procedures and variables defined within the slib | |
95 | module with @code{(define-public ...)}. | |
96 | ||
97 | So here are the functions involved: | |
98 | @c begin (scm-doc-string "boot-9.scm" "define-module") | |
99 | @deffn syntax define-module module-specification | |
100 | @var{module-specification} is of the form @code{(hierarchy file)}. One | |
101 | example of this is | |
102 | @smalllisp | |
103 | (use-modules (ice-9 slib)) | |
104 | @end smalllisp | |
105 | define-module makes this module available to Guile programs under the | |
106 | given @var{module-specification}. | |
107 | @end deffn | |
108 | @c end | |
109 | ||
110 | @c begin (scm-doc-string "boot-9.scm" "define-public") | |
111 | @deffn syntax define-public @dots{} | |
112 | Makes a procedure or variable available to programs that use the current | |
113 | module. | |
114 | @end deffn | |
115 | @c end | |
116 | ||
117 | @c begin (scm-doc-string "boot-9.scm" "use-modules") | |
118 | @deffn syntax use-modules module-specification | |
119 | @var{module-specification} is of the form @code{(hierarchy file)}. One | |
120 | example of this is | |
121 | @smalllisp | |
122 | (use-modules (ice-9 slib)) | |
123 | @end smalllisp | |
124 | use-modules allows the current Guile program to use all publicly defined | |
125 | procedures and variables in the module denoted by | |
126 | @var{module-specification}. | |
127 | @end deffn | |
128 | @c end | |
129 | ||
130 | [FIXME: must say more, and explain, and also demonstrate a private name | |
131 | space use, and demonstrate how one would do Python's "from Tkinter | |
132 | import *" versus "import Tkinter". Must also add something about paths | |
133 | and standards for contributed modules.] | |
134 | ||
135 | @c docstring begin (texi-doc-string "guile" "standard-eval-closure") | |
136 | @deffn primitive standard-eval-closure module | |
137 | Return an eval closure for the module @var{module}. | |
138 | @end deffn | |
139 | ||
140 | Some modules are included in the Guile distribution; here are references | |
141 | to the entries in this manual which describe them in more detail: | |
142 | @table @strong | |
143 | @item boot-9 | |
144 | boot-9 is Guile's initialization module, and it is always loaded when | |
145 | Guile starts up. | |
146 | @item (ice-9 debug) | |
147 | Mikael Djurfeldt's source-level debugging support for Guile | |
148 | (@pxref{Debugger User Interface}). | |
149 | @item (ice-9 threads) | |
150 | Guile's support for multi threaded execution (@pxref{Scheduling}). | |
151 | @item (ice-9 slib) | |
152 | This module contains hooks for using Aubrey Jaffer's portable Scheme | |
153 | library SLIB from Guile (@pxref{SLIB}). | |
154 | @item (ice-9 jacal) | |
155 | This module contains hooks for using Aubrey Jaffer's symbolic math | |
156 | packge Jacal from Guile (@pxref{JACAL}). | |
157 | @end table | |
158 | ||
159 | ||
160 | @node Dynamic Libraries | |
161 | @section Dynamic Libraries | |
162 | ||
163 | Often you will want to extend Guile by linking it with some existing | |
164 | system library. For example, linking Guile with a @code{curses} or | |
165 | @code{termcap} library would be useful if you want to implement a | |
166 | full-screen user interface for a Guile application. However, if you | |
167 | were to link Guile with these libraries at compile time, it would bloat | |
168 | the interpreter considerably, affecting everyone on the system even if | |
169 | the new libraries are useful only to you. Also, every time a new | |
170 | library is installed, you would have to reconfigure, recompile and | |
171 | relink Guile merely in order to provide a new interface. | |
172 | ||
173 | Many Unix systems permit you to get around this problem by using | |
174 | @dfn{dynamic loading}. When a new library is linked, it can be made a | |
175 | @dfn{dynamic library} by passing certain switches to the linker. A | |
176 | dynamic library does not need to be linked with an executable image at | |
177 | link time; instead, the executable may choose to load it dynamically at | |
178 | run time. This is a powerful concept that permits an executable to link | |
179 | itself with almost any library without reconfiguration, if it has been | |
180 | written properly. | |
181 | ||
182 | Guile's dynamic linking functions make it relatively easy to write a | |
183 | module that incorporates code from third-party object code libraries. | |
184 | ||
185 | @c ARGFIXME fname/library-file | |
186 | @c docstring begin (texi-doc-string "guile" "dynamic-link") | |
187 | @deffn primitive dynamic-link fname | |
188 | Open the dynamic library @var{library-file}. A library handle | |
189 | representing the opened library is returned; this handle should be used | |
190 | as the @var{lib} argument to the following functions. | |
191 | @end deffn | |
192 | ||
193 | @c docstring begin (texi-doc-string "guile" "dynamic-object?") | |
194 | @deffn primitive dynamic-object? obj | |
195 | Return @code{#t} if @var{obj} is a dynamic library handle, or @code{#f} | |
196 | otherwise. | |
197 | @end deffn | |
198 | ||
199 | @c ARGFIXME dobj/dynobj/library-handle | |
200 | @c docstring begin (texi-doc-string "guile" "dynamic-unlink") | |
201 | @deffn primitive dynamic-unlink dobj | |
202 | Unlink the library represented by @var{library-handle}, | |
203 | and remove any imported symbols from the address space. | |
204 | GJB:FIXME:DOC: 2nd version below: | |
205 | Unlink the indicated object file from the application. The | |
206 | argument @var{dynobj} must have been obtained by a call to | |
207 | @code{dynamic-link}. After @code{dynamic-unlink} has been | |
208 | called on @var{dynobj}, its content is no longer accessible. | |
209 | @end deffn | |
210 | ||
211 | @c ARGFIXME symb/func/function dobj/lib/dynobj | |
212 | @c docstring begin (texi-doc-string "guile" "dynamic-func") | |
213 | @deffn primitive dynamic-func name dobj | |
214 | Search the dynamic object @var{dobj} for the C function | |
215 | indicated by the string @var{name} and return some Scheme | |
216 | handle that can later be used with @code{dynamic-call} to | |
217 | actually call the function. | |
218 | ||
219 | Regardless whether your C compiler prepends an underscore @samp{_} to | |
220 | the global names in a program, you should @strong{not} include this | |
221 | underscore in @var{function}. Guile knows whether the underscore is | |
222 | needed or not and will add it when necessary. | |
223 | @end deffn | |
224 | ||
225 | @c ARGFIXME lib-thunk/func/function lib/dobj/dynobj | |
226 | @c docstring begin (texi-doc-string "guile" "dynamic-call") | |
227 | @deffn primitive dynamic-call func dobj | |
228 | Call @var{lib-thunk}, a procedure of no arguments. If @var{lib-thunk} | |
229 | is a string, it is assumed to be a symbol found in the dynamic library | |
230 | @var{lib} and is fetched with @code{dynamic-func}. Otherwise, it should | |
231 | be a function handle returned by a previous call to @code{dynamic-func}. | |
232 | The return value is unspecified. | |
233 | GJB:FIXME:DOC 2nd version below | |
234 | Call the C function indicated by @var{function} and @var{dynobj}. The | |
235 | function is passed no arguments and its return value is ignored. When | |
236 | @var{function} is something returned by @code{dynamic-func}, call that | |
237 | function and ignore @var{dynobj}. When @var{function} is a string (or | |
238 | symbol, etc.), look it up in @var{dynobj}; this is equivalent to | |
239 | ||
240 | @smallexample | |
241 | (dynamic-call (dynamic-func @var{function} @var{dynobj} #f)) | |
242 | @end smallexample | |
243 | ||
244 | Interrupts are deferred while the C function is executing (with | |
245 | @code{SCM_DEFER_INTS}/@code{SCM_ALLOW_INTS}). | |
246 | @end deffn | |
247 | ||
248 | @c ARGFIXME func/proc/function dobj/dynobj | |
249 | @c docstring begin (texi-doc-string "guile" "dynamic-args-call") | |
250 | @deffn primitive dynamic-args-call func dobj args | |
251 | Call @var{proc}, a dynamically loaded function, passing it the argument | |
252 | list @var{args} (a list of strings). As with @code{dynamic-call}, | |
253 | @var{proc} should be either a function handle or a string, in which case | |
254 | it is first fetched from @var{lib} with @code{dynamic-func}. | |
255 | ||
256 | @var{proc} is assumed to return an integer, which is used as the return | |
257 | value from @code{dynamic-args-call}. | |
258 | ||
259 | GJB:FIXME:DOC 2nd version below | |
260 | Call the C function indicated by @var{function} and @var{dynobj}, just | |
261 | like @code{dynamic-call}, but pass it some arguments and return its | |
262 | return value. The C function is expected to take two arguments and | |
263 | return an @code{int}, just like @code{main}: | |
264 | ||
265 | @smallexample | |
266 | int c_func (int argc, char **argv); | |
267 | @end smallexample | |
268 | ||
269 | The parameter @var{args} must be a list of strings and is converted into | |
270 | an array of @code{char *}. The array is passed in @var{argv} and its | |
271 | size in @var{argc}. The return value is converted to a Scheme number | |
272 | and returned from the call to @code{dynamic-args-call}. | |
273 | @end deffn | |
274 | ||
275 | @c docstring begin (texi-doc-string "guile" "c-registered-modules") | |
276 | @deffn primitive c-registered-modules | |
277 | Return a list of the object code modules that have been imported into | |
278 | the current Guile process. Each element of the list is a pair whose | |
279 | car is the name of the module, and whose cdr is the function handle | |
280 | for that module's initializer function. The name is the string that | |
281 | has been passed to scm_register_module_xxx. | |
282 | @end deffn | |
283 | ||
284 | @c docstring begin (texi-doc-string "guile" "c-clear-registered-modules") | |
285 | @deffn primitive c-clear-registered-modules | |
286 | Destroy the list of modules registered with the current Guile process. | |
287 | The return value is unspecified. @strong{Warning:} this function does | |
288 | not actually unlink or deallocate these modules, but only destroys the | |
289 | records of which modules have been loaded. It should therefore be used | |
290 | only by module bookkeeping operations. | |
291 | @end deffn | |
292 | ||
293 | [FIXME: provide a brief example here of writing the C hooks for an | |
294 | object code module, and using dynamic-link and dynamic-call to load the | |
295 | module.] | |
296 | ||
297 | ||
298 | @node Dynamic Linking from Marius | |
299 | @section Dynamic Linking from Marius | |
300 | ||
301 | @c NJFIXME primitive documentation here duplicates (and is generally | |
302 | @c better than) documentation for the same primitives earlier on. | |
303 | ||
304 | Most modern Unices have something called @dfn{shared libraries}. This | |
305 | ordinarily means that they have the capability to share the executable | |
306 | image of a library between several running programs to save memory and | |
307 | disk space. But generally, shared libraries give a lot of additional | |
308 | flexibility compared to the traditional static libraries. In fact, | |
309 | calling them `dynamic' libraries is as correct as calling them `shared'. | |
310 | ||
311 | Shared libraries really give you a lot of flexibility in addition to the | |
312 | memory and disk space savings. When you link a program against a shared | |
313 | library, that library is not closely incorporated into the final | |
314 | executable. Instead, the executable of your program only contains | |
315 | enough information to find the needed shared libraries when the program | |
316 | is actually run. Only then, when the program is starting, is the final | |
317 | step of the linking process performed. This means that you need not | |
318 | recompile all programs when you install a new, only slightly modified | |
319 | version of a shared library. The programs will pick up the changes | |
320 | automatically the next time they are run. | |
321 | ||
322 | Now, when all the necessary machinery is there to perform part of the | |
323 | linking at run-time, why not take the next step and allow the programmer | |
324 | to explicitly take advantage of it from within his program? Of course, | |
325 | many operating systems that support shared libraries do just that, and | |
326 | chances are that Guile will allow you to access this feature from within | |
327 | your Scheme programs. As you might have guessed already, this feature | |
328 | is called @dfn{dynamic linking}@footnote{Some people also refer to the | |
329 | final linking stage at program startup as `dynamic linking', so if you | |
330 | want to make yourself perfectly clear, it is probably best to use the | |
331 | more technical term @dfn{dlopening}, as suggested by Gordon Matzigkeit | |
332 | in his libtool documentation.} | |
333 | ||
334 | As with many aspects of Guile, there is a low-level way to access the | |
335 | dynamic linking apparatus, and a more high-level interface that | |
336 | integrates dynamically linked libraries into the module system. | |
337 | ||
338 | @menu | |
339 | * Low level dynamic linking:: | |
340 | * Compiled Code Modules:: | |
341 | * Dynamic Linking and Compiled Code Modules:: | |
342 | @end menu | |
343 | ||
344 | @node Low level dynamic linking | |
345 | @subsection Low level dynamic linking | |
346 | ||
347 | When using the low level procedures to do your dynamic linking, you have | |
348 | complete control over which library is loaded when and what get's done | |
349 | with it. | |
350 | ||
351 | @deffn primitive dynamic-link library | |
352 | Find the shared library denoted by @var{library} (a string) and link it | |
353 | into the running Guile application. When everything works out, return a | |
354 | Scheme object suitable for representing the linked object file. | |
355 | Otherwise an error is thrown. How object files are searched is system | |
356 | dependent. | |
357 | ||
358 | Normally, @var{library} is just the name of some shared library file | |
359 | that will be searched for in the places where shared libraries usually | |
360 | reside, such as in @file{/usr/lib} and @file{/usr/local/lib}. | |
361 | @end deffn | |
362 | ||
363 | @deffn primitive dynamic-object? val | |
364 | Determine whether @var{val} represents a dynamically linked object file. | |
365 | @end deffn | |
366 | ||
367 | @deffn primitive dynamic-unlink dynobj | |
368 | Unlink the indicated object file from the application. The argument | |
369 | @var{dynobj} should be one of the values returned by | |
370 | @code{dynamic-link}. When @code{dynamic-unlink} has been called on | |
371 | @var{dynobj}, it is no longer usable as an argument to the functions | |
372 | below and you will get type mismatch errors when you try to. | |
373 | @end deffn | |
374 | ||
375 | @deffn primitive dynamic-func function dynobj | |
376 | Search the C function indicated by @var{function} (a string or symbol) | |
377 | in @var{dynobj} and return some Scheme object that can later be used | |
378 | with @code{dynamic-call} to actually call this function. Right now, | |
379 | these Scheme objects are formed by casting the address of the function | |
380 | to @code{long} and converting this number to its Scheme representation. | |
381 | ||
382 | Regardless whether your C compiler prepends an underscore @samp{_} to | |
383 | the global names in a program, you should @strong{not} include this | |
384 | underscore in @var{function}. Guile knows whether the underscore is | |
385 | needed or not and will add it when necessary. | |
386 | @end deffn | |
387 | ||
388 | @deffn primitive dynamic-call function dynobj | |
389 | Call the C function indicated by @var{function} and @var{dynobj}. The | |
390 | function is passed no arguments and its return value is ignored. When | |
391 | @var{function} is something returned by @code{dynamic-func}, call that | |
392 | function and ignore @var{dynobj}. When @var{function} is a string (or | |
393 | symbol, etc.), look it up in @var{dynobj}; this is equivalent to | |
394 | ||
395 | @smallexample | |
396 | (dynamic-call (dynamic-func @var{function} @var{dynobj} #f)) | |
397 | @end smallexample | |
398 | ||
399 | Interrupts are deferred while the C function is executing (with | |
400 | @code{SCM_DEFER_INTS}/@code{SCM_ALLOW_INTS}). | |
401 | @end deffn | |
402 | ||
403 | @deffn primitive dynamic-args-call function dynobj args | |
404 | Call the C function indicated by @var{function} and @var{dynobj}, just | |
405 | like @code{dynamic-call}, but pass it some arguments and return its | |
406 | return value. The C function is expected to take two arguments and | |
407 | return an @code{int}, just like @code{main}: | |
408 | ||
409 | @smallexample | |
410 | int c_func (int argc, char **argv); | |
411 | @end smallexample | |
412 | ||
413 | The parameter @var{args} must be a list of strings and is converted into | |
414 | an array of @code{char *}. The array is passed in @var{argv} and its | |
415 | size in @var{argc}. The return value is converted to a Scheme number | |
416 | and returned from the call to @code{dynamic-args-call}. | |
417 | @end deffn | |
418 | ||
419 | When dynamic linking is disabled or not supported on your system, | |
420 | the above functions throw errors, but they are still available. | |
421 | ||
422 | Here is a small example that works on GNU/Linux: | |
423 | ||
424 | @smallexample | |
425 | (define libc-obj (dynamic-link "libc.so")) | |
426 | libc-obj | |
427 | @result{} #<dynamic-object "libc.so"> | |
428 | (dynamic-args-call 'rand libc-obj '()) | |
429 | @result{} 269167349 | |
430 | (dynamic-unlink libc-obj) | |
431 | libc-obj | |
432 | @result{} #<dynamic-object "libc.so" (unlinked)> | |
433 | @end smallexample | |
434 | ||
435 | As you can see, after calling @code{dynamic-unlink} on a dynamically | |
436 | linked library, it is marked as @samp{(unlinked)} and you are no longer | |
437 | able to use it with @code{dynamic-call}, etc. Whether the library is | |
438 | really removed from you program is system-dependent and will generally | |
439 | not happen when some other parts of your program still use it. In the | |
440 | example above, @code{libc} is almost certainly not removed from your | |
441 | program because it is badly needed by almost everything. | |
442 | ||
443 | The functions to call a function from a dynamically linked library, | |
444 | @code{dynamic-call} and @code{dynamic-args-call}, are not very powerful. | |
445 | They are mostly intended to be used for calling specially written | |
446 | initialization functions that will then add new primitives to Guile. | |
447 | For example, we do not expect that you will dynamically link | |
448 | @file{libX11} with @code{dynamic-link} and then construct a beautiful | |
449 | graphical user interface just by using @code{dynamic-call} and | |
450 | @code{dynamic-args-call}. Instead, the usual way would be to write a | |
451 | special Guile<->X11 glue library that has intimate knowledge about both | |
452 | Guile and X11 and does whatever is necessary to make them inter-operate | |
453 | smoothly. This glue library could then be dynamically linked into a | |
454 | vanilla Guile interpreter and activated by calling its initialization | |
455 | function. That function would add all the new types and primitives to | |
456 | the Guile interpreter that it has to offer. | |
457 | ||
458 | From this setup the next logical step is to integrate these glue | |
459 | libraries into the module system of Guile so that you can load new | |
460 | primitives into a running system just as you can load new Scheme code. | |
461 | ||
462 | There is, however, another possibility to get a more thorough access to | |
463 | the functions contained in a dynamically linked library. Anthony Green | |
464 | has written @file{libffi}, a library that implements a @dfn{foreign | |
465 | function interface} for a number of different platforms. With it, you | |
466 | can extend the Spartan functionality of @code{dynamic-call} and | |
467 | @code{dynamic-args-call} considerably. There is glue code available in | |
468 | the Guile contrib archive to make @file{libffi} accessible from Guile. | |
469 | ||
470 | @node Compiled Code Modules | |
471 | @subsection Putting Compiled Code into Modules | |
472 | ||
473 | The new primitives that you add to Guile with @code{gh_new_procedure} or | |
474 | with any of the other mechanisms are normally placed into the same | |
475 | module as all the other builtin procedures (like @code{display}). | |
476 | However, it is also possible to put new primitives into their own | |
477 | module. | |
478 | ||
479 | The mechanism for doing so is not very well thought out and is likely to | |
480 | change when the module system of Guile itself is revised, but it is | |
481 | simple and useful enough to document it as it stands. | |
482 | ||
483 | What @code{gh_new_procedure} and the functions used by the snarfer | |
484 | really do is to add the new primitives to whatever module is the | |
485 | @emph{current module} when they are called. This is analogous to the | |
486 | way Scheme code is put into modules: the @code{define-module} expression | |
487 | at the top of a Scheme source file creates a new module and makes it the | |
488 | current module while the rest of the file is evaluated. The | |
489 | @code{define} expressions in that file then add their new definitions to | |
490 | this current module. | |
491 | ||
492 | Therefore, all we need to do is to make sure that the right module is | |
493 | current when calling @code{gh_new_procedure} for our new primitives. | |
494 | Unfortunately, there is not yet an easy way to access the module system | |
495 | from C, so we are better off with a more indirect approach. Instead of | |
496 | adding our primitives at initialization time we merely register with | |
497 | Guile that we are ready to provide the contents of a certain module, | |
498 | should it ever be needed. | |
499 | ||
500 | @deftypefun void scm_register_module_xxx (char *@var{name}, void (*@var{initfunc})(void)) | |
501 | Register with Guile that @var{initfunc} will provide the contents of the | |
502 | module @var{name}. | |
503 | ||
504 | The function @var{initfunc} should perform the usual initialization | |
505 | actions for your new primitives, like calling @code{gh_new_procedure} or | |
506 | including the file produced by the snarfer. When @var{initfunc} is | |
507 | called, the current module is a newly created module with a name as | |
508 | indicated by @var{name}. Each definition that is added to it will be | |
509 | automatically exported. | |
510 | ||
511 | The string @var{name} indicates the hierachical name of the new module. | |
512 | It should consist of the individual components of the module name | |
513 | separated by single spaces. That is, the Scheme module name @code{(foo | |
514 | bar)}, which is a list, should be written as @code{"foo bar"} for the | |
515 | @var{name} parameter. | |
516 | ||
517 | You can call @code{scm_register_module_xxx} at any time, even before | |
518 | Guile has been initialized. This might be useful when you want to put | |
519 | the call to it in some initialization code that is magically called | |
520 | before main, like constructors for global C++ objects. | |
521 | ||
522 | An example for @code{scm_register_module_xxx} appears in the next section. | |
523 | @end deftypefun | |
524 | ||
525 | Now, instead of calling the initialization function at program startup, | |
526 | you should simply call @code{scm_register_module_xxx} and pass it the | |
527 | initialization function. When the named module is later requested by | |
528 | Scheme code with @code{use-modules} for example, Guile will notice that | |
529 | it knows how to create this module and will call the initialization | |
530 | function at the right time in the right context. | |
531 | ||
532 | @node Dynamic Linking and Compiled Code Modules | |
533 | @subsection Dynamic Linking and Compiled Code Modules | |
534 | ||
535 | The most interesting application of dynamically linked libraries is | |
536 | probably to use them for providing @emph{compiled code modules} to | |
537 | Scheme programs. As much fun as programming in Scheme is, every now and | |
538 | then comes the need to write some low-level C stuff to make Scheme even | |
539 | more fun. | |
540 | ||
541 | Not only can you put these new primitives into their own module (see the | |
542 | previous section), you can even put them into a shared library that is | |
543 | only then linked to your running Guile image when it is actually | |
544 | needed. | |
545 | ||
546 | An example will hopefully make everything clear. Suppose we want to | |
547 | make the Bessel functions of the C library available to Scheme in the | |
548 | module @samp{(math bessel)}. First we need to write the appropriate | |
549 | glue code to convert the arguments and return values of the functions | |
550 | from Scheme to C and back. Additionally, we need a function that will | |
551 | add them to the set of Guile primitives. Because this is just an | |
552 | example, we will only implement this for the @code{j0} function, tho. | |
553 | ||
554 | @smallexample | |
555 | #include <math.h> | |
556 | #include <guile/gh.h> | |
557 | ||
558 | SCM | |
559 | j0_wrapper (SCM x) | |
560 | @{ | |
561 | return gh_double2scm (j0 (gh_scm2double (x))); | |
562 | @} | |
563 | ||
564 | void | |
565 | init_math_bessel () | |
566 | @{ | |
567 | gh_new_procedure1_0 ("j0", j0_wrapper); | |
568 | @} | |
569 | @end smallexample | |
570 | ||
571 | We can already try to bring this into action by manually calling the low | |
572 | level functions for performing dynamic linking. The C source file needs | |
573 | to be compiled into a shared library. Here is how to do it on | |
574 | GNU/Linux, please refer to the @code{libtool} documentation for how to | |
575 | create dynamically linkable libraries portably. | |
576 | ||
577 | @smallexample | |
578 | gcc -shared -o libbessel.so -fPIC bessel.c | |
579 | @end smallexample | |
580 | ||
581 | Now fire up Guile: | |
582 | ||
583 | @smalllisp | |
584 | (define bessel-lib (dynamic-link "./libbessel.so")) | |
585 | (dynamic-call "init_math_bessel" bessel-lib) | |
586 | (j0 2) | |
587 | @result{} 0.223890779141236 | |
588 | @end smalllisp | |
589 | ||
590 | The filename @file{./libbessel.so} should be pointing to the shared | |
591 | library produced with the @code{gcc} command above, of course. The | |
592 | second line of the Guile interaction will call the | |
593 | @code{init_math_bessel} function which in turn will register the C | |
594 | function @code{j0_wrapper} with the Guile interpreter under the name | |
595 | @code{j0}. This function becomes immediately available and we can call | |
596 | it from Scheme. | |
597 | ||
598 | Fun, isn't it? But we are only half way there. This is what | |
599 | @code{apropos} has to say about @code{j0}: | |
600 | ||
601 | @smallexample | |
602 | (apropos 'j0) | |
603 | @print{} the-root-module: j0 #<primitive-procedure j0> | |
604 | @end smallexample | |
605 | ||
606 | As you can see, @code{j0} is contained in the root module, where all | |
607 | the other Guile primitives like @code{display}, etc live. In general, | |
608 | a primitive is put into whatever module is the @dfn{current module} at | |
609 | the time @code{gh_new_procedure} is called. To put @code{j0} into its | |
610 | own module named @samp{(math bessel)}, we need to make a call to | |
611 | @code{scm_register_module_xxx}. Additionally, to have Guile perform | |
612 | the dynamic linking automatically, we need to put @file{libbessel.so} | |
613 | into a place where Guile can find it. The call to | |
614 | @code{scm_register_module_xxx} should be contained in a specially | |
615 | named @dfn{module init function}. Guile knows about this special name | |
616 | and will call that function automatically after having linked in the | |
617 | shared library. For our example, we add the following code to | |
618 | @file{bessel.c}: | |
619 | ||
620 | @smallexample | |
621 | void scm_init_math_bessel_module () | |
622 | @{ | |
623 | scm_register_module_xxx ("math bessel", init_math_bessel); | |
624 | @} | |
625 | @end smallexample | |
626 | ||
627 | The general pattern for the name of a module init function is: | |
628 | @samp{scm_init_}, followed by the name of the module where the | |
629 | individual hierarchical components are concatenated with underscores, | |
630 | followed by @samp{_module}. It should call | |
631 | @code{scm_register_module_xxx} with the correct module name and the | |
632 | appropriate initialization function. When that initialization function | |
633 | will be called, a newly created module with the right name will be the | |
634 | @emph{current module} so that all definitions that the initialization | |
635 | functions makes will end up in the correct module. | |
636 | ||
637 | After @file{libbessel.so} has been rebuild, we need to place the shared | |
638 | library into the right place. When Guile tries to autoload the | |
639 | @samp{(math bessel)} module, it looks not only for a file called | |
640 | @file{math/bessel.scm} in its @code{%load-path}, but also for | |
641 | @file{math/libbessel.so}. So all we need to do is to create a directory | |
642 | called @file{math} somewhere in Guile's @code{%load-path} and place | |
643 | @file{libbessel.so} there. Normally, the current directory @file{.} is | |
644 | in the @code{%load-path}, so we just use that for this example. | |
645 | ||
646 | @smallexample | |
647 | % mkdir maths | |
648 | % cd maths | |
649 | % ln -s ../libbessel.so . | |
650 | % cd .. | |
651 | % guile | |
652 | guile> (use-modules (math bessel)) | |
653 | guile> (j0 2) | |
654 | 0.223890779141236 | |
655 | guile> (apropos 'j0) | |
656 | @print{} bessel: j0 #<primitive-procedure j0> | |
657 | @end smallexample | |
658 | ||
659 | That's it! | |
660 | ||
661 | Note that we used a symlink to make @file{libbessel.so} appear in the | |
662 | right spot. This is probably not a bad idea in general. The | |
663 | directories that the @file{%load-path} normally contains are supposed to | |
664 | contain only architecture independent files. They are not really the | |
665 | right place for a shared library. You might want to install the | |
666 | libraries somewhere below @samp{exec_prefix} and then symlink to them | |
667 | from the architecture independent directory. This will at least work on | |
668 | heterogenous systems where the architecture dependent stuff resides in | |
669 | the same place on all machines (which seems like a good idea to me | |
670 | anyway). | |
671 | ||
672 | ||
673 | @c Local Variables: | |
674 | @c TeX-master: "guile.texi" | |
675 | @c End: |