Commit | Line | Data |
---|---|---|
a0e07ba4 NJ |
1 | @page |
2 | @node Modules | |
3 | @chapter Modules | |
4 | @cindex modules | |
5 | ||
6 | When programs become large, naming conflicts can occur when a function | |
7 | or global variable defined in one file has the same name as a function | |
8 | or global variable in another file. Even just a @emph{similarity} | |
9 | between function names can cause hard-to-find bugs, since a programmer | |
10 | might type the wrong function name. | |
11 | ||
12 | The approach used to tackle this problem is called @emph{information | |
13 | encapsulation}, which consists of packaging functional units into a | |
14 | given name space that is clearly separated from other name spaces. | |
15 | @cindex encapsulation | |
16 | @cindex information encapsulation | |
17 | @cindex name space | |
18 | ||
19 | The language features that allow this are usually called @emph{the | |
20 | module system} because programs are broken up into modules that are | |
21 | compiled separately (or loaded separately in an interpreter). | |
22 | ||
23 | Older languages, like C, have limited support for name space | |
24 | manipulation and protection. In C a variable or function is public by | |
25 | default, and can be made local to a module with the @code{static} | |
26 | keyword. But you cannot reference public variables and functions from | |
27 | another module with different names. | |
28 | ||
29 | More advanced module systems have become a common feature in recently | |
30 | designed languages: ML, Python, Perl, and Modula 3 all allow the | |
31 | @emph{renaming} of objects from a foreign module, so they will not | |
32 | clutter the global name space. | |
33 | @cindex name space - private | |
34 | ||
2a946b44 NJ |
35 | In addition, Guile offers variables as first-class objects. They can |
36 | be used for interacting with the module system. | |
37 | ||
a0e07ba4 NJ |
38 | @menu |
39 | * Scheme and modules:: How modules are handled in standard Scheme. | |
40 | * The Guile module system:: How Guile does it. | |
41 | * Dynamic Libraries:: Loading libraries of compiled code at run time. | |
2a946b44 | 42 | * Variables:: First-class variables. |
a0e07ba4 NJ |
43 | @end menu |
44 | ||
45 | ||
46 | @node Scheme and modules | |
47 | @section Scheme and modules | |
48 | ||
49 | Scheme, as defined in R5RS, 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 | ||
59 | @smalllisp | |
60 | (provide 'random) | |
61 | @end smalllisp | |
62 | ||
63 | so to use its procedures, a user would type | |
64 | ||
65 | @smalllisp | |
66 | (require 'random) | |
67 | @end smalllisp | |
68 | ||
69 | and they would magically become available, @emph{but still have the same | |
70 | names!} So this method is nice, but not as good as a full-featured | |
71 | module system. | |
72 | ||
73 | ||
74 | @node The Guile module system | |
75 | @section The Guile module system | |
76 | ||
77 | In 1996 Tom Lord implemented a full-featured module system for Guile which | |
78 | allows loading Scheme source files into a private name space. This system has | |
79 | been in available since Guile version 1.4. | |
80 | @c fixme: Actually, was it available before? 1.4 seems a bit late... | |
81 | ||
82 | For Guile version 1.5.0 and later, the system has been improved to have better | |
83 | integration from C code, more fine-grained user control over interfaces, and | |
84 | documentation. | |
85 | ||
86 | Although it is anticipated that the module system implementation will | |
87 | change in the future, the Scheme programming interface described in this | |
88 | manual should be considered stable. The C programming interface is | |
89 | considered relatively stable, although at the time of this writing, | |
90 | there is still some flux. | |
91 | @c fixme: Review: Need better C code interface commentary. | |
92 | ||
93 | @menu | |
94 | * General Information about Modules:: Guile module basics. | |
95 | * Using Guile Modules:: How to use existing modules. | |
96 | * Creating Guile Modules:: How to package your code into modules. | |
97 | * More Module Procedures:: Low-level module code. | |
98 | * Module System Quirks:: Strange things to be aware of. | |
99 | * Included Guile Modules:: Which modules come with Guile? | |
100 | @end menu | |
101 | ||
102 | @node General Information about Modules | |
103 | @subsection General Information about Modules | |
104 | ||
105 | A Guile module is a collection of named procedures, variables and | |
106 | macros, altogether called the @dfn{bindings}, since they bind, or | |
107 | associate, a symbol (the name) to a Scheme object (procedure, variable, | |
108 | or macro). Within a module, all bindings are visible. Certain bindings | |
109 | can be declared @dfn{public}, in which case they are added to the | |
110 | module's so-called @dfn{export list}; this set of public bindings is | |
111 | called the module's @dfn{public interface} (@pxref{Creating Guile | |
112 | Modules}). | |
113 | ||
114 | A client module @dfn{uses} a providing module's bindings by either | |
115 | accessing the providing module's public interface, or by building a | |
116 | custom interface (and then accessing that). In a custom interface, the | |
117 | client module can @dfn{select} which bindings to access and can also | |
118 | algorithmically @dfn{rename} bindings. In contrast, when using the | |
119 | providing module's public interface, the entire export list is available | |
120 | without renaming (@pxref{Using Guile Modules}). | |
121 | ||
122 | To use a module, it must be found and loaded. All Guile modules have a | |
123 | unique @dfn{module name}, which is a list of one or more symbols. | |
124 | Examples are @code{(ice-9 popen)} or @code{(srfi srfi-11)}. When Guile | |
125 | searches for the code of a module, it constructs the name of the file to | |
126 | load by concatenating the name elements with slashes between the | |
127 | elements and appending a number of file name extensions from the list | |
128 | @code{%load-extensions} (REFFIXME). The resulting file name is then | |
129 | searched in all directories in the variable @code{%load-path}. For | |
130 | example, the @code{(ice-9 popen)} module would result in the filename | |
131 | @code{ice-9/popen.scm} and searched in the installation directory of | |
132 | Guile and in all other directories in the load path. | |
133 | ||
134 | @c FIXME::martin: Not sure about this, maybe someone knows better? | |
135 | Every module has a so-called syntax transformer associated with it. | |
136 | This is a procedure which performs all syntax transformation for the | |
137 | time the module is read in and evaluated. When working with modules, | |
138 | you can manipulate the current syntax transformer using the | |
139 | @code{use-syntax} syntactic form or the @code{#:use-syntax} module | |
140 | definition option (@pxref{Creating Guile Modules}). | |
141 | ||
142 | Please note that there are some problems with the current module system | |
143 | you should keep in mind (@pxref{Module System Quirks}). We hope to | |
144 | address these eventually. | |
145 | ||
146 | ||
147 | @node Using Guile Modules | |
148 | @subsection Using Guile Modules | |
149 | ||
150 | To use a Guile module is to access either its public interface or a | |
151 | custom interface (@pxref{General Information about Modules}). Both | |
152 | types of access are handled by the syntactic form @code{use-modules}, | |
153 | which accepts one or more interface specifications and, upon evaluation, | |
154 | arranges for those interfaces to be available to the current module. | |
155 | This process may include locating and loading code for a given module if | |
156 | that code has not yet been loaded (REFFIXME %load-path). | |
157 | ||
158 | An @dfn{interface specification} has one of two forms. The first | |
159 | variation is simply to name the module, in which case its public | |
160 | interface is the one accessed. For example: | |
161 | ||
162 | @smalllisp | |
163 | (use-modules (ice-9 popen)) | |
164 | @end smalllisp | |
165 | ||
166 | Here, the interface specification is @code{(ice-9 popen)}, and the | |
167 | result is that the current module now has access to @code{open-pipe}, | |
168 | @code{close-pipe}, @code{open-input-pipe}, and so on (@pxref{Included | |
169 | Guile Modules}). | |
170 | ||
171 | Note in the previous example that if the current module had already | |
172 | defined @code{open-pipe}, that definition would be overwritten by the | |
173 | definition in @code{(ice-9 popen)}. For this reason (and others), there | |
174 | is a second variation of interface specification that not only names a | |
175 | module to be accessed, but also selects bindings from it and renames | |
176 | them to suit the current module's needs. For example: | |
177 | ||
178 | @smalllisp | |
179 | (use-modules ((ice-9 popen) | |
180 | :select ((open-pipe . pipe-open) close-pipe) | |
181 | :rename (symbol-prefix-proc 'unixy:))) | |
182 | @end smalllisp | |
183 | ||
184 | Here, the interface specification is more complex than before, and the | |
185 | result is that a custom interface with only two bindings is created and | |
186 | subsequently accessed by the current module. The mapping of old to new | |
187 | names is as follows: | |
188 | ||
189 | @c Use `smallexample' since `table' is ugly. --ttn | |
190 | @smallexample | |
191 | (ice-9 popen) sees: current module sees: | |
192 | open-pipe unixy:pipe-open | |
193 | close-pipe unixy:close-pipe | |
194 | @end smallexample | |
195 | ||
196 | This example also shows how to use the convenience procedure | |
197 | @code{symbol-prefix-proc}. | |
198 | ||
199 | @c begin (scm-doc-string "boot-9.scm" "symbol-prefix-proc") | |
8f85c0c6 | 200 | @deffn {Scheme Procedure} symbol-prefix-proc prefix-sym |
a0e07ba4 NJ |
201 | Return a procedure that prefixes its arg (a symbol) with |
202 | @var{prefix-sym}. | |
203 | @c Insert gratuitous C++ slam here. --ttn | |
204 | @end deffn | |
205 | ||
206 | @c begin (scm-doc-string "boot-9.scm" "use-modules") | |
207 | @deffn syntax use-modules spec @dots{} | |
208 | Resolve each interface specification @var{spec} into an interface and | |
209 | arrange for these to be accessible by the current module. The return | |
210 | value is unspecified. | |
211 | ||
212 | @var{spec} can be a list of symbols, in which case it names a module | |
213 | whose public interface is found and used. | |
214 | ||
215 | @var{spec} can also be of the form: | |
216 | ||
217 | @smalllisp | |
218 | (MODULE-NAME [:select SELECTION] [:rename RENAMER]) | |
219 | @end smalllisp | |
220 | ||
221 | in which case a custom interface is newly created and used. | |
222 | @var{module-name} is a list of symbols, as above; @var{selection} is a | |
223 | list of selection-specs; and @var{renamer} is a procedure that takes a | |
224 | symbol and returns its new name. A selection-spec is either a symbol or | |
225 | a pair of symbols @code{(ORIG . SEEN)}, where @var{orig} is the name in | |
226 | the used module and @var{seen} is the name in the using module. Note | |
227 | that @var{seen} is also passed through @var{renamer}. | |
228 | ||
229 | The @code{:select} and @code{:rename} clauses are optional. If both are | |
230 | omitted, the returned interface has no bindings. If the @code{:select} | |
231 | clause is omitted, @var{renamer} operates on the used module's public | |
232 | interface. | |
233 | ||
234 | Signal error if module name is not resolvable. | |
235 | @end deffn | |
236 | ||
237 | ||
238 | @c FIXME::martin: Is this correct, and is there more to say? | |
239 | @c FIXME::martin: Define term and concept `system transformer' somewhere. | |
240 | ||
241 | @deffn syntax use-syntax module-name | |
242 | Load the module @code{module-name} and use its system | |
243 | transformer as the system transformer for the currently defined module, | |
244 | as well as installing it as the current system transformer. | |
245 | @end deffn | |
246 | ||
247 | ||
248 | @node Creating Guile Modules | |
249 | @subsection Creating Guile Modules | |
250 | ||
251 | When you want to create your own modules, you have to take the following | |
252 | steps: | |
253 | ||
254 | @itemize @bullet | |
255 | @item | |
256 | Create a Scheme source file and add all variables and procedures you wish | |
257 | to export, or which are required by the exported procedures. | |
258 | ||
259 | @item | |
260 | Add a @code{define-module} form at the beginning. | |
261 | ||
262 | @item | |
263 | Export all bindings which should be in the public interface, either | |
264 | by using @code{define-public} or @code{export} (both documented below). | |
265 | @end itemize | |
266 | ||
267 | @c begin (scm-doc-string "boot-9.scm" "define-module") | |
268 | @deffn syntax define-module module-name [options @dots{}] | |
269 | @var{module-name} is of the form @code{(hierarchy file)}. One | |
270 | example of this is | |
271 | ||
272 | @smalllisp | |
273 | (define-module (ice-9 popen)) | |
274 | @end smalllisp | |
275 | ||
276 | @code{define-module} makes this module available to Guile programs under | |
277 | the given @var{module-name}. | |
278 | ||
279 | The @var{options} are keyword/value pairs which specify more about the | |
280 | defined module. The recognized options and their meaning is shown in | |
281 | the following table. | |
282 | ||
283 | @c fixme: Should we use "#:" or ":"? | |
284 | ||
285 | @table @code | |
286 | @item #:use-module @var{interface-specification} | |
287 | Equivalent to a @code{(use-modules @var{interface-specification})} | |
288 | (@pxref{Using Guile Modules}). | |
289 | ||
290 | @item #:use-syntax @var{module} | |
291 | Use @var{module} when loading the currently defined module, and install | |
292 | it as the syntax transformer. | |
293 | ||
294 | @item #:autoload @var{module} @var{symbol} | |
295 | Load @var{module} whenever @var{symbol} is accessed. | |
296 | ||
297 | @item #:export @var{list} | |
298 | Export all identifiers in @var{list}, which must be a list of symbols. | |
299 | This is equivalent to @code{(export @var{list})} in the module body. | |
300 | ||
301 | @item #:no-backtrace | |
302 | Tell Guile not to record information for procedure backtraces when | |
303 | executing the procedures in this module. | |
304 | ||
305 | @item #:pure | |
306 | Create a @dfn{pure} module, that is a module which does not contain any | |
307 | of the standard procedure bindings except for the syntax forms. This is | |
308 | useful if you want to create @dfn{safe} modules, that is modules which | |
309 | do not know anything about dangerous procedures. | |
310 | @end table | |
311 | ||
312 | @end deffn | |
313 | @c end | |
314 | ||
315 | @deffn syntax export variable @dots{} | |
316 | Add all @var{variable}s (which must be symbols) to the list of exported | |
317 | bindings of the current module. | |
318 | @end deffn | |
319 | ||
320 | @c begin (scm-doc-string "boot-9.scm" "define-public") | |
321 | @deffn syntax define-public @dots{} | |
322 | Equivalent to @code{(begin (define foo ...) (export foo))}. | |
323 | @end deffn | |
324 | @c end | |
325 | ||
326 | ||
327 | @node More Module Procedures | |
328 | @subsection More Module Procedures | |
329 | ||
330 | @c FIXME::martin: Review me! | |
331 | ||
332 | @c FIXME::martin: Should this procedure be documented and supported | |
333 | @c at all? | |
334 | ||
335 | The procedures in this section are useful if you want to dig into the | |
336 | innards of Guile's module system. If you don't know precisely what you | |
337 | do, you should probably avoid using any of them. | |
338 | ||
8f85c0c6 NJ |
339 | @deffn {Scheme Procedure} standard-eval-closure module |
340 | @deffnx {C Function} scm_standard_eval_closure (module) | |
a0e07ba4 NJ |
341 | Return an eval closure for the module @var{module}. |
342 | @end deffn | |
343 | ||
344 | ||
345 | @node Module System Quirks | |
346 | @subsection Module System Quirks | |
347 | ||
348 | Although the programming interfaces are relatively stable, the Guile | |
349 | module system itself is still evolving. Here are some situations where | |
350 | usage surpasses design. | |
351 | ||
352 | @itemize @bullet | |
353 | ||
354 | @item | |
355 | When using a module which exports a macro definition, the other module | |
356 | must export all bindings the macro expansion uses, too, because the | |
357 | expanded code would otherwise not be able to see these definitions and | |
358 | issue a ``variable unbound'' error, or worse, would use another binding | |
359 | which might be present in the scope of the expansion. | |
360 | ||
361 | @item | |
362 | When two or more used modules export bindings with the same names, the | |
363 | last accessed module wins, and the exported binding of that last module | |
364 | will silently be used. This might lead to hard-to-find errors because | |
365 | wrong procedures or variables are used. To avoid this kind of | |
366 | @dfn{name-clash} situation, use a custom interface specification | |
367 | (@pxref{Using Guile Modules}). (We include this entry for the possible | |
368 | benefit of users of Guile versions previous to 1.5.0, when custom | |
369 | interfaces were added to the module system.) | |
370 | ||
371 | @item | |
372 | [Add other quirks here.] | |
373 | ||
374 | @end itemize | |
375 | ||
376 | ||
377 | @node Included Guile Modules | |
378 | @subsection Included Guile Modules | |
379 | ||
380 | @c FIXME::martin: Review me! | |
381 | ||
382 | Some modules are included in the Guile distribution; here are references | |
383 | to the entries in this manual which describe them in more detail: | |
384 | ||
385 | @table @strong | |
386 | @item boot-9 | |
387 | boot-9 is Guile's initialization module, and it is always loaded when | |
388 | Guile starts up. | |
389 | ||
390 | @item (ice-9 debug) | |
391 | Mikael Djurfeldt's source-level debugging support for Guile | |
392 | (@pxref{Debugger User Interface}). | |
393 | ||
394 | @item (ice-9 threads) | |
395 | Guile's support for multi threaded execution (@pxref{Scheduling}). | |
396 | ||
397 | @item (ice-9 rdelim) | |
398 | Line- and character-delimited input (@pxref{Line/Delimited}). | |
399 | ||
400 | @item (ice-9 rw) | |
401 | Block string input/output (@pxref{Block Reading and Writing}). | |
402 | ||
403 | @item (ice-9 documentation) | |
404 | Online documentation (REFFIXME). | |
405 | ||
406 | @item (srfi srfi-1) | |
407 | A library providing a lot of useful list and pair processing | |
408 | procedures (@pxref{SRFI-1}). | |
409 | ||
410 | @item (srfi srfi-2) | |
411 | Support for @code{and-let*} (@pxref{SRFI-2}). | |
412 | ||
413 | @item (srfi srfi-4) | |
414 | Support for homogeneous numeric vectors (@pxref{SRFI-4}). | |
415 | ||
416 | @item (srfi srfi-6) | |
417 | Support for some additional string port procedures (@pxref{SRFI-6}). | |
418 | ||
419 | @item (srfi srfi-8) | |
420 | Multiple-value handling with @code{receive} (@pxref{SRFI-8}). | |
421 | ||
422 | @item (srfi srfi-9) | |
423 | Record definition with @code{define-record-type} (@pxref{SRFI-9}). | |
424 | ||
425 | @item (srfi srfi-10) | |
426 | Read hash extension @code{#,()} (@pxref{SRFI-10}). | |
427 | ||
428 | @item (srfi srfi-11) | |
429 | Multiple-value handling with @code{let-values} and @code{let-values*} | |
430 | (@pxref{SRFI-11}). | |
431 | ||
432 | @item (srfi srfi-13) | |
433 | String library (@pxref{SRFI-13}). | |
434 | ||
435 | @item (srfi srfi-14) | |
436 | Character-set library (@pxref{SRFI-14}). | |
437 | ||
438 | @item (srfi srfi-17) | |
439 | Getter-with-setter support (@pxref{SRFI-17}). | |
440 | ||
441 | @item (ice-9 slib) | |
442 | This module contains hooks for using Aubrey Jaffer's portable Scheme | |
443 | library SLIB from Guile (@pxref{SLIB}). | |
444 | ||
445 | @c FIXME::martin: This module is not in the distribution. Remove it | |
446 | @c from here? | |
447 | @item (ice-9 jacal) | |
448 | This module contains hooks for using Aubrey Jaffer's symbolic math | |
85a9b4ed | 449 | package Jacal from Guile (@pxref{JACAL}). |
a0e07ba4 NJ |
450 | @end table |
451 | ||
452 | ||
453 | @node Dynamic Libraries | |
454 | @section Dynamic Libraries | |
455 | ||
456 | Most modern Unices have something called @dfn{shared libraries}. This | |
457 | ordinarily means that they have the capability to share the executable | |
458 | image of a library between several running programs to save memory and | |
459 | disk space. But generally, shared libraries give a lot of additional | |
460 | flexibility compared to the traditional static libraries. In fact, | |
461 | calling them `dynamic' libraries is as correct as calling them `shared'. | |
462 | ||
463 | Shared libraries really give you a lot of flexibility in addition to the | |
464 | memory and disk space savings. When you link a program against a shared | |
465 | library, that library is not closely incorporated into the final | |
466 | executable. Instead, the executable of your program only contains | |
467 | enough information to find the needed shared libraries when the program | |
468 | is actually run. Only then, when the program is starting, is the final | |
469 | step of the linking process performed. This means that you need not | |
470 | recompile all programs when you install a new, only slightly modified | |
471 | version of a shared library. The programs will pick up the changes | |
472 | automatically the next time they are run. | |
473 | ||
474 | Now, when all the necessary machinery is there to perform part of the | |
475 | linking at run-time, why not take the next step and allow the programmer | |
476 | to explicitly take advantage of it from within his program? Of course, | |
477 | many operating systems that support shared libraries do just that, and | |
478 | chances are that Guile will allow you to access this feature from within | |
479 | your Scheme programs. As you might have guessed already, this feature | |
480 | is called @dfn{dynamic linking}@footnote{Some people also refer to the | |
481 | final linking stage at program startup as `dynamic linking', so if you | |
482 | want to make yourself perfectly clear, it is probably best to use the | |
483 | more technical term @dfn{dlopening}, as suggested by Gordon Matzigkeit | |
484 | in his libtool documentation.} | |
485 | ||
486 | As with many aspects of Guile, there is a low-level way to access the | |
487 | dynamic linking apparatus, and a more high-level interface that | |
488 | integrates dynamically linked libraries into the module system. | |
489 | ||
490 | @menu | |
491 | * Low level dynamic linking:: | |
492 | * Compiled Code Modules:: | |
493 | * Dynamic Linking and Compiled Code Modules:: | |
494 | @end menu | |
495 | ||
496 | @node Low level dynamic linking | |
497 | @subsection Low level dynamic linking | |
498 | ||
499 | When using the low level procedures to do your dynamic linking, you have | |
85a9b4ed | 500 | complete control over which library is loaded when and what gets done |
a0e07ba4 NJ |
501 | with it. |
502 | ||
8f85c0c6 NJ |
503 | @deffn {Scheme Procedure} dynamic-link library |
504 | @deffnx {C Function} scm_dynamic_link (library) | |
a0e07ba4 NJ |
505 | Find the shared library denoted by @var{library} (a string) and link it |
506 | into the running Guile application. When everything works out, return a | |
507 | Scheme object suitable for representing the linked object file. | |
508 | Otherwise an error is thrown. How object files are searched is system | |
509 | dependent. | |
510 | ||
511 | Normally, @var{library} is just the name of some shared library file | |
512 | that will be searched for in the places where shared libraries usually | |
513 | reside, such as in @file{/usr/lib} and @file{/usr/local/lib}. | |
514 | @end deffn | |
515 | ||
8f85c0c6 NJ |
516 | @deffn {Scheme Procedure} dynamic-object? obj |
517 | @deffnx {C Function} scm_dynamic_object_p (obj) | |
518 | Return @code{#t} if @var{obj} is a dynamic library handle, or @code{#f} | |
519 | otherwise. | |
a0e07ba4 NJ |
520 | @end deffn |
521 | ||
8f85c0c6 NJ |
522 | @deffn {Scheme Procedure} dynamic-unlink dobj |
523 | @deffnx {C Function} scm_dynamic_unlink (dobj) | |
524 | Unlink the indicated object file from the application. The | |
525 | argument @var{dobj} must have been obtained by a call to | |
526 | @code{dynamic-link}. After @code{dynamic-unlink} has been | |
527 | called on @var{dobj}, its content is no longer accessible. | |
a0e07ba4 NJ |
528 | @end deffn |
529 | ||
8f85c0c6 NJ |
530 | @deffn {Scheme Procedure} dynamic-func name dobj |
531 | @deffnx {C Function} scm_dynamic_func (name, dobj) | |
532 | Search the dynamic object @var{dobj} for the C function | |
533 | indicated by the string @var{name} and return some Scheme | |
534 | handle that can later be used with @code{dynamic-call} to | |
535 | actually call the function. | |
a0e07ba4 NJ |
536 | |
537 | Regardless whether your C compiler prepends an underscore @samp{_} to | |
538 | the global names in a program, you should @strong{not} include this | |
539 | underscore in @var{function}. Guile knows whether the underscore is | |
540 | needed or not and will add it when necessary. | |
541 | @end deffn | |
542 | ||
8f85c0c6 NJ |
543 | @deffn {Scheme Procedure} dynamic-call func dobj |
544 | @deffnx {C Function} scm_dynamic_call (func, dobj) | |
545 | Call the C function indicated by @var{func} and @var{dobj}. | |
546 | The function is passed no arguments and its return value is | |
547 | ignored. When @var{function} is something returned by | |
548 | @code{dynamic-func}, call that function and ignore @var{dobj}. | |
549 | When @var{func} is a string , look it up in @var{dynobj}; this | |
550 | is equivalent to | |
a0e07ba4 | 551 | @smallexample |
8f85c0c6 | 552 | (dynamic-call (dynamic-func @var{func} @var{dobj} #f)) |
a0e07ba4 NJ |
553 | @end smallexample |
554 | ||
555 | Interrupts are deferred while the C function is executing (with | |
556 | @code{SCM_DEFER_INTS}/@code{SCM_ALLOW_INTS}). | |
557 | @end deffn | |
558 | ||
8f85c0c6 NJ |
559 | @deffn {Scheme Procedure} dynamic-args-call func dobj args |
560 | @deffnx {C Function} scm_dynamic_args_call (func, dobj, args) | |
561 | Call the C function indicated by @var{func} and @var{dobj}, | |
562 | just like @code{dynamic-call}, but pass it some arguments and | |
563 | return its return value. The C function is expected to take | |
564 | two arguments and return an @code{int}, just like @code{main}: | |
a0e07ba4 NJ |
565 | @smallexample |
566 | int c_func (int argc, char **argv); | |
567 | @end smallexample | |
568 | ||
8f85c0c6 NJ |
569 | The parameter @var{args} must be a list of strings and is |
570 | converted into an array of @code{char *}. The array is passed | |
571 | in @var{argv} and its size in @var{argc}. The return value is | |
572 | converted to a Scheme number and returned from the call to | |
573 | @code{dynamic-args-call}. | |
a0e07ba4 NJ |
574 | @end deffn |
575 | ||
576 | When dynamic linking is disabled or not supported on your system, | |
577 | the above functions throw errors, but they are still available. | |
578 | ||
579 | Here is a small example that works on GNU/Linux: | |
580 | ||
581 | @smallexample | |
582 | (define libc-obj (dynamic-link "libc.so")) | |
583 | libc-obj | |
584 | @result{} #<dynamic-object "libc.so"> | |
585 | (dynamic-args-call 'rand libc-obj '()) | |
586 | @result{} 269167349 | |
587 | (dynamic-unlink libc-obj) | |
588 | libc-obj | |
589 | @result{} #<dynamic-object "libc.so" (unlinked)> | |
590 | @end smallexample | |
591 | ||
592 | As you can see, after calling @code{dynamic-unlink} on a dynamically | |
593 | linked library, it is marked as @samp{(unlinked)} and you are no longer | |
594 | able to use it with @code{dynamic-call}, etc. Whether the library is | |
595 | really removed from you program is system-dependent and will generally | |
596 | not happen when some other parts of your program still use it. In the | |
597 | example above, @code{libc} is almost certainly not removed from your | |
598 | program because it is badly needed by almost everything. | |
599 | ||
600 | The functions to call a function from a dynamically linked library, | |
601 | @code{dynamic-call} and @code{dynamic-args-call}, are not very powerful. | |
602 | They are mostly intended to be used for calling specially written | |
603 | initialization functions that will then add new primitives to Guile. | |
604 | For example, we do not expect that you will dynamically link | |
605 | @file{libX11} with @code{dynamic-link} and then construct a beautiful | |
606 | graphical user interface just by using @code{dynamic-call} and | |
607 | @code{dynamic-args-call}. Instead, the usual way would be to write a | |
608 | special Guile<->X11 glue library that has intimate knowledge about both | |
609 | Guile and X11 and does whatever is necessary to make them inter-operate | |
610 | smoothly. This glue library could then be dynamically linked into a | |
611 | vanilla Guile interpreter and activated by calling its initialization | |
612 | function. That function would add all the new types and primitives to | |
613 | the Guile interpreter that it has to offer. | |
614 | ||
615 | From this setup the next logical step is to integrate these glue | |
616 | libraries into the module system of Guile so that you can load new | |
617 | primitives into a running system just as you can load new Scheme code. | |
618 | ||
619 | There is, however, another possibility to get a more thorough access to | |
620 | the functions contained in a dynamically linked library. Anthony Green | |
621 | has written @file{libffi}, a library that implements a @dfn{foreign | |
622 | function interface} for a number of different platforms. With it, you | |
623 | can extend the Spartan functionality of @code{dynamic-call} and | |
624 | @code{dynamic-args-call} considerably. There is glue code available in | |
625 | the Guile contrib archive to make @file{libffi} accessible from Guile. | |
626 | ||
627 | @node Compiled Code Modules | |
628 | @subsection Putting Compiled Code into Modules | |
629 | ||
630 | @c FIXME::martin: Change all gh_ references to their scm_ equivalents. | |
631 | ||
632 | The new primitives that you add to Guile with @code{gh_new_procedure} | |
633 | or with any of the other mechanisms are normally placed into the same | |
634 | module as all the other builtin procedures (like @code{display}). | |
635 | However, it is also possible to put new primitives into their own | |
636 | module. | |
637 | ||
638 | The mechanism for doing so is not very well thought out and is likely to | |
639 | change when the module system of Guile itself is revised, but it is | |
640 | simple and useful enough to document it as it stands. | |
641 | ||
642 | What @code{gh_new_procedure} and the functions used by the snarfer | |
643 | really do is to add the new primitives to whatever module is the | |
644 | @emph{current module} when they are called. This is analogous to the | |
645 | way Scheme code is put into modules: the @code{define-module} expression | |
646 | at the top of a Scheme source file creates a new module and makes it the | |
647 | current module while the rest of the file is evaluated. The | |
648 | @code{define} expressions in that file then add their new definitions to | |
649 | this current module. | |
650 | ||
651 | Therefore, all we need to do is to make sure that the right module is | |
652 | current when calling @code{gh_new_procedure} for our new primitives. | |
653 | Unfortunately, there is not yet an easy way to access the module system | |
654 | from C, so we are better off with a more indirect approach. Instead of | |
655 | adding our primitives at initialization time we merely register with | |
656 | Guile that we are ready to provide the contents of a certain module, | |
657 | should it ever be needed. | |
658 | ||
659 | @deftypefun void scm_register_module_xxx (char *@var{name}, void (*@var{initfunc})(void)) | |
660 | Register with Guile that @var{initfunc} will provide the contents of the | |
661 | module @var{name}. | |
662 | ||
663 | The function @var{initfunc} should perform the usual initialization | |
664 | actions for your new primitives, like calling @code{gh_new_procedure} or | |
665 | including the file produced by the snarfer. When @var{initfunc} is | |
666 | called, the current module is a newly created module with a name as | |
667 | indicated by @var{name}. Each definition that is added to it will be | |
668 | automatically exported. | |
669 | ||
85a9b4ed | 670 | The string @var{name} indicates the hierarchical name of the new module. |
a0e07ba4 NJ |
671 | It should consist of the individual components of the module name |
672 | separated by single spaces. That is, the Scheme module name @code{(foo | |
673 | bar)}, which is a list, should be written as @code{"foo bar"} for the | |
674 | @var{name} parameter. | |
675 | ||
676 | You can call @code{scm_register_module_xxx} at any time, even before | |
677 | Guile has been initialized. This might be useful when you want to put | |
678 | the call to it in some initialization code that is magically called | |
679 | before main, like constructors for global C++ objects. | |
680 | ||
681 | An example for @code{scm_register_module_xxx} appears in the next section. | |
682 | @end deftypefun | |
683 | ||
684 | Now, instead of calling the initialization function at program startup, | |
685 | you should simply call @code{scm_register_module_xxx} and pass it the | |
686 | initialization function. When the named module is later requested by | |
687 | Scheme code with @code{use-modules} for example, Guile will notice that | |
688 | it knows how to create this module and will call the initialization | |
689 | function at the right time in the right context. | |
690 | ||
691 | @node Dynamic Linking and Compiled Code Modules | |
692 | @subsection Dynamic Linking and Compiled Code Modules | |
693 | ||
694 | The most interesting application of dynamically linked libraries is | |
695 | probably to use them for providing @emph{compiled code modules} to | |
696 | Scheme programs. As much fun as programming in Scheme is, every now and | |
697 | then comes the need to write some low-level C stuff to make Scheme even | |
698 | more fun. | |
699 | ||
700 | Not only can you put these new primitives into their own module (see the | |
701 | previous section), you can even put them into a shared library that is | |
702 | only then linked to your running Guile image when it is actually | |
703 | needed. | |
704 | ||
705 | An example will hopefully make everything clear. Suppose we want to | |
706 | make the Bessel functions of the C library available to Scheme in the | |
707 | module @samp{(math bessel)}. First we need to write the appropriate | |
708 | glue code to convert the arguments and return values of the functions | |
709 | from Scheme to C and back. Additionally, we need a function that will | |
710 | add them to the set of Guile primitives. Because this is just an | |
6c997de2 | 711 | example, we will only implement this for the @code{j0} function. |
a0e07ba4 NJ |
712 | |
713 | @c FIXME::martin: Change all gh_ references to their scm_ equivalents. | |
714 | ||
715 | @smallexample | |
716 | #include <math.h> | |
717 | #include <guile/gh.h> | |
718 | ||
719 | SCM | |
720 | j0_wrapper (SCM x) | |
721 | @{ | |
722 | return gh_double2scm (j0 (gh_scm2double (x))); | |
723 | @} | |
724 | ||
725 | void | |
726 | init_math_bessel () | |
727 | @{ | |
728 | gh_new_procedure1_0 ("j0", j0_wrapper); | |
729 | @} | |
730 | @end smallexample | |
731 | ||
732 | We can already try to bring this into action by manually calling the low | |
733 | level functions for performing dynamic linking. The C source file needs | |
734 | to be compiled into a shared library. Here is how to do it on | |
735 | GNU/Linux, please refer to the @code{libtool} documentation for how to | |
736 | create dynamically linkable libraries portably. | |
737 | ||
738 | @smallexample | |
739 | gcc -shared -o libbessel.so -fPIC bessel.c | |
740 | @end smallexample | |
741 | ||
742 | Now fire up Guile: | |
743 | ||
744 | @smalllisp | |
745 | (define bessel-lib (dynamic-link "./libbessel.so")) | |
746 | (dynamic-call "init_math_bessel" bessel-lib) | |
747 | (j0 2) | |
748 | @result{} 0.223890779141236 | |
749 | @end smalllisp | |
750 | ||
751 | The filename @file{./libbessel.so} should be pointing to the shared | |
752 | library produced with the @code{gcc} command above, of course. The | |
753 | second line of the Guile interaction will call the | |
754 | @code{init_math_bessel} function which in turn will register the C | |
755 | function @code{j0_wrapper} with the Guile interpreter under the name | |
756 | @code{j0}. This function becomes immediately available and we can call | |
757 | it from Scheme. | |
758 | ||
759 | Fun, isn't it? But we are only half way there. This is what | |
760 | @code{apropos} has to say about @code{j0}: | |
761 | ||
762 | @smallexample | |
763 | (apropos 'j0) | |
764 | @print{} the-root-module: j0 #<primitive-procedure j0> | |
765 | @end smallexample | |
766 | ||
767 | As you can see, @code{j0} is contained in the root module, where all | |
768 | the other Guile primitives like @code{display}, etc live. In general, | |
769 | a primitive is put into whatever module is the @dfn{current module} at | |
770 | the time @code{gh_new_procedure} is called. To put @code{j0} into its | |
771 | own module named @samp{(math bessel)}, we need to make a call to | |
772 | @code{scm_register_module_xxx}. Additionally, to have Guile perform | |
773 | the dynamic linking automatically, we need to put @file{libbessel.so} | |
774 | into a place where Guile can find it. The call to | |
775 | @code{scm_register_module_xxx} should be contained in a specially | |
776 | named @dfn{module init function}. Guile knows about this special name | |
777 | and will call that function automatically after having linked in the | |
778 | shared library. For our example, we add the following code to | |
779 | @file{bessel.c}: | |
780 | ||
781 | @smallexample | |
782 | void scm_init_math_bessel_module () | |
783 | @{ | |
784 | scm_register_module_xxx ("math bessel", init_math_bessel); | |
785 | @} | |
786 | @end smallexample | |
787 | ||
788 | The general pattern for the name of a module init function is: | |
789 | @samp{scm_init_}, followed by the name of the module where the | |
790 | individual hierarchical components are concatenated with underscores, | |
791 | followed by @samp{_module}. It should call | |
792 | @code{scm_register_module_xxx} with the correct module name and the | |
793 | appropriate initialization function. When that initialization function | |
794 | will be called, a newly created module with the right name will be the | |
795 | @emph{current module} so that all definitions that the initialization | |
796 | functions makes will end up in the correct module. | |
797 | ||
798 | After @file{libbessel.so} has been rebuild, we need to place the shared | |
799 | library into the right place. When Guile tries to autoload the | |
800 | @samp{(math bessel)} module, it looks not only for a file called | |
801 | @file{math/bessel.scm} in its @code{%load-path}, but also for | |
802 | @file{math/libbessel.so}. So all we need to do is to create a directory | |
803 | called @file{math} somewhere in Guile's @code{%load-path} and place | |
804 | @file{libbessel.so} there. Normally, the current directory @file{.} is | |
805 | in the @code{%load-path}, so we just use that for this example. | |
806 | ||
807 | @smallexample | |
808 | % mkdir maths | |
809 | % cd maths | |
810 | % ln -s ../libbessel.so . | |
811 | % cd .. | |
812 | % guile | |
813 | guile> (use-modules (math bessel)) | |
814 | guile> (j0 2) | |
815 | 0.223890779141236 | |
816 | guile> (apropos 'j0) | |
817 | @print{} bessel: j0 #<primitive-procedure j0> | |
818 | @end smallexample | |
819 | ||
820 | That's it! | |
821 | ||
822 | Note that we used a symlink to make @file{libbessel.so} appear in the | |
823 | right spot. This is probably not a bad idea in general. The | |
824 | directories that the @file{%load-path} normally contains are supposed to | |
825 | contain only architecture independent files. They are not really the | |
826 | right place for a shared library. You might want to install the | |
827 | libraries somewhere below @samp{exec_prefix} and then symlink to them | |
828 | from the architecture independent directory. This will at least work on | |
829 | heterogenous systems where the architecture dependent stuff resides in | |
830 | the same place on all machines (which seems like a good idea to me | |
831 | anyway). | |
832 | ||
833 | ||
2a946b44 NJ |
834 | @node Variables |
835 | @section Variables | |
836 | @tpindex Variables | |
837 | ||
838 | A variable is a box-like object that can hold any Scheme value. It is | |
839 | said to be @dfn{undefined} if its box holds a special Scheme value that | |
840 | denotes undefined-ness (which is different from all other Scheme values, | |
841 | including for example @code{#f}); otherwise the variable is | |
842 | @dfn{defined}. | |
843 | ||
844 | On its own, a variable object is anonymous. A variable is said to be | |
845 | @dfn{bound} when it is associated with a name in some way, usually a | |
846 | symbol in a module obarray. When this happens, the relationship is | |
847 | mutual: the variable is bound to the name (in that module), and the name | |
848 | (in that module) is bound to the variable. | |
849 | ||
850 | (That's the theory, anyway. In practice, defined-ness and bound-ness | |
851 | sometimes get confused, because Lisp and Scheme implementations have | |
852 | often conflated --- or deliberately drawn no distinction between --- a | |
853 | name that is unbound and a name that is bound to a variable whose value | |
854 | is undefined. We will try to be clear about the difference and explain | |
855 | any confusion where it is unavoidable.) | |
856 | ||
857 | Variables do not have a read syntax. Most commonly they are created and | |
858 | bound implicitly by @code{define} expressions: a top-level @code{define} | |
859 | expression of the form | |
860 | ||
861 | @lisp | |
862 | (define @var{name} @var{value}) | |
863 | @end lisp | |
864 | ||
865 | @noindent | |
866 | creates a variable with initial value @var{value} and binds it to the | |
867 | name @var{name} in the current module. But they can also be created | |
868 | dynamically by calling one of the constructor procedures | |
869 | @code{make-variable} and @code{make-undefined-variable}. | |
870 | ||
871 | First-class variables are especially useful for interacting with the | |
872 | current module system (@pxref{The Guile module system}). | |
873 | ||
874 | @deffn {Scheme Procedure} make-undefined-variable | |
875 | @deffnx {C Function} scm_make_undefined_variable () | |
876 | Return a variable that is initially unbound. | |
877 | @end deffn | |
878 | ||
879 | @deffn {Scheme Procedure} make-variable init | |
880 | @deffnx {C Function} scm_make_variable (init) | |
881 | Return a variable initialized to value @var{init}. | |
882 | @end deffn | |
883 | ||
884 | @deffn {Scheme Procedure} variable-bound? var | |
885 | @deffnx {C Function} scm_variable_bound_p (var) | |
886 | Return @code{#t} iff @var{var} is bound to a value. | |
887 | Throws an error if @var{var} is not a variable object. | |
888 | @end deffn | |
889 | ||
890 | @deffn {Scheme Procedure} variable-ref var | |
891 | @deffnx {C Function} scm_variable_ref (var) | |
892 | Dereference @var{var} and return its value. | |
893 | @var{var} must be a variable object; see @code{make-variable} | |
894 | and @code{make-undefined-variable}. | |
895 | @end deffn | |
896 | ||
897 | @deffn {Scheme Procedure} variable-set! var val | |
898 | @deffnx {C Function} scm_variable_set_x (var, val) | |
899 | Set the value of the variable @var{var} to @var{val}. | |
900 | @var{var} must be a variable object, @var{val} can be any | |
901 | value. Return an unspecified value. | |
902 | @end deffn | |
903 | ||
904 | @deffn {Scheme Procedure} variable? obj | |
905 | @deffnx {C Function} scm_variable_p (obj) | |
906 | Return @code{#t} iff @var{obj} is a variable object, else | |
907 | return @code{#f}. | |
908 | @end deffn | |
909 | ||
910 | ||
a0e07ba4 NJ |
911 | @c Local Variables: |
912 | @c TeX-master: "guile.texi" | |
913 | @c End: |