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 | ||
38a93523 | 185 | @c docstring begin (texi-doc-string "guile" "dynamic-link") |
ae9f3a15 MG |
186 | @deffn primitive dynamic-link filename |
187 | Open the dynamic library called @var{filename}. A library | |
188 | handle representing the opened library is returned; this handle | |
189 | should be used as the @var{dobj} argument to the following | |
190 | functions. | |
38a93523 NJ |
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 | ||
38a93523 NJ |
199 | @c docstring begin (texi-doc-string "guile" "dynamic-unlink") |
200 | @deffn primitive dynamic-unlink dobj | |
38a93523 | 201 | Unlink the indicated object file from the application. The |
ae9f3a15 | 202 | argument @var{dobj} must have been obtained by a call to |
38a93523 | 203 | @code{dynamic-link}. After @code{dynamic-unlink} has been |
ae9f3a15 | 204 | called on @var{dobj}, its content is no longer accessible. |
38a93523 NJ |
205 | @end deffn |
206 | ||
38a93523 NJ |
207 | @c docstring begin (texi-doc-string "guile" "dynamic-func") |
208 | @deffn primitive dynamic-func name dobj | |
209 | Search the dynamic object @var{dobj} for the C function | |
210 | indicated by the string @var{name} and return some Scheme | |
211 | handle that can later be used with @code{dynamic-call} to | |
212 | actually call the function. | |
213 | ||
214 | Regardless whether your C compiler prepends an underscore @samp{_} to | |
215 | the global names in a program, you should @strong{not} include this | |
216 | underscore in @var{function}. Guile knows whether the underscore is | |
217 | needed or not and will add it when necessary. | |
218 | @end deffn | |
219 | ||
38a93523 NJ |
220 | @c docstring begin (texi-doc-string "guile" "dynamic-call") |
221 | @deffn primitive dynamic-call func dobj | |
ae9f3a15 MG |
222 | Call the C function indicated by @var{func} and @var{dobj}. |
223 | The function is passed no arguments and its return value is | |
224 | ignored. When @var{function} is something returned by | |
225 | @code{dynamic-func}, call that function and ignore @var{dobj}. | |
226 | When @var{func} is a string , look it up in @var{dynobj}; this | |
227 | is equivalent to | |
38a93523 | 228 | @smallexample |
ae9f3a15 | 229 | (dynamic-call (dynamic-func @var{func} @var{dobj} #f)) |
38a93523 NJ |
230 | @end smallexample |
231 | ||
232 | Interrupts are deferred while the C function is executing (with | |
233 | @code{SCM_DEFER_INTS}/@code{SCM_ALLOW_INTS}). | |
234 | @end deffn | |
235 | ||
38a93523 NJ |
236 | @c docstring begin (texi-doc-string "guile" "dynamic-args-call") |
237 | @deffn primitive dynamic-args-call func dobj args | |
ae9f3a15 MG |
238 | Call the C function indicated by @var{func} and @var{dobj}, |
239 | just like @code{dynamic-call}, but pass it some arguments and | |
240 | return its return value. The C function is expected to take | |
241 | two arguments and return an @code{int}, just like @code{main}: | |
38a93523 NJ |
242 | @smallexample |
243 | int c_func (int argc, char **argv); | |
244 | @end smallexample | |
245 | ||
ae9f3a15 MG |
246 | The parameter @var{args} must be a list of strings and is |
247 | converted into an array of @code{char *}. The array is passed | |
248 | in @var{argv} and its size in @var{argc}. The return value is | |
249 | converted to a Scheme number and returned from the call to | |
250 | @code{dynamic-args-call}. | |
38a93523 NJ |
251 | @end deffn |
252 | ||
253 | @c docstring begin (texi-doc-string "guile" "c-registered-modules") | |
254 | @deffn primitive c-registered-modules | |
255 | Return a list of the object code modules that have been imported into | |
256 | the current Guile process. Each element of the list is a pair whose | |
257 | car is the name of the module, and whose cdr is the function handle | |
258 | for that module's initializer function. The name is the string that | |
259 | has been passed to scm_register_module_xxx. | |
260 | @end deffn | |
261 | ||
262 | @c docstring begin (texi-doc-string "guile" "c-clear-registered-modules") | |
263 | @deffn primitive c-clear-registered-modules | |
264 | Destroy the list of modules registered with the current Guile process. | |
265 | The return value is unspecified. @strong{Warning:} this function does | |
266 | not actually unlink or deallocate these modules, but only destroys the | |
267 | records of which modules have been loaded. It should therefore be used | |
268 | only by module bookkeeping operations. | |
269 | @end deffn | |
270 | ||
271 | [FIXME: provide a brief example here of writing the C hooks for an | |
272 | object code module, and using dynamic-link and dynamic-call to load the | |
273 | module.] | |
274 | ||
275 | ||
276 | @node Dynamic Linking from Marius | |
277 | @section Dynamic Linking from Marius | |
278 | ||
279 | @c NJFIXME primitive documentation here duplicates (and is generally | |
280 | @c better than) documentation for the same primitives earlier on. | |
281 | ||
282 | Most modern Unices have something called @dfn{shared libraries}. This | |
283 | ordinarily means that they have the capability to share the executable | |
284 | image of a library between several running programs to save memory and | |
285 | disk space. But generally, shared libraries give a lot of additional | |
286 | flexibility compared to the traditional static libraries. In fact, | |
287 | calling them `dynamic' libraries is as correct as calling them `shared'. | |
288 | ||
289 | Shared libraries really give you a lot of flexibility in addition to the | |
290 | memory and disk space savings. When you link a program against a shared | |
291 | library, that library is not closely incorporated into the final | |
292 | executable. Instead, the executable of your program only contains | |
293 | enough information to find the needed shared libraries when the program | |
294 | is actually run. Only then, when the program is starting, is the final | |
295 | step of the linking process performed. This means that you need not | |
296 | recompile all programs when you install a new, only slightly modified | |
297 | version of a shared library. The programs will pick up the changes | |
298 | automatically the next time they are run. | |
299 | ||
300 | Now, when all the necessary machinery is there to perform part of the | |
301 | linking at run-time, why not take the next step and allow the programmer | |
302 | to explicitly take advantage of it from within his program? Of course, | |
303 | many operating systems that support shared libraries do just that, and | |
304 | chances are that Guile will allow you to access this feature from within | |
305 | your Scheme programs. As you might have guessed already, this feature | |
306 | is called @dfn{dynamic linking}@footnote{Some people also refer to the | |
307 | final linking stage at program startup as `dynamic linking', so if you | |
308 | want to make yourself perfectly clear, it is probably best to use the | |
309 | more technical term @dfn{dlopening}, as suggested by Gordon Matzigkeit | |
310 | in his libtool documentation.} | |
311 | ||
312 | As with many aspects of Guile, there is a low-level way to access the | |
313 | dynamic linking apparatus, and a more high-level interface that | |
314 | integrates dynamically linked libraries into the module system. | |
315 | ||
316 | @menu | |
317 | * Low level dynamic linking:: | |
318 | * Compiled Code Modules:: | |
319 | * Dynamic Linking and Compiled Code Modules:: | |
320 | @end menu | |
321 | ||
322 | @node Low level dynamic linking | |
323 | @subsection Low level dynamic linking | |
324 | ||
325 | When using the low level procedures to do your dynamic linking, you have | |
326 | complete control over which library is loaded when and what get's done | |
327 | with it. | |
328 | ||
329 | @deffn primitive dynamic-link library | |
330 | Find the shared library denoted by @var{library} (a string) and link it | |
331 | into the running Guile application. When everything works out, return a | |
332 | Scheme object suitable for representing the linked object file. | |
333 | Otherwise an error is thrown. How object files are searched is system | |
334 | dependent. | |
335 | ||
336 | Normally, @var{library} is just the name of some shared library file | |
337 | that will be searched for in the places where shared libraries usually | |
338 | reside, such as in @file{/usr/lib} and @file{/usr/local/lib}. | |
339 | @end deffn | |
340 | ||
341 | @deffn primitive dynamic-object? val | |
342 | Determine whether @var{val} represents a dynamically linked object file. | |
343 | @end deffn | |
344 | ||
345 | @deffn primitive dynamic-unlink dynobj | |
346 | Unlink the indicated object file from the application. The argument | |
347 | @var{dynobj} should be one of the values returned by | |
348 | @code{dynamic-link}. When @code{dynamic-unlink} has been called on | |
349 | @var{dynobj}, it is no longer usable as an argument to the functions | |
350 | below and you will get type mismatch errors when you try to. | |
351 | @end deffn | |
352 | ||
353 | @deffn primitive dynamic-func function dynobj | |
354 | Search the C function indicated by @var{function} (a string or symbol) | |
355 | in @var{dynobj} and return some Scheme object that can later be used | |
356 | with @code{dynamic-call} to actually call this function. Right now, | |
357 | these Scheme objects are formed by casting the address of the function | |
358 | to @code{long} and converting this number to its Scheme representation. | |
359 | ||
360 | Regardless whether your C compiler prepends an underscore @samp{_} to | |
361 | the global names in a program, you should @strong{not} include this | |
362 | underscore in @var{function}. Guile knows whether the underscore is | |
363 | needed or not and will add it when necessary. | |
364 | @end deffn | |
365 | ||
366 | @deffn primitive dynamic-call function dynobj | |
367 | Call the C function indicated by @var{function} and @var{dynobj}. The | |
368 | function is passed no arguments and its return value is ignored. When | |
369 | @var{function} is something returned by @code{dynamic-func}, call that | |
370 | function and ignore @var{dynobj}. When @var{function} is a string (or | |
371 | symbol, etc.), look it up in @var{dynobj}; this is equivalent to | |
372 | ||
373 | @smallexample | |
374 | (dynamic-call (dynamic-func @var{function} @var{dynobj} #f)) | |
375 | @end smallexample | |
376 | ||
377 | Interrupts are deferred while the C function is executing (with | |
378 | @code{SCM_DEFER_INTS}/@code{SCM_ALLOW_INTS}). | |
379 | @end deffn | |
380 | ||
381 | @deffn primitive dynamic-args-call function dynobj args | |
382 | Call the C function indicated by @var{function} and @var{dynobj}, just | |
383 | like @code{dynamic-call}, but pass it some arguments and return its | |
384 | return value. The C function is expected to take two arguments and | |
385 | return an @code{int}, just like @code{main}: | |
386 | ||
387 | @smallexample | |
388 | int c_func (int argc, char **argv); | |
389 | @end smallexample | |
390 | ||
391 | The parameter @var{args} must be a list of strings and is converted into | |
392 | an array of @code{char *}. The array is passed in @var{argv} and its | |
393 | size in @var{argc}. The return value is converted to a Scheme number | |
394 | and returned from the call to @code{dynamic-args-call}. | |
395 | @end deffn | |
396 | ||
397 | When dynamic linking is disabled or not supported on your system, | |
398 | the above functions throw errors, but they are still available. | |
399 | ||
400 | Here is a small example that works on GNU/Linux: | |
401 | ||
402 | @smallexample | |
403 | (define libc-obj (dynamic-link "libc.so")) | |
404 | libc-obj | |
405 | @result{} #<dynamic-object "libc.so"> | |
406 | (dynamic-args-call 'rand libc-obj '()) | |
407 | @result{} 269167349 | |
408 | (dynamic-unlink libc-obj) | |
409 | libc-obj | |
410 | @result{} #<dynamic-object "libc.so" (unlinked)> | |
411 | @end smallexample | |
412 | ||
413 | As you can see, after calling @code{dynamic-unlink} on a dynamically | |
414 | linked library, it is marked as @samp{(unlinked)} and you are no longer | |
415 | able to use it with @code{dynamic-call}, etc. Whether the library is | |
416 | really removed from you program is system-dependent and will generally | |
417 | not happen when some other parts of your program still use it. In the | |
418 | example above, @code{libc} is almost certainly not removed from your | |
419 | program because it is badly needed by almost everything. | |
420 | ||
421 | The functions to call a function from a dynamically linked library, | |
422 | @code{dynamic-call} and @code{dynamic-args-call}, are not very powerful. | |
423 | They are mostly intended to be used for calling specially written | |
424 | initialization functions that will then add new primitives to Guile. | |
425 | For example, we do not expect that you will dynamically link | |
426 | @file{libX11} with @code{dynamic-link} and then construct a beautiful | |
427 | graphical user interface just by using @code{dynamic-call} and | |
428 | @code{dynamic-args-call}. Instead, the usual way would be to write a | |
429 | special Guile<->X11 glue library that has intimate knowledge about both | |
430 | Guile and X11 and does whatever is necessary to make them inter-operate | |
431 | smoothly. This glue library could then be dynamically linked into a | |
432 | vanilla Guile interpreter and activated by calling its initialization | |
433 | function. That function would add all the new types and primitives to | |
434 | the Guile interpreter that it has to offer. | |
435 | ||
436 | From this setup the next logical step is to integrate these glue | |
437 | libraries into the module system of Guile so that you can load new | |
438 | primitives into a running system just as you can load new Scheme code. | |
439 | ||
440 | There is, however, another possibility to get a more thorough access to | |
441 | the functions contained in a dynamically linked library. Anthony Green | |
442 | has written @file{libffi}, a library that implements a @dfn{foreign | |
443 | function interface} for a number of different platforms. With it, you | |
444 | can extend the Spartan functionality of @code{dynamic-call} and | |
445 | @code{dynamic-args-call} considerably. There is glue code available in | |
446 | the Guile contrib archive to make @file{libffi} accessible from Guile. | |
447 | ||
448 | @node Compiled Code Modules | |
449 | @subsection Putting Compiled Code into Modules | |
450 | ||
451 | The new primitives that you add to Guile with @code{gh_new_procedure} or | |
452 | with any of the other mechanisms are normally placed into the same | |
453 | module as all the other builtin procedures (like @code{display}). | |
454 | However, it is also possible to put new primitives into their own | |
455 | module. | |
456 | ||
457 | The mechanism for doing so is not very well thought out and is likely to | |
458 | change when the module system of Guile itself is revised, but it is | |
459 | simple and useful enough to document it as it stands. | |
460 | ||
461 | What @code{gh_new_procedure} and the functions used by the snarfer | |
462 | really do is to add the new primitives to whatever module is the | |
463 | @emph{current module} when they are called. This is analogous to the | |
464 | way Scheme code is put into modules: the @code{define-module} expression | |
465 | at the top of a Scheme source file creates a new module and makes it the | |
466 | current module while the rest of the file is evaluated. The | |
467 | @code{define} expressions in that file then add their new definitions to | |
468 | this current module. | |
469 | ||
470 | Therefore, all we need to do is to make sure that the right module is | |
471 | current when calling @code{gh_new_procedure} for our new primitives. | |
472 | Unfortunately, there is not yet an easy way to access the module system | |
473 | from C, so we are better off with a more indirect approach. Instead of | |
474 | adding our primitives at initialization time we merely register with | |
475 | Guile that we are ready to provide the contents of a certain module, | |
476 | should it ever be needed. | |
477 | ||
478 | @deftypefun void scm_register_module_xxx (char *@var{name}, void (*@var{initfunc})(void)) | |
479 | Register with Guile that @var{initfunc} will provide the contents of the | |
480 | module @var{name}. | |
481 | ||
482 | The function @var{initfunc} should perform the usual initialization | |
483 | actions for your new primitives, like calling @code{gh_new_procedure} or | |
484 | including the file produced by the snarfer. When @var{initfunc} is | |
485 | called, the current module is a newly created module with a name as | |
486 | indicated by @var{name}. Each definition that is added to it will be | |
487 | automatically exported. | |
488 | ||
489 | The string @var{name} indicates the hierachical name of the new module. | |
490 | It should consist of the individual components of the module name | |
491 | separated by single spaces. That is, the Scheme module name @code{(foo | |
492 | bar)}, which is a list, should be written as @code{"foo bar"} for the | |
493 | @var{name} parameter. | |
494 | ||
495 | You can call @code{scm_register_module_xxx} at any time, even before | |
496 | Guile has been initialized. This might be useful when you want to put | |
497 | the call to it in some initialization code that is magically called | |
498 | before main, like constructors for global C++ objects. | |
499 | ||
500 | An example for @code{scm_register_module_xxx} appears in the next section. | |
501 | @end deftypefun | |
502 | ||
503 | Now, instead of calling the initialization function at program startup, | |
504 | you should simply call @code{scm_register_module_xxx} and pass it the | |
505 | initialization function. When the named module is later requested by | |
506 | Scheme code with @code{use-modules} for example, Guile will notice that | |
507 | it knows how to create this module and will call the initialization | |
508 | function at the right time in the right context. | |
509 | ||
510 | @node Dynamic Linking and Compiled Code Modules | |
511 | @subsection Dynamic Linking and Compiled Code Modules | |
512 | ||
513 | The most interesting application of dynamically linked libraries is | |
514 | probably to use them for providing @emph{compiled code modules} to | |
515 | Scheme programs. As much fun as programming in Scheme is, every now and | |
516 | then comes the need to write some low-level C stuff to make Scheme even | |
517 | more fun. | |
518 | ||
519 | Not only can you put these new primitives into their own module (see the | |
520 | previous section), you can even put them into a shared library that is | |
521 | only then linked to your running Guile image when it is actually | |
522 | needed. | |
523 | ||
524 | An example will hopefully make everything clear. Suppose we want to | |
525 | make the Bessel functions of the C library available to Scheme in the | |
526 | module @samp{(math bessel)}. First we need to write the appropriate | |
527 | glue code to convert the arguments and return values of the functions | |
528 | from Scheme to C and back. Additionally, we need a function that will | |
529 | add them to the set of Guile primitives. Because this is just an | |
530 | example, we will only implement this for the @code{j0} function, tho. | |
531 | ||
532 | @smallexample | |
533 | #include <math.h> | |
534 | #include <guile/gh.h> | |
535 | ||
536 | SCM | |
537 | j0_wrapper (SCM x) | |
538 | @{ | |
539 | return gh_double2scm (j0 (gh_scm2double (x))); | |
540 | @} | |
541 | ||
542 | void | |
543 | init_math_bessel () | |
544 | @{ | |
545 | gh_new_procedure1_0 ("j0", j0_wrapper); | |
546 | @} | |
547 | @end smallexample | |
548 | ||
549 | We can already try to bring this into action by manually calling the low | |
550 | level functions for performing dynamic linking. The C source file needs | |
551 | to be compiled into a shared library. Here is how to do it on | |
552 | GNU/Linux, please refer to the @code{libtool} documentation for how to | |
553 | create dynamically linkable libraries portably. | |
554 | ||
555 | @smallexample | |
556 | gcc -shared -o libbessel.so -fPIC bessel.c | |
557 | @end smallexample | |
558 | ||
559 | Now fire up Guile: | |
560 | ||
561 | @smalllisp | |
562 | (define bessel-lib (dynamic-link "./libbessel.so")) | |
563 | (dynamic-call "init_math_bessel" bessel-lib) | |
564 | (j0 2) | |
565 | @result{} 0.223890779141236 | |
566 | @end smalllisp | |
567 | ||
568 | The filename @file{./libbessel.so} should be pointing to the shared | |
569 | library produced with the @code{gcc} command above, of course. The | |
570 | second line of the Guile interaction will call the | |
571 | @code{init_math_bessel} function which in turn will register the C | |
572 | function @code{j0_wrapper} with the Guile interpreter under the name | |
573 | @code{j0}. This function becomes immediately available and we can call | |
574 | it from Scheme. | |
575 | ||
576 | Fun, isn't it? But we are only half way there. This is what | |
577 | @code{apropos} has to say about @code{j0}: | |
578 | ||
579 | @smallexample | |
580 | (apropos 'j0) | |
581 | @print{} the-root-module: j0 #<primitive-procedure j0> | |
582 | @end smallexample | |
583 | ||
584 | As you can see, @code{j0} is contained in the root module, where all | |
585 | the other Guile primitives like @code{display}, etc live. In general, | |
586 | a primitive is put into whatever module is the @dfn{current module} at | |
587 | the time @code{gh_new_procedure} is called. To put @code{j0} into its | |
588 | own module named @samp{(math bessel)}, we need to make a call to | |
589 | @code{scm_register_module_xxx}. Additionally, to have Guile perform | |
590 | the dynamic linking automatically, we need to put @file{libbessel.so} | |
591 | into a place where Guile can find it. The call to | |
592 | @code{scm_register_module_xxx} should be contained in a specially | |
593 | named @dfn{module init function}. Guile knows about this special name | |
594 | and will call that function automatically after having linked in the | |
595 | shared library. For our example, we add the following code to | |
596 | @file{bessel.c}: | |
597 | ||
598 | @smallexample | |
599 | void scm_init_math_bessel_module () | |
600 | @{ | |
601 | scm_register_module_xxx ("math bessel", init_math_bessel); | |
602 | @} | |
603 | @end smallexample | |
604 | ||
605 | The general pattern for the name of a module init function is: | |
606 | @samp{scm_init_}, followed by the name of the module where the | |
607 | individual hierarchical components are concatenated with underscores, | |
608 | followed by @samp{_module}. It should call | |
609 | @code{scm_register_module_xxx} with the correct module name and the | |
610 | appropriate initialization function. When that initialization function | |
611 | will be called, a newly created module with the right name will be the | |
612 | @emph{current module} so that all definitions that the initialization | |
613 | functions makes will end up in the correct module. | |
614 | ||
615 | After @file{libbessel.so} has been rebuild, we need to place the shared | |
616 | library into the right place. When Guile tries to autoload the | |
617 | @samp{(math bessel)} module, it looks not only for a file called | |
618 | @file{math/bessel.scm} in its @code{%load-path}, but also for | |
619 | @file{math/libbessel.so}. So all we need to do is to create a directory | |
620 | called @file{math} somewhere in Guile's @code{%load-path} and place | |
621 | @file{libbessel.so} there. Normally, the current directory @file{.} is | |
622 | in the @code{%load-path}, so we just use that for this example. | |
623 | ||
624 | @smallexample | |
625 | % mkdir maths | |
626 | % cd maths | |
627 | % ln -s ../libbessel.so . | |
628 | % cd .. | |
629 | % guile | |
630 | guile> (use-modules (math bessel)) | |
631 | guile> (j0 2) | |
632 | 0.223890779141236 | |
633 | guile> (apropos 'j0) | |
634 | @print{} bessel: j0 #<primitive-procedure j0> | |
635 | @end smallexample | |
636 | ||
637 | That's it! | |
638 | ||
639 | Note that we used a symlink to make @file{libbessel.so} appear in the | |
640 | right spot. This is probably not a bad idea in general. The | |
641 | directories that the @file{%load-path} normally contains are supposed to | |
642 | contain only architecture independent files. They are not really the | |
643 | right place for a shared library. You might want to install the | |
644 | libraries somewhere below @samp{exec_prefix} and then symlink to them | |
645 | from the architecture independent directory. This will at least work on | |
646 | heterogenous systems where the architecture dependent stuff resides in | |
647 | the same place on all machines (which seems like a good idea to me | |
648 | anyway). | |
649 | ||
650 | ||
651 | @c Local Variables: | |
652 | @c TeX-master: "guile.texi" | |
653 | @c End: |