Commit | Line | Data |
---|---|---|
07d83abe MV |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Guile Reference Manual. | |
c8779dde | 3 | @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2007, 2008 |
07d83abe MV |
4 | @c Free Software Foundation, Inc. |
5 | @c See the file guile.texi for copying conditions. | |
6 | ||
7 | @page | |
8 | @node Modules | |
9 | @section Modules | |
10 | @cindex modules | |
11 | ||
12 | When programs become large, naming conflicts can occur when a function | |
13 | or global variable defined in one file has the same name as a function | |
14 | or global variable in another file. Even just a @emph{similarity} | |
15 | between function names can cause hard-to-find bugs, since a programmer | |
16 | might type the wrong function name. | |
17 | ||
18 | The approach used to tackle this problem is called @emph{information | |
19 | encapsulation}, which consists of packaging functional units into a | |
20 | given name space that is clearly separated from other name spaces. | |
21 | @cindex encapsulation | |
22 | @cindex information encapsulation | |
23 | @cindex name space | |
24 | ||
25 | The language features that allow this are usually called @emph{the | |
26 | module system} because programs are broken up into modules that are | |
27 | compiled separately (or loaded separately in an interpreter). | |
28 | ||
29 | Older languages, like C, have limited support for name space | |
30 | manipulation and protection. In C a variable or function is public by | |
31 | default, and can be made local to a module with the @code{static} | |
32 | keyword. But you cannot reference public variables and functions from | |
33 | another module with different names. | |
34 | ||
35 | More advanced module systems have become a common feature in recently | |
36 | designed languages: ML, Python, Perl, and Modula 3 all allow the | |
37 | @emph{renaming} of objects from a foreign module, so they will not | |
38 | clutter the global name space. | |
39 | @cindex name space - private | |
40 | ||
41 | In addition, Guile offers variables as first-class objects. They can | |
42 | be used for interacting with the module system. | |
43 | ||
44 | @menu | |
45 | * provide and require:: The SLIB feature mechanism. | |
46 | * Environments:: R5RS top-level environments. | |
47 | * The Guile module system:: How Guile does it. | |
48 | * Dynamic Libraries:: Loading libraries of compiled code at run time. | |
49 | * Variables:: First-class variables. | |
50 | @end menu | |
51 | ||
52 | @node provide and require | |
53 | @subsection provide and require | |
54 | ||
55 | Aubrey Jaffer, mostly to support his portable Scheme library SLIB, | |
56 | implemented a provide/require mechanism for many Scheme implementations. | |
57 | Library files in SLIB @emph{provide} a feature, and when user programs | |
58 | @emph{require} that feature, the library file is loaded in. | |
59 | ||
60 | For example, the file @file{random.scm} in the SLIB package contains the | |
61 | line | |
62 | ||
aba0dff5 | 63 | @lisp |
07d83abe | 64 | (provide 'random) |
aba0dff5 | 65 | @end lisp |
07d83abe MV |
66 | |
67 | so to use its procedures, a user would type | |
68 | ||
aba0dff5 | 69 | @lisp |
07d83abe | 70 | (require 'random) |
aba0dff5 | 71 | @end lisp |
07d83abe MV |
72 | |
73 | and they would magically become available, @emph{but still have the same | |
74 | names!} So this method is nice, but not as good as a full-featured | |
75 | module system. | |
76 | ||
77 | When SLIB is used with Guile, provide and require can be used to access | |
78 | its facilities. | |
79 | ||
80 | @node Environments | |
81 | @subsection Environments | |
82 | @cindex environment | |
83 | ||
84 | Scheme, as defined in R5RS, does @emph{not} have a full module system. | |
85 | However it does define the concept of a top-level @dfn{environment}. | |
86 | Such an environment maps identifiers (symbols) to Scheme objects such | |
87 | as procedures and lists: @ref{About Closure}. In other words, it | |
88 | implements a set of @dfn{bindings}. | |
89 | ||
90 | Environments in R5RS can be passed as the second argument to | |
91 | @code{eval} (@pxref{Fly Evaluation}). Three procedures are defined to | |
92 | return environments: @code{scheme-report-environment}, | |
93 | @code{null-environment} and @code{interaction-environment} (@pxref{Fly | |
94 | Evaluation}). | |
95 | ||
96 | In addition, in Guile any module can be used as an R5RS environment, | |
97 | i.e., passed as the second argument to @code{eval}. | |
98 | ||
99 | Note: the following two procedures are available only when the | |
100 | @code{(ice-9 r5rs)} module is loaded: | |
101 | ||
aba0dff5 | 102 | @lisp |
07d83abe | 103 | (use-modules (ice-9 r5rs)) |
aba0dff5 | 104 | @end lisp |
07d83abe MV |
105 | |
106 | @deffn {Scheme Procedure} scheme-report-environment version | |
107 | @deffnx {Scheme Procedure} null-environment version | |
108 | @var{version} must be the exact integer `5', corresponding to revision | |
109 | 5 of the Scheme report (the Revised^5 Report on Scheme). | |
110 | @code{scheme-report-environment} returns a specifier for an | |
111 | environment that is empty except for all bindings defined in the | |
112 | report that are either required or both optional and supported by the | |
113 | implementation. @code{null-environment} returns a specifier for an | |
114 | environment that is empty except for the (syntactic) bindings for all | |
115 | syntactic keywords defined in the report that are either required or | |
116 | both optional and supported by the implementation. | |
117 | ||
118 | Currently Guile does not support values of @var{version} for other | |
119 | revisions of the report. | |
120 | ||
121 | The effect of assigning (through the use of @code{eval}) a variable | |
122 | bound in a @code{scheme-report-environment} (for example @code{car}) | |
123 | is unspecified. Currently the environments specified by | |
124 | @code{scheme-report-environment} are not immutable in Guile. | |
125 | @end deffn | |
126 | ||
127 | @node The Guile module system | |
128 | @subsection The Guile module system | |
129 | ||
130 | The Guile module system extends the concept of environments, discussed | |
131 | in the previous section, with mechanisms to define, use and customise | |
132 | sets of bindings. | |
133 | ||
134 | In 1996 Tom Lord implemented a full-featured module system for Guile which | |
135 | allows loading Scheme source files into a private name space. This system has | |
9f1ba6a9 | 136 | been available since at least Guile version 1.1. |
07d83abe MV |
137 | |
138 | For Guile version 1.5.0 and later, the system has been improved to have better | |
139 | integration from C code, more fine-grained user control over interfaces, and | |
140 | documentation. | |
141 | ||
142 | Although it is anticipated that the module system implementation will | |
143 | change in the future, the Scheme programming interface described in this | |
144 | manual should be considered stable. The C programming interface is | |
145 | considered relatively stable, although at the time of this writing, | |
146 | there is still some flux. | |
147 | ||
148 | @menu | |
149 | * General Information about Modules:: Guile module basics. | |
150 | * Using Guile Modules:: How to use existing modules. | |
151 | * Creating Guile Modules:: How to package your code into modules. | |
cdf1ad3b | 152 | * Module System Reflection:: Accessing module objects at run-time. |
07d83abe MV |
153 | * Module System Quirks:: Strange things to be aware of. |
154 | * Included Guile Modules:: Which modules come with Guile? | |
155 | * Accessing Modules from C:: How to work with modules with C code. | |
156 | @end menu | |
157 | ||
158 | @node General Information about Modules | |
159 | @subsubsection General Information about Modules | |
160 | ||
161 | A Guile module can be thought of as a collection of named procedures, | |
162 | variables and macros. More precisely, it is a set of @dfn{bindings} | |
163 | of symbols (names) to Scheme objects. | |
164 | ||
165 | An environment is a mapping from identifiers (or symbols) to locations, | |
166 | i.e., a set of bindings. | |
167 | There are top-level environments and lexical environments. | |
168 | The environment in which a lambda is executed is remembered as part of its | |
169 | definition. | |
170 | ||
171 | Within a module, all bindings are visible. Certain bindings | |
172 | can be declared @dfn{public}, in which case they are added to the | |
173 | module's so-called @dfn{export list}; this set of public bindings is | |
174 | called the module's @dfn{public interface} (@pxref{Creating Guile | |
175 | Modules}). | |
176 | ||
177 | A client module @dfn{uses} a providing module's bindings by either | |
178 | accessing the providing module's public interface, or by building a | |
179 | custom interface (and then accessing that). In a custom interface, the | |
180 | client module can @dfn{select} which bindings to access and can also | |
181 | algorithmically @dfn{rename} bindings. In contrast, when using the | |
182 | providing module's public interface, the entire export list is available | |
183 | without renaming (@pxref{Using Guile Modules}). | |
184 | ||
185 | To use a module, it must be found and loaded. All Guile modules have a | |
186 | unique @dfn{module name}, which is a list of one or more symbols. | |
187 | Examples are @code{(ice-9 popen)} or @code{(srfi srfi-11)}. When Guile | |
188 | searches for the code of a module, it constructs the name of the file to | |
189 | load by concatenating the name elements with slashes between the | |
190 | elements and appending a number of file name extensions from the list | |
191 | @code{%load-extensions} (@pxref{Loading}). The resulting file name is | |
192 | then searched in all directories in the variable @code{%load-path} | |
193 | (@pxref{Build Config}). For example, the @code{(ice-9 popen)} module | |
194 | would result in the filename @code{ice-9/popen.scm} and searched in the | |
195 | installation directories of Guile and in all other directories in the | |
196 | load path. | |
197 | ||
198 | @c FIXME::martin: Not sure about this, maybe someone knows better? | |
199 | Every module has a so-called syntax transformer associated with it. | |
200 | This is a procedure which performs all syntax transformation for the | |
201 | time the module is read in and evaluated. When working with modules, | |
202 | you can manipulate the current syntax transformer using the | |
203 | @code{use-syntax} syntactic form or the @code{#:use-syntax} module | |
204 | definition option (@pxref{Creating Guile Modules}). | |
205 | ||
206 | Please note that there are some problems with the current module system | |
207 | you should keep in mind (@pxref{Module System Quirks}). We hope to | |
208 | address these eventually. | |
209 | ||
210 | ||
211 | @node Using Guile Modules | |
212 | @subsubsection Using Guile Modules | |
213 | ||
214 | To use a Guile module is to access either its public interface or a | |
215 | custom interface (@pxref{General Information about Modules}). Both | |
216 | types of access are handled by the syntactic form @code{use-modules}, | |
217 | which accepts one or more interface specifications and, upon evaluation, | |
218 | arranges for those interfaces to be available to the current module. | |
219 | This process may include locating and loading code for a given module if | |
5c132e68 | 220 | that code has not yet been loaded, following @code{%load-path} (@pxref{Build |
07d83abe MV |
221 | Config}). |
222 | ||
223 | An @dfn{interface specification} has one of two forms. The first | |
224 | variation is simply to name the module, in which case its public | |
225 | interface is the one accessed. For example: | |
226 | ||
aba0dff5 | 227 | @lisp |
07d83abe | 228 | (use-modules (ice-9 popen)) |
aba0dff5 | 229 | @end lisp |
07d83abe MV |
230 | |
231 | Here, the interface specification is @code{(ice-9 popen)}, and the | |
232 | result is that the current module now has access to @code{open-pipe}, | |
233 | @code{close-pipe}, @code{open-input-pipe}, and so on (@pxref{Included | |
234 | Guile Modules}). | |
235 | ||
236 | Note in the previous example that if the current module had already | |
237 | defined @code{open-pipe}, that definition would be overwritten by the | |
238 | definition in @code{(ice-9 popen)}. For this reason (and others), there | |
239 | is a second variation of interface specification that not only names a | |
240 | module to be accessed, but also selects bindings from it and renames | |
241 | them to suit the current module's needs. For example: | |
242 | ||
46bb559d | 243 | @cindex binding renamer |
aba0dff5 | 244 | @lisp |
07d83abe | 245 | (use-modules ((ice-9 popen) |
8d9cb14e NJ |
246 | #:select ((open-pipe . pipe-open) close-pipe) |
247 | #:renamer (symbol-prefix-proc 'unixy:))) | |
aba0dff5 | 248 | @end lisp |
07d83abe MV |
249 | |
250 | Here, the interface specification is more complex than before, and the | |
251 | result is that a custom interface with only two bindings is created and | |
252 | subsequently accessed by the current module. The mapping of old to new | |
253 | names is as follows: | |
254 | ||
255 | @c Use `smallexample' since `table' is ugly. --ttn | |
256 | @smallexample | |
257 | (ice-9 popen) sees: current module sees: | |
258 | open-pipe unixy:pipe-open | |
259 | close-pipe unixy:close-pipe | |
260 | @end smallexample | |
261 | ||
262 | This example also shows how to use the convenience procedure | |
263 | @code{symbol-prefix-proc}. | |
264 | ||
265 | You can also directly refer to bindings in a module by using the | |
266 | @code{@@} syntax. For example, instead of using the | |
267 | @code{use-modules} statement from above and writing | |
268 | @code{unixy:pipe-open} to refer to the @code{pipe-open} from the | |
269 | @code{(ice-9 popen)}, you could also write @code{(@@ (ice-9 popen) | |
270 | open-pipe)}. Thus an alternative to the complete @code{use-modules} | |
271 | statement would be | |
272 | ||
aba0dff5 | 273 | @lisp |
07d83abe MV |
274 | (define unixy:pipe-open (@@ (ice-9 popen) open-pipe)) |
275 | (define unixy:close-pipe (@@ (ice-9 popen) close-pipe)) | |
aba0dff5 | 276 | @end lisp |
07d83abe MV |
277 | |
278 | There is also @code{@@@@}, which can be used like @code{@@}, but does | |
279 | not check whether the variable that is being accessed is actually | |
280 | exported. Thus, @code{@@@@} can be thought of as the impolite version | |
281 | of @code{@@} and should only be used as a last resort or for | |
282 | debugging, for example. | |
283 | ||
284 | Note that just as with a @code{use-modules} statement, any module that | |
285 | has not yet been loaded yet will be loaded when referenced by a | |
286 | @code{@@} or @code{@@@@} form. | |
287 | ||
288 | You can also use the @code{@@} and @code{@@@@} syntaxes as the target | |
289 | of a @code{set!} when the binding refers to a variable. | |
290 | ||
291 | @c begin (scm-doc-string "boot-9.scm" "symbol-prefix-proc") | |
292 | @deffn {Scheme Procedure} symbol-prefix-proc prefix-sym | |
293 | Return a procedure that prefixes its arg (a symbol) with | |
294 | @var{prefix-sym}. | |
295 | @c Insert gratuitous C++ slam here. --ttn | |
296 | @end deffn | |
297 | ||
298 | @c begin (scm-doc-string "boot-9.scm" "use-modules") | |
299 | @deffn syntax use-modules spec @dots{} | |
300 | Resolve each interface specification @var{spec} into an interface and | |
301 | arrange for these to be accessible by the current module. The return | |
302 | value is unspecified. | |
303 | ||
304 | @var{spec} can be a list of symbols, in which case it names a module | |
305 | whose public interface is found and used. | |
306 | ||
307 | @var{spec} can also be of the form: | |
308 | ||
46bb559d | 309 | @cindex binding renamer |
aba0dff5 | 310 | @lisp |
07d83abe | 311 | (MODULE-NAME [:select SELECTION] [:renamer RENAMER]) |
aba0dff5 | 312 | @end lisp |
07d83abe MV |
313 | |
314 | in which case a custom interface is newly created and used. | |
315 | @var{module-name} is a list of symbols, as above; @var{selection} is a | |
316 | list of selection-specs; and @var{renamer} is a procedure that takes a | |
317 | symbol and returns its new name. A selection-spec is either a symbol or | |
318 | a pair of symbols @code{(ORIG . SEEN)}, where @var{orig} is the name in | |
319 | the used module and @var{seen} is the name in the using module. Note | |
320 | that @var{seen} is also passed through @var{renamer}. | |
321 | ||
322 | The @code{:select} and @code{:renamer} clauses are optional. If both are | |
323 | omitted, the returned interface has no bindings. If the @code{:select} | |
324 | clause is omitted, @var{renamer} operates on the used module's public | |
325 | interface. | |
326 | ||
327 | Signal error if module name is not resolvable. | |
328 | @end deffn | |
329 | ||
330 | ||
331 | @c FIXME::martin: Is this correct, and is there more to say? | |
c8779dde | 332 | @c FIXME::martin: Define term and concept `syntax transformer' somewhere. |
07d83abe MV |
333 | |
334 | @deffn syntax use-syntax module-name | |
c8779dde LC |
335 | Load the module @code{module-name} and use its syntax |
336 | transformer as the syntax transformer for the currently defined module, | |
337 | as well as installing it as the current syntax transformer. | |
07d83abe MV |
338 | @end deffn |
339 | ||
340 | @deffn syntax @@ module-name binding-name | |
341 | Refer to the binding named @var{binding-name} in module | |
342 | @var{module-name}. The binding must have been exported by the module. | |
343 | @end deffn | |
344 | ||
345 | @deffn syntax @@@@ module-name binding-name | |
346 | Refer to the binding named @var{binding-name} in module | |
347 | @var{module-name}. The binding must not have been exported by the | |
348 | module. This syntax is only intended for debugging purposes or as a | |
349 | last resort. | |
350 | @end deffn | |
351 | ||
352 | @node Creating Guile Modules | |
353 | @subsubsection Creating Guile Modules | |
354 | ||
355 | When you want to create your own modules, you have to take the following | |
356 | steps: | |
357 | ||
358 | @itemize @bullet | |
359 | @item | |
360 | Create a Scheme source file and add all variables and procedures you wish | |
361 | to export, or which are required by the exported procedures. | |
362 | ||
363 | @item | |
364 | Add a @code{define-module} form at the beginning. | |
365 | ||
366 | @item | |
367 | Export all bindings which should be in the public interface, either | |
368 | by using @code{define-public} or @code{export} (both documented below). | |
369 | @end itemize | |
370 | ||
371 | @c begin (scm-doc-string "boot-9.scm" "define-module") | |
372 | @deffn syntax define-module module-name [options @dots{}] | |
373 | @var{module-name} is of the form @code{(hierarchy file)}. One | |
374 | example of this is | |
375 | ||
aba0dff5 | 376 | @lisp |
07d83abe | 377 | (define-module (ice-9 popen)) |
aba0dff5 | 378 | @end lisp |
07d83abe MV |
379 | |
380 | @code{define-module} makes this module available to Guile programs under | |
381 | the given @var{module-name}. | |
382 | ||
383 | The @var{options} are keyword/value pairs which specify more about the | |
384 | defined module. The recognized options and their meaning is shown in | |
385 | the following table. | |
386 | ||
387 | @c fixme: Should we use "#:" or ":"? | |
388 | ||
389 | @table @code | |
390 | @item #:use-module @var{interface-specification} | |
391 | Equivalent to a @code{(use-modules @var{interface-specification})} | |
392 | (@pxref{Using Guile Modules}). | |
393 | ||
394 | @item #:use-syntax @var{module} | |
395 | Use @var{module} when loading the currently defined module, and install | |
396 | it as the syntax transformer. | |
397 | ||
950f97ac | 398 | @item #:autoload @var{module} @var{symbol-list} |
65f1345f | 399 | @cindex autoload |
950f97ac KR |
400 | Load @var{module} when any of @var{symbol-list} are accessed. For |
401 | example, | |
402 | ||
403 | @example | |
404 | (define-module (my mod) | |
405 | #:autoload (srfi srfi-1) (partition delete-duplicates)) | |
406 | ... | |
407 | (if something | |
408 | (set! foo (delete-duplicates ...))) | |
409 | @end example | |
410 | ||
a236df75 | 411 | When a module is autoloaded, all its bindings become available. |
950f97ac KR |
412 | @var{symbol-list} is just those that will first trigger the load. |
413 | ||
414 | An autoload is a good way to put off loading a big module until it's | |
415 | really needed, for instance for faster startup or if it will only be | |
416 | needed in certain circumstances. | |
417 | ||
418 | @code{@@} can do a similar thing (@pxref{Using Guile Modules}), but in | |
419 | that case an @code{@@} form must be written every time a binding from | |
420 | the module is used. | |
07d83abe MV |
421 | |
422 | @item #:export @var{list} | |
65f1345f | 423 | @cindex export |
46bb559d | 424 | Export all identifiers in @var{list} which must be a list of symbols. |
07d83abe MV |
425 | This is equivalent to @code{(export @var{list})} in the module body. |
426 | ||
46bb559d KR |
427 | @item #:re-export @var{list} |
428 | @cindex re-export | |
429 | Re-export all identifiers in @var{list} which must be a list of | |
430 | symbols. The symbols in @var{list} must be imported by the current | |
431 | module from other modules. This is equivalent to @code{re-export} | |
432 | below. | |
433 | ||
434 | @item #:export-syntax @var{list} | |
435 | @cindex export-syntax | |
436 | Export all identifiers in @var{list} which must be a list of symbols. | |
437 | The identifiers in @var{list} must refer to macros (@pxref{Macros}) | |
438 | defined in the current module. This is equivalent to | |
439 | @code{(export-syntax @var{list})} in the module body. | |
440 | ||
441 | @item #:re-export-syntax @var{list} | |
442 | @cindex re-export-syntax | |
443 | Re-export all identifiers in @var{list} which must be a list of | |
444 | symbols. The symbols in @var{list} must refer to macros imported by | |
445 | the current module from other modules. This is equivalent to | |
446 | @code{(re-export-syntax @var{list})} in the module body. | |
447 | ||
448 | @item #:replace @var{list} | |
449 | @cindex replace | |
450 | @cindex replacing binding | |
451 | @cindex overriding binding | |
452 | @cindex duplicate binding | |
453 | Export all identifiers in @var{list} (a list of symbols) and mark them | |
454 | as @dfn{replacing bindings}. In the module user's name space, this | |
455 | will have the effect of replacing any binding with the same name that | |
456 | is not also ``replacing''. Normally a replacement results in an | |
457 | ``override'' warning message, @code{#:replace} avoids that. | |
458 | ||
e724644d MV |
459 | This is useful for modules that export bindings that have the same |
460 | name as core bindings. @code{#:replace}, in a sense, lets Guile know | |
461 | that the module @emph{purposefully} replaces a core binding. It is | |
462 | important to note, however, that this binding replacement is confined | |
463 | to the name space of the module user. In other words, the value of the | |
464 | core binding in question remains unchanged for other modules. | |
465 | ||
466 | For instance, SRFI-39 exports a binding named | |
467 | @code{current-input-port} (@pxref{SRFI-39}) that is a function which | |
468 | is upwardly compatible with the core @code{current-input-port} | |
469 | function. Therefore, SRFI-39 exports its version with | |
470 | @code{#:replace}. | |
471 | ||
472 | SRFI-19, on the other hand, exports its own version of | |
473 | @code{current-time} (@pxref{SRFI-19 Time}) which is not compatible | |
474 | with the core @code{current-time} function (@pxref{Time}). Therefore, | |
475 | SRFI-19 does not use @code{#:replace}. | |
476 | ||
477 | The @code{#:replace} option can also be used by a module which is | |
478 | intentionally producing a new special kind of environment and should | |
479 | override any core or other bindings already in scope. For example | |
480 | perhaps a logic processing environment where @code{<=} is an inference | |
481 | instead of a comparison. | |
482 | ||
483 | The @code{#:duplicates} (see below) provides fine-grain control about | |
484 | duplicate binding handling on the module-user side. | |
46bb559d KR |
485 | |
486 | @item #:duplicates @var{list} | |
487 | @cindex duplicate binding handlers | |
488 | @cindex duplicate binding | |
489 | @cindex overriding binding | |
490 | Tell Guile to handle duplicate bindings for the bindings imported by | |
491 | the current module according to the policy defined by @var{list}, a | |
492 | list of symbols. @var{list} must contain symbols representing a | |
493 | duplicate binding handling policy chosen among the following: | |
494 | ||
495 | @table @code | |
496 | @item check | |
497 | Raises an error when a binding is imported from more than one place. | |
498 | @item warn | |
499 | Issue a warning when a binding is imported from more than one place | |
500 | and leave the responsibility of actually handling the duplication to | |
501 | the next duplicate binding handler. | |
502 | @item replace | |
503 | When a new binding is imported that has the same name as a previously | |
504 | imported binding, then do the following: | |
505 | ||
506 | @enumerate | |
507 | @item | |
508 | @cindex replacing binding | |
509 | If the old binding was said to be @dfn{replacing} (via the | |
510 | @code{#:replace} option above) and the new binding is not replacing, | |
511 | the keep the old binding. | |
512 | @item | |
513 | If the old binding was not said to be replacing and the new binding is | |
514 | replacing, then replace the old binding with the new one. | |
515 | @item | |
516 | If neither the old nor the new binding is replacing, then keep the old | |
517 | one. | |
518 | @end enumerate | |
519 | ||
520 | @item warn-override-core | |
521 | Issue a warning when a core binding is being overwritten and actually | |
522 | override the core binding with the new one. | |
523 | @item first | |
524 | In case of duplicate bindings, the firstly imported binding is always | |
525 | the one which is kept. | |
526 | @item last | |
527 | In case of duplicate bindings, the lastly imported binding is always | |
528 | the one which is kept. | |
529 | @item noop | |
530 | In case of duplicate bindings, leave the responsibility to the next | |
531 | duplicate handler. | |
532 | @end table | |
533 | ||
534 | If @var{list} contains more than one symbol, then the duplicate | |
535 | binding handlers which appear first will be used first when resolving | |
536 | a duplicate binding situation. As mentioned above, some resolution | |
537 | policies may explicitly leave the responsibility of handling the | |
538 | duplication to the next handler in @var{list}. | |
539 | ||
540 | @findex default-duplicate-binding-handler | |
541 | The default duplicate binding resolution policy is given by the | |
542 | @code{default-duplicate-binding-handler} procedure, and is | |
543 | ||
aba0dff5 | 544 | @lisp |
46bb559d | 545 | (replace warn-override-core warn last) |
aba0dff5 | 546 | @end lisp |
46bb559d | 547 | |
07d83abe | 548 | @item #:no-backtrace |
65f1345f | 549 | @cindex no backtrace |
07d83abe MV |
550 | Tell Guile not to record information for procedure backtraces when |
551 | executing the procedures in this module. | |
552 | ||
553 | @item #:pure | |
65f1345f | 554 | @cindex pure module |
07d83abe MV |
555 | Create a @dfn{pure} module, that is a module which does not contain any |
556 | of the standard procedure bindings except for the syntax forms. This is | |
557 | useful if you want to create @dfn{safe} modules, that is modules which | |
558 | do not know anything about dangerous procedures. | |
559 | @end table | |
560 | ||
561 | @end deffn | |
562 | @c end | |
563 | ||
564 | @deffn syntax export variable @dots{} | |
565 | Add all @var{variable}s (which must be symbols) to the list of exported | |
566 | bindings of the current module. | |
567 | @end deffn | |
568 | ||
569 | @c begin (scm-doc-string "boot-9.scm" "define-public") | |
570 | @deffn syntax define-public @dots{} | |
571 | Equivalent to @code{(begin (define foo ...) (export foo))}. | |
572 | @end deffn | |
573 | @c end | |
574 | ||
46bb559d KR |
575 | @deffn syntax re-export variable @dots{} |
576 | Add all @var{variable}s (which must be symbols) to the list of | |
577 | re-exported bindings of the current module. Re-exported bindings must | |
578 | be imported by the current module from some other module. | |
579 | @end deffn | |
580 | ||
cdf1ad3b MV |
581 | @node Module System Reflection |
582 | @subsubsection Module System Reflection | |
583 | ||
584 | The previous sections have described a declarative view of the module | |
585 | system. You can also work with it programmatically by accessing and | |
586 | modifying various parts of the Scheme objects that Guile uses to | |
587 | implement the module system. | |
588 | ||
589 | At any time, there is a @dfn{current module}. This module is the one | |
590 | where a top-level @code{define} and similar syntax will add new | |
591 | bindings. You can find other module objects with @code{resolve-module}, | |
592 | for example. | |
593 | ||
594 | These module objects can be used as the second argument to @code{eval}. | |
595 | ||
596 | @deffn {Scheme Procedure} current-module | |
597 | Return the current module object. | |
598 | @end deffn | |
599 | ||
600 | @deffn {Scheme Procedure} set-current-module module | |
601 | Set the current module to @var{module} and return | |
602 | the previous current module. | |
603 | @end deffn | |
604 | ||
b1f57ea4 LC |
605 | @deffn {Scheme Procedure} save-module-excursion thunk |
606 | Call @var{thunk} within a @code{dynamic-wind} such that the module that | |
607 | is current at invocation time is restored when @var{thunk}'s dynamic | |
608 | extent is left (@pxref{Dynamic Wind}). | |
609 | ||
610 | More precisely, if @var{thunk} escapes non-locally, the current module | |
611 | (at the time of escape) is saved, and the original current module (at | |
612 | the time @var{thunk}'s dynamic extent was last entered) is restored. If | |
613 | @var{thunk}'s dynamic extent is re-entered, then the current module is | |
614 | saved, and the previously saved inner module is set current again. | |
615 | @end deffn | |
616 | ||
cdf1ad3b MV |
617 | @deffn {Scheme Procedure} resolve-module name |
618 | Find the module named @var{name} and return it. When it has not already | |
619 | been defined, try to auto-load it. When it can't be found that way | |
620 | either, create an empty module. The name is a list of symbols. | |
621 | @end deffn | |
622 | ||
623 | @deffn {Scheme Procedure} resolve-interface name | |
624 | Find the module named @var{name} as with @code{resolve-module} and | |
625 | return its interface. The interface of a module is also a module | |
626 | object, but it contains only the exported bindings. | |
627 | @end deffn | |
628 | ||
629 | @deffn {Scheme Procedure} module-use! module interface | |
630 | Add @var{interface} to the front of the use-list of @var{module}. Both | |
631 | arguments should be module objects, and @var{interface} should very | |
632 | likely be a module returned by @code{resolve-interface}. | |
633 | @end deffn | |
07d83abe MV |
634 | |
635 | @node Module System Quirks | |
636 | @subsubsection Module System Quirks | |
637 | ||
638 | Although the programming interfaces are relatively stable, the Guile | |
639 | module system itself is still evolving. Here are some situations where | |
640 | usage surpasses design. | |
641 | ||
642 | @itemize @bullet | |
643 | ||
644 | @item | |
645 | When using a module which exports a macro definition, the other module | |
646 | must export all bindings the macro expansion uses, too, because the | |
647 | expanded code would otherwise not be able to see these definitions and | |
648 | issue a ``variable unbound'' error, or worse, would use another binding | |
649 | which might be present in the scope of the expansion. | |
650 | ||
651 | @item | |
652 | When two or more used modules export bindings with the same names, the | |
653 | last accessed module wins, and the exported binding of that last module | |
654 | will silently be used. This might lead to hard-to-find errors because | |
655 | wrong procedures or variables are used. To avoid this kind of | |
656 | @dfn{name-clash} situation, use a custom interface specification | |
657 | (@pxref{Using Guile Modules}). (We include this entry for the possible | |
658 | benefit of users of Guile versions previous to 1.5.0, when custom | |
659 | interfaces were added to the module system.) | |
660 | ||
661 | @item | |
662 | [Add other quirks here.] | |
663 | ||
664 | @end itemize | |
665 | ||
666 | ||
667 | @node Included Guile Modules | |
668 | @subsubsection Included Guile Modules | |
669 | ||
670 | @c FIXME::martin: Review me! | |
671 | ||
672 | Some modules are included in the Guile distribution; here are references | |
673 | to the entries in this manual which describe them in more detail: | |
674 | ||
675 | @table @strong | |
676 | @item boot-9 | |
677 | boot-9 is Guile's initialization module, and it is always loaded when | |
678 | Guile starts up. | |
679 | ||
680 | @item (ice-9 debug) | |
681 | Mikael Djurfeldt's source-level debugging support for Guile | |
24dbb5ed | 682 | (@pxref{Tracing}). |
07d83abe | 683 | |
54a3c992 KR |
684 | @item (ice-9 expect) |
685 | Actions based on matching input from a port (@pxref{Expect}). | |
686 | ||
687 | @item (ice-9 format) | |
688 | Formatted output in the style of Common Lisp (@pxref{Formatted | |
689 | Output}). | |
690 | ||
691 | @item (ice-9 ftw) | |
692 | File tree walker (@pxref{File Tree Walk}). | |
693 | ||
694 | @item (ice-9 getopt-long) | |
695 | Command line option processing (@pxref{getopt-long}). | |
696 | ||
697 | @item (ice-9 history) | |
698 | Refer to previous interactive expressions (@pxref{Value History}). | |
699 | ||
700 | @item (ice-9 popen) | |
701 | Pipes to and from child processes (@pxref{Pipes}). | |
702 | ||
703 | @item (ice-9 pretty-print) | |
704 | Nicely formatted output of Scheme expressions and objects | |
705 | (@pxref{Pretty Printing}). | |
706 | ||
707 | @item (ice-9 q) | |
708 | First-in first-out queues (@pxref{Queues}). | |
709 | ||
07d83abe MV |
710 | @item (ice-9 rdelim) |
711 | Line- and character-delimited input (@pxref{Line/Delimited}). | |
712 | ||
54a3c992 KR |
713 | @item (ice-9 readline) |
714 | @code{readline} interactive command line editing (@pxref{Readline | |
715 | Support}). | |
716 | ||
717 | @item (ice-9 receive) | |
718 | Multiple-value handling with @code{receive} (@pxref{Multiple Values}). | |
719 | ||
720 | @item (ice-9 regex) | |
721 | Regular expression matching (@pxref{Regular Expressions}). | |
722 | ||
07d83abe MV |
723 | @item (ice-9 rw) |
724 | Block string input/output (@pxref{Block Reading and Writing}). | |
725 | ||
54a3c992 KR |
726 | @item (ice-9 streams) |
727 | Sequence of values calculated on-demand (@pxref{Streams}). | |
728 | ||
729 | @item (ice-9 syncase) | |
730 | R5RS @code{syntax-rules} macro system (@pxref{Syntax Rules}). | |
731 | ||
aca55ba9 KR |
732 | @item (ice-9 threads) |
733 | Guile's support for multi threaded execution (@pxref{Scheduling}). | |
734 | ||
07d83abe MV |
735 | @item (ice-9 documentation) |
736 | Online documentation (REFFIXME). | |
737 | ||
738 | @item (srfi srfi-1) | |
739 | A library providing a lot of useful list and pair processing | |
740 | procedures (@pxref{SRFI-1}). | |
741 | ||
742 | @item (srfi srfi-2) | |
743 | Support for @code{and-let*} (@pxref{SRFI-2}). | |
744 | ||
745 | @item (srfi srfi-4) | |
746 | Support for homogeneous numeric vectors (@pxref{SRFI-4}). | |
747 | ||
748 | @item (srfi srfi-6) | |
749 | Support for some additional string port procedures (@pxref{SRFI-6}). | |
750 | ||
751 | @item (srfi srfi-8) | |
752 | Multiple-value handling with @code{receive} (@pxref{SRFI-8}). | |
753 | ||
754 | @item (srfi srfi-9) | |
755 | Record definition with @code{define-record-type} (@pxref{SRFI-9}). | |
756 | ||
757 | @item (srfi srfi-10) | |
758 | Read hash extension @code{#,()} (@pxref{SRFI-10}). | |
759 | ||
760 | @item (srfi srfi-11) | |
cdc4f3db | 761 | Multiple-value handling with @code{let-values} and @code{let*-values} |
07d83abe MV |
762 | (@pxref{SRFI-11}). |
763 | ||
764 | @item (srfi srfi-13) | |
765 | String library (@pxref{SRFI-13}). | |
766 | ||
767 | @item (srfi srfi-14) | |
768 | Character-set library (@pxref{SRFI-14}). | |
769 | ||
e376f9e5 KR |
770 | @item (srfi srfi-16) |
771 | @code{case-lambda} procedures of variable arity (@pxref{SRFI-16}). | |
772 | ||
07d83abe MV |
773 | @item (srfi srfi-17) |
774 | Getter-with-setter support (@pxref{SRFI-17}). | |
775 | ||
e376f9e5 KR |
776 | @item (srfi srfi-19) |
777 | Time/Date library (@pxref{SRFI-19}). | |
778 | ||
07d83abe MV |
779 | @item (srfi srfi-26) |
780 | Convenient syntax for partial application (@pxref{SRFI-26}) | |
781 | ||
e376f9e5 KR |
782 | @item (srfi srfi-31) |
783 | @code{rec} convenient recursive expressions (@pxref{SRFI-31}) | |
784 | ||
07d83abe MV |
785 | @item (ice-9 slib) |
786 | This module contains hooks for using Aubrey Jaffer's portable Scheme | |
787 | library SLIB from Guile (@pxref{SLIB}). | |
07d83abe MV |
788 | @end table |
789 | ||
790 | ||
791 | @node Accessing Modules from C | |
792 | @subsubsection Accessing Modules from C | |
793 | ||
794 | The last sections have described how modules are used in Scheme code, | |
795 | which is the recommended way of creating and accessing modules. You | |
796 | can also work with modules from C, but it is more cumbersome. | |
797 | ||
798 | The following procedures are available. | |
799 | ||
800 | @deftypefn {C Procedure} SCM scm_current_module () | |
801 | Return the module that is the @emph{current module}. | |
802 | @end deftypefn | |
803 | ||
804 | @deftypefn {C Procedure} SCM scm_set_current_module (SCM @var{module}) | |
805 | Set the current module to @var{module} and return the previous current | |
806 | module. | |
807 | @end deftypefn | |
808 | ||
809 | @deftypefn {C Procedure} SCM scm_c_call_with_current_module (SCM @var{module}, SCM (*@var{func})(void *), void *@var{data}) | |
810 | Call @var{func} and make @var{module} the current module during the | |
811 | call. The argument @var{data} is passed to @var{func}. The return | |
812 | value of @code{scm_c_call_with_current_module} is the return value of | |
813 | @var{func}. | |
814 | @end deftypefn | |
815 | ||
816 | @deftypefn {C Procedure} SCM scm_c_lookup (const char *@var{name}) | |
817 | Return the variable bound to the symbol indicated by @var{name} in the | |
818 | current module. If there is no such binding or the symbol is not | |
819 | bound to a variable, signal an error. | |
820 | @end deftypefn | |
821 | ||
822 | @deftypefn {C Procedure} SCM scm_lookup (SCM @var{name}) | |
823 | Like @code{scm_c_lookup}, but the symbol is specified directly. | |
824 | @end deftypefn | |
825 | ||
826 | @deftypefn {C Procedure} SCM scm_c_module_lookup (SCM @var{module}, const char *@var{name}) | |
827 | @deftypefnx {C Procedure} SCM scm_module_lookup (SCM @var{module}, SCM @var{name}) | |
828 | Like @code{scm_c_lookup} and @code{scm_lookup}, but the specified | |
829 | module is used instead of the current one. | |
830 | @end deftypefn | |
831 | ||
832 | @deftypefn {C Procedure} SCM scm_c_define (const char *@var{name}, SCM @var{val}) | |
833 | Bind the symbol indicated by @var{name} to a variable in the current | |
834 | module and set that variable to @var{val}. When @var{name} is already | |
835 | bound to a variable, use that. Else create a new variable. | |
836 | @end deftypefn | |
837 | ||
838 | @deftypefn {C Procedure} SCM scm_define (SCM @var{name}, SCM @var{val}) | |
839 | Like @code{scm_c_define}, but the symbol is specified directly. | |
840 | @end deftypefn | |
841 | ||
842 | @deftypefn {C Procedure} SCM scm_c_module_define (SCM @var{module}, const char *@var{name}, SCM @var{val}) | |
843 | @deftypefnx {C Procedure} SCM scm_module_define (SCM @var{module}, SCM @var{name}, SCM @var{val}) | |
844 | Like @code{scm_c_define} and @code{scm_define}, but the specified | |
845 | module is used instead of the current one. | |
846 | @end deftypefn | |
847 | ||
848 | @deftypefn {C Procedure} SCM scm_module_reverse_lookup (SCM @var{module}, SCM @var{variable}) | |
849 | Find the symbol that is bound to @var{variable} in @var{module}. When no such binding is found, return @var{#f}. | |
850 | @end deftypefn | |
851 | ||
852 | @deftypefn {C Procedure} SCM scm_c_define_module (const char *@var{name}, void (*@var{init})(void *), void *@var{data}) | |
853 | Define a new module named @var{name} and make it current while | |
854 | @var{init} is called, passing it @var{data}. Return the module. | |
855 | ||
856 | The parameter @var{name} is a string with the symbols that make up | |
857 | the module name, separated by spaces. For example, @samp{"foo bar"} names | |
858 | the module @samp{(foo bar)}. | |
859 | ||
860 | When there already exists a module named @var{name}, it is used | |
861 | unchanged, otherwise, an empty module is created. | |
862 | @end deftypefn | |
863 | ||
864 | @deftypefn {C Procedure} SCM scm_c_resolve_module (const char *@var{name}) | |
865 | Find the module name @var{name} and return it. When it has not | |
866 | already been defined, try to auto-load it. When it can't be found | |
867 | that way either, create an empty module. The name is interpreted as | |
868 | for @code{scm_c_define_module}. | |
869 | @end deftypefn | |
870 | ||
871 | @deftypefn {C Procedure} SCM scm_resolve_module (SCM @var{name}) | |
872 | Like @code{scm_c_resolve_module}, but the name is given as a real list | |
873 | of symbols. | |
874 | @end deftypefn | |
875 | ||
876 | @deftypefn {C Procedure} SCM scm_c_use_module (const char *@var{name}) | |
877 | Add the module named @var{name} to the uses list of the current | |
878 | module, as with @code{(use-modules @var{name})}. The name is | |
879 | interpreted as for @code{scm_c_define_module}. | |
880 | @end deftypefn | |
881 | ||
882 | @deftypefn {C Procedure} SCM scm_c_export (const char *@var{name}, ...) | |
883 | Add the bindings designated by @var{name}, ... to the public interface | |
884 | of the current module. The list of names is terminated by | |
885 | @code{NULL}. | |
886 | @end deftypefn | |
887 | ||
888 | @node Dynamic Libraries | |
889 | @subsection Dynamic Libraries | |
890 | ||
891 | Most modern Unices have something called @dfn{shared libraries}. This | |
892 | ordinarily means that they have the capability to share the executable | |
893 | image of a library between several running programs to save memory and | |
894 | disk space. But generally, shared libraries give a lot of additional | |
895 | flexibility compared to the traditional static libraries. In fact, | |
896 | calling them `dynamic' libraries is as correct as calling them `shared'. | |
897 | ||
898 | Shared libraries really give you a lot of flexibility in addition to the | |
899 | memory and disk space savings. When you link a program against a shared | |
900 | library, that library is not closely incorporated into the final | |
901 | executable. Instead, the executable of your program only contains | |
902 | enough information to find the needed shared libraries when the program | |
903 | is actually run. Only then, when the program is starting, is the final | |
904 | step of the linking process performed. This means that you need not | |
905 | recompile all programs when you install a new, only slightly modified | |
906 | version of a shared library. The programs will pick up the changes | |
907 | automatically the next time they are run. | |
908 | ||
909 | Now, when all the necessary machinery is there to perform part of the | |
910 | linking at run-time, why not take the next step and allow the programmer | |
911 | to explicitly take advantage of it from within his program? Of course, | |
912 | many operating systems that support shared libraries do just that, and | |
913 | chances are that Guile will allow you to access this feature from within | |
914 | your Scheme programs. As you might have guessed already, this feature | |
915 | is called @dfn{dynamic linking}.@footnote{Some people also refer to the | |
916 | final linking stage at program startup as `dynamic linking', so if you | |
917 | want to make yourself perfectly clear, it is probably best to use the | |
918 | more technical term @dfn{dlopening}, as suggested by Gordon Matzigkeit | |
919 | in his libtool documentation.} | |
920 | ||
921 | As with many aspects of Guile, there is a low-level way to access the | |
922 | dynamic linking apparatus, and a more high-level interface that | |
923 | integrates dynamically linked libraries into the module system. | |
924 | ||
925 | @menu | |
ef5f9163 KR |
926 | * Low level dynamic linking:: |
927 | * Compiled Code Modules:: | |
928 | * Dynamic Linking and Compiled Code Modules:: | |
929 | * Compiled Code Installation:: | |
07d83abe MV |
930 | @end menu |
931 | ||
932 | @node Low level dynamic linking | |
933 | @subsubsection Low level dynamic linking | |
934 | ||
935 | When using the low level procedures to do your dynamic linking, you have | |
936 | complete control over which library is loaded when and what gets done | |
937 | with it. | |
938 | ||
939 | @deffn {Scheme Procedure} dynamic-link library | |
940 | @deffnx {C Function} scm_dynamic_link (library) | |
941 | Find the shared library denoted by @var{library} (a string) and link it | |
942 | into the running Guile application. When everything works out, return a | |
943 | Scheme object suitable for representing the linked object file. | |
944 | Otherwise an error is thrown. How object files are searched is system | |
945 | dependent. | |
946 | ||
947 | Normally, @var{library} is just the name of some shared library file | |
948 | that will be searched for in the places where shared libraries usually | |
949 | reside, such as in @file{/usr/lib} and @file{/usr/local/lib}. | |
950 | @end deffn | |
951 | ||
952 | @deffn {Scheme Procedure} dynamic-object? obj | |
953 | @deffnx {C Function} scm_dynamic_object_p (obj) | |
954 | Return @code{#t} if @var{obj} is a dynamic library handle, or @code{#f} | |
955 | otherwise. | |
956 | @end deffn | |
957 | ||
958 | @deffn {Scheme Procedure} dynamic-unlink dobj | |
959 | @deffnx {C Function} scm_dynamic_unlink (dobj) | |
960 | Unlink the indicated object file from the application. The | |
961 | argument @var{dobj} must have been obtained by a call to | |
962 | @code{dynamic-link}. After @code{dynamic-unlink} has been | |
963 | called on @var{dobj}, its content is no longer accessible. | |
964 | @end deffn | |
965 | ||
966 | @deffn {Scheme Procedure} dynamic-func name dobj | |
967 | @deffnx {C Function} scm_dynamic_func (name, dobj) | |
968 | Search the dynamic object @var{dobj} for the C function | |
969 | indicated by the string @var{name} and return some Scheme | |
970 | handle that can later be used with @code{dynamic-call} to | |
971 | actually call the function. | |
972 | ||
973 | Regardless whether your C compiler prepends an underscore @samp{_} to | |
974 | the global names in a program, you should @strong{not} include this | |
975 | underscore in @var{function}. Guile knows whether the underscore is | |
976 | needed or not and will add it when necessary. | |
977 | @end deffn | |
978 | ||
979 | @deffn {Scheme Procedure} dynamic-call func dobj | |
980 | @deffnx {C Function} scm_dynamic_call (func, dobj) | |
981 | Call the C function indicated by @var{func} and @var{dobj}. | |
982 | The function is passed no arguments and its return value is | |
983 | ignored. When @var{function} is something returned by | |
984 | @code{dynamic-func}, call that function and ignore @var{dobj}. | |
985 | When @var{func} is a string , look it up in @var{dynobj}; this | |
986 | is equivalent to | |
987 | @smallexample | |
988 | (dynamic-call (dynamic-func @var{func} @var{dobj}) #f) | |
989 | @end smallexample | |
990 | ||
991 | Interrupts are deferred while the C function is executing (with | |
992 | @code{SCM_DEFER_INTS}/@code{SCM_ALLOW_INTS}). | |
993 | @end deffn | |
994 | ||
995 | @deffn {Scheme Procedure} dynamic-args-call func dobj args | |
996 | @deffnx {C Function} scm_dynamic_args_call (func, dobj, args) | |
997 | Call the C function indicated by @var{func} and @var{dobj}, | |
998 | just like @code{dynamic-call}, but pass it some arguments and | |
999 | return its return value. The C function is expected to take | |
1000 | two arguments and return an @code{int}, just like @code{main}: | |
1001 | @smallexample | |
1002 | int c_func (int argc, char **argv); | |
1003 | @end smallexample | |
1004 | ||
1005 | The parameter @var{args} must be a list of strings and is | |
1006 | converted into an array of @code{char *}. The array is passed | |
1007 | in @var{argv} and its size in @var{argc}. The return value is | |
1008 | converted to a Scheme number and returned from the call to | |
1009 | @code{dynamic-args-call}. | |
1010 | @end deffn | |
1011 | ||
1012 | When dynamic linking is disabled or not supported on your system, | |
1013 | the above functions throw errors, but they are still available. | |
1014 | ||
1015 | Here is a small example that works on GNU/Linux: | |
1016 | ||
1017 | @smallexample | |
1018 | (define libc-obj (dynamic-link "libc.so")) | |
1019 | libc-obj | |
1020 | @result{} #<dynamic-object "libc.so"> | |
1021 | (dynamic-args-call 'rand libc-obj '()) | |
1022 | @result{} 269167349 | |
1023 | (dynamic-unlink libc-obj) | |
1024 | libc-obj | |
1025 | @result{} #<dynamic-object "libc.so" (unlinked)> | |
1026 | @end smallexample | |
1027 | ||
1028 | As you can see, after calling @code{dynamic-unlink} on a dynamically | |
1029 | linked library, it is marked as @samp{(unlinked)} and you are no longer | |
1030 | able to use it with @code{dynamic-call}, etc. Whether the library is | |
1031 | really removed from you program is system-dependent and will generally | |
1032 | not happen when some other parts of your program still use it. In the | |
1033 | example above, @code{libc} is almost certainly not removed from your | |
1034 | program because it is badly needed by almost everything. | |
1035 | ||
1036 | The functions to call a function from a dynamically linked library, | |
1037 | @code{dynamic-call} and @code{dynamic-args-call}, are not very powerful. | |
1038 | They are mostly intended to be used for calling specially written | |
1039 | initialization functions that will then add new primitives to Guile. | |
1040 | For example, we do not expect that you will dynamically link | |
1041 | @file{libX11} with @code{dynamic-link} and then construct a beautiful | |
1042 | graphical user interface just by using @code{dynamic-call} and | |
1043 | @code{dynamic-args-call}. Instead, the usual way would be to write a | |
1044 | special Guile<->X11 glue library that has intimate knowledge about both | |
1045 | Guile and X11 and does whatever is necessary to make them inter-operate | |
1046 | smoothly. This glue library could then be dynamically linked into a | |
1047 | vanilla Guile interpreter and activated by calling its initialization | |
1048 | function. That function would add all the new types and primitives to | |
1049 | the Guile interpreter that it has to offer. | |
1050 | ||
1051 | From this setup the next logical step is to integrate these glue | |
1052 | libraries into the module system of Guile so that you can load new | |
1053 | primitives into a running system just as you can load new Scheme code. | |
1054 | ||
1055 | There is, however, another possibility to get a more thorough access to | |
1056 | the functions contained in a dynamically linked library. Anthony Green | |
1057 | has written @file{libffi}, a library that implements a @dfn{foreign | |
1058 | function interface} for a number of different platforms. With it, you | |
1059 | can extend the Spartan functionality of @code{dynamic-call} and | |
1060 | @code{dynamic-args-call} considerably. There is glue code available in | |
1061 | the Guile contrib archive to make @file{libffi} accessible from Guile. | |
1062 | ||
1063 | @node Compiled Code Modules | |
1064 | @subsubsection Putting Compiled Code into Modules | |
1065 | ||
1066 | The new primitives that you add to Guile with | |
1067 | @code{scm_c_define_gsubr} (@pxref{Primitive Procedures}) or with any | |
1068 | of the other mechanisms are placed into the @code{(guile-user)} module | |
1069 | by default. However, it is also possible to put new primitives into | |
1070 | other modules. | |
1071 | ||
1072 | The mechanism for doing so is not very well thought out and is likely to | |
1073 | change when the module system of Guile itself is revised, but it is | |
1074 | simple and useful enough to document it as it stands. | |
1075 | ||
1076 | What @code{scm_c_define_gsubr} and the functions used by the snarfer | |
1077 | really do is to add the new primitives to whatever module is the | |
1078 | @emph{current module} when they are called. This is analogous to the | |
1079 | way Scheme code is put into modules: the @code{define-module} expression | |
1080 | at the top of a Scheme source file creates a new module and makes it the | |
1081 | current module while the rest of the file is evaluated. The | |
1082 | @code{define} expressions in that file then add their new definitions to | |
1083 | this current module. | |
1084 | ||
1085 | Therefore, all we need to do is to make sure that the right module is | |
1086 | current when calling @code{scm_c_define_gsubr} for our new primitives. | |
1087 | ||
1088 | @node Dynamic Linking and Compiled Code Modules | |
1089 | @subsubsection Dynamic Linking and Compiled Code Modules | |
1090 | ||
1091 | The most interesting application of dynamically linked libraries is | |
1092 | probably to use them for providing @emph{compiled code modules} to | |
1093 | Scheme programs. As much fun as programming in Scheme is, every now and | |
1094 | then comes the need to write some low-level C stuff to make Scheme even | |
1095 | more fun. | |
1096 | ||
1097 | Not only can you put these new primitives into their own module (see the | |
1098 | previous section), you can even put them into a shared library that is | |
1099 | only then linked to your running Guile image when it is actually | |
1100 | needed. | |
1101 | ||
1102 | An example will hopefully make everything clear. Suppose we want to | |
1103 | make the Bessel functions of the C library available to Scheme in the | |
1104 | module @samp{(math bessel)}. First we need to write the appropriate | |
1105 | glue code to convert the arguments and return values of the functions | |
1106 | from Scheme to C and back. Additionally, we need a function that will | |
1107 | add them to the set of Guile primitives. Because this is just an | |
1108 | example, we will only implement this for the @code{j0} function. | |
1109 | ||
1110 | @c FIXME::martin: Change all gh_ references to their scm_ equivalents. | |
1111 | ||
1112 | @smallexample | |
1113 | #include <math.h> | |
1114 | #include <libguile.h> | |
1115 | ||
1116 | SCM | |
1117 | j0_wrapper (SCM x) | |
1118 | @{ | |
1119 | return scm_double2num (j0 (scm_num2dbl (x, "j0"))); | |
1120 | @} | |
1121 | ||
1122 | void | |
1123 | init_math_bessel () | |
1124 | @{ | |
1125 | scm_c_define_gsubr ("j0", 1, 0, 0, j0_wrapper); | |
1126 | @} | |
1127 | @end smallexample | |
1128 | ||
1129 | We can already try to bring this into action by manually calling the low | |
1130 | level functions for performing dynamic linking. The C source file needs | |
1131 | to be compiled into a shared library. Here is how to do it on | |
1132 | GNU/Linux, please refer to the @code{libtool} documentation for how to | |
1133 | create dynamically linkable libraries portably. | |
1134 | ||
1135 | @smallexample | |
1136 | gcc -shared -o libbessel.so -fPIC bessel.c | |
1137 | @end smallexample | |
1138 | ||
1139 | Now fire up Guile: | |
1140 | ||
aba0dff5 | 1141 | @lisp |
07d83abe MV |
1142 | (define bessel-lib (dynamic-link "./libbessel.so")) |
1143 | (dynamic-call "init_math_bessel" bessel-lib) | |
1144 | (j0 2) | |
1145 | @result{} 0.223890779141236 | |
aba0dff5 | 1146 | @end lisp |
07d83abe MV |
1147 | |
1148 | The filename @file{./libbessel.so} should be pointing to the shared | |
1149 | library produced with the @code{gcc} command above, of course. The | |
1150 | second line of the Guile interaction will call the | |
1151 | @code{init_math_bessel} function which in turn will register the C | |
1152 | function @code{j0_wrapper} with the Guile interpreter under the name | |
1153 | @code{j0}. This function becomes immediately available and we can call | |
1154 | it from Scheme. | |
1155 | ||
1156 | Fun, isn't it? But we are only half way there. This is what | |
1157 | @code{apropos} has to say about @code{j0}: | |
1158 | ||
1159 | @smallexample | |
1160 | (apropos "j0") | |
1161 | @print{} (guile-user): j0 #<primitive-procedure j0> | |
1162 | @end smallexample | |
1163 | ||
1164 | As you can see, @code{j0} is contained in the root module, where all | |
1165 | the other Guile primitives like @code{display}, etc live. In general, | |
1166 | a primitive is put into whatever module is the @dfn{current module} at | |
1167 | the time @code{scm_c_define_gsubr} is called. | |
1168 | ||
1169 | A compiled module should have a specially named @dfn{module init | |
1170 | function}. Guile knows about this special name and will call that | |
1171 | function automatically after having linked in the shared library. For | |
1172 | our example, we replace @code{init_math_bessel} with the following code in | |
1173 | @file{bessel.c}: | |
1174 | ||
1175 | @smallexample | |
1176 | void | |
1177 | init_math_bessel (void *unused) | |
1178 | @{ | |
1179 | scm_c_define_gsubr ("j0", 1, 0, 0, j0_wrapper); | |
1180 | scm_c_export ("j0", NULL); | |
1181 | @} | |
1182 | ||
1183 | void | |
1184 | scm_init_math_bessel_module () | |
1185 | @{ | |
1186 | scm_c_define_module ("math bessel", init_math_bessel, NULL); | |
1187 | @} | |
1188 | @end smallexample | |
1189 | ||
1190 | The general pattern for the name of a module init function is: | |
1191 | @samp{scm_init_}, followed by the name of the module where the | |
1192 | individual hierarchical components are concatenated with underscores, | |
1193 | followed by @samp{_module}. | |
1194 | ||
1195 | After @file{libbessel.so} has been rebuilt, we need to place the shared | |
1196 | library into the right place. | |
1197 | ||
1198 | Once the module has been correctly installed, it should be possible to | |
1199 | use it like this: | |
1200 | ||
1201 | @smallexample | |
1202 | guile> (load-extension "./libbessel.so" "scm_init_math_bessel_module") | |
1203 | guile> (use-modules (math bessel)) | |
1204 | guile> (j0 2) | |
1205 | 0.223890779141236 | |
1206 | guile> (apropos "j0") | |
1207 | @print{} (math bessel): j0 #<primitive-procedure j0> | |
1208 | @end smallexample | |
1209 | ||
1210 | That's it! | |
1211 | ||
cdf1ad3b MV |
1212 | @deffn {Scheme Procedure} load-extension lib init |
1213 | @deffnx {C Function} scm_load_extension (lib, init) | |
1214 | Load and initialize the extension designated by LIB and INIT. | |
1215 | When there is no pre-registered function for LIB/INIT, this is | |
1216 | equivalent to | |
1217 | ||
1218 | @lisp | |
1219 | (dynamic-call INIT (dynamic-link LIB)) | |
1220 | @end lisp | |
1221 | ||
1222 | When there is a pre-registered function, that function is called | |
1223 | instead. | |
1224 | ||
1225 | Normally, there is no pre-registered function. This option exists | |
1226 | only for situations where dynamic linking is unavailable or unwanted. | |
1227 | In that case, you would statically link your program with the desired | |
1228 | library, and register its init function right after Guile has been | |
1229 | initialized. | |
1230 | ||
1231 | LIB should be a string denoting a shared library without any file type | |
1232 | suffix such as ".so". The suffix is provided automatically. It | |
1233 | should also not contain any directory components. Libraries that | |
1234 | implement Guile Extensions should be put into the normal locations for | |
1235 | shared libraries. We recommend to use the naming convention | |
1236 | libguile-bla-blum for a extension related to a module `(bla blum)'. | |
1237 | ||
1238 | The normal way for a extension to be used is to write a small Scheme | |
1239 | file that defines a module, and to load the extension into this | |
1240 | module. When the module is auto-loaded, the extension is loaded as | |
1241 | well. For example, | |
1242 | ||
1243 | @lisp | |
1244 | (define-module (bla blum)) | |
1245 | ||
1246 | (load-extension "libguile-bla-blum" "bla_init_blum") | |
1247 | @end lisp | |
1248 | @end deffn | |
1249 | ||
ef5f9163 KR |
1250 | |
1251 | @node Compiled Code Installation | |
1252 | @subsubsection Compiled Code Installation | |
1253 | ||
1254 | The simplest way to write a module using compiled C code is | |
1255 | ||
1256 | @example | |
1257 | (define-module (foo bar)) | |
1258 | (load-extension "foobar-c-code" "foo_bar_init") | |
1259 | @end example | |
1260 | ||
1261 | When loaded with @code{(use-modules (foo bar))}, the | |
1b09b607 | 1262 | @code{load-extension} call looks for the @file{foobar-c-code.so} (etc) |
ef5f9163 KR |
1263 | object file in the standard system locations, such as @file{/usr/lib} |
1264 | or @file{/usr/local/lib}. | |
1265 | ||
1266 | If someone installs your module to a non-standard location then the | |
1267 | object file won't be found. You can address this by inserting the | |
1268 | install location in the @file{foo/bar.scm} file. This is convenient | |
1b09b607 KR |
1269 | for the user and also guarantees the intended object is read, even if |
1270 | stray older or newer versions are in the loader's path. | |
ef5f9163 KR |
1271 | |
1272 | The usual way to specify an install location is with a @code{prefix} | |
1273 | at the configure stage, for instance @samp{./configure prefix=/opt} | |
1b09b607 KR |
1274 | results in library files as say @file{/opt/lib/foobar-c-code.so}. |
1275 | When using Autoconf (@pxref{Top, , Introduction, autoconf, The GNU | |
1276 | Autoconf Manual}), the library location is in a @code{libdir} | |
1277 | variable. Its value is intended to be expanded by @command{make}, and | |
1278 | can by substituted into a source file like @file{foo.scm.in} | |
ef5f9163 KR |
1279 | |
1280 | @example | |
1281 | (define-module (foo bar)) | |
1b09b607 | 1282 | (load-extension "XXlibdirXX/foobar-c-code" "foo_bar_init") |
ef5f9163 KR |
1283 | @end example |
1284 | ||
1b09b607 KR |
1285 | @noindent |
1286 | with the following in a @file{Makefile}, using @command{sed} | |
1287 | (@pxref{Top, , Introduction, sed, SED, A Stream Editor}), | |
ef5f9163 | 1288 | |
1b09b607 KR |
1289 | @example |
1290 | foo.scm: foo.scm.in | |
1291 | sed 's|XXlibdirXX|$(libdir)|' <foo.scm.in >foo.scm | |
1292 | @end example | |
1293 | ||
1294 | The actual pattern @code{XXlibdirXX} is arbitrary, it's only something | |
1295 | which doesn't otherwise occur. If several modules need the value, it | |
1296 | can be easier to create one @file{foo/config.scm} with a define of the | |
1297 | @code{libdir} location, and use that as required. | |
ef5f9163 KR |
1298 | |
1299 | @example | |
1300 | (define-module (foo config)) | |
1b09b607 | 1301 | (define-public foo-config-libdir "XXlibdirXX"") |
ef5f9163 KR |
1302 | @end example |
1303 | ||
1b09b607 KR |
1304 | Such a file might have other locations too, for instance a data |
1305 | directory for auxiliary files, or @code{localedir} if the module has | |
1306 | its own @code{gettext} message catalogue | |
ef5f9163 KR |
1307 | (@pxref{Internationalization}). |
1308 | ||
1309 | When installing multiple C code objects, it can be convenient to put | |
1310 | them in a subdirectory of @code{libdir}, thus giving for example | |
1311 | @code{/usr/lib/foo/some-obj.so}. If the objects are only meant to be | |
1312 | used through the module, then a subdirectory keeps them out of sight. | |
1313 | ||
1b09b607 KR |
1314 | It will be noted all of the above requires that the Scheme code to be |
1315 | found in @code{%load-path} (@pxref{Build Config}). Presently it's | |
1316 | left up to the system administrator or each user to augment that path | |
1317 | when installing Guile modules in non-default locations. But having | |
1318 | reached the Scheme code, that code should take care of hitting any of | |
1319 | its own private files etc. | |
ef5f9163 | 1320 | |
ef5f9163 KR |
1321 | Presently there's no convention for having a Guile version number in |
1322 | module C code filenames or directories. This is primarily because | |
1323 | there's no established principles for two versions of Guile to be | |
1324 | installed under the same prefix (eg. two both under @file{/usr}). | |
1325 | Assuming upward compatibility is maintained then this should be | |
1326 | unnecessary, and if compatibility is not maintained then it's highly | |
1327 | likely a package will need to be revisited anyway. | |
1328 | ||
1329 | The present suggestion is that modules should assume when they're | |
1330 | installed under a particular @code{prefix} that there's a single | |
1331 | version of Guile there, and the @code{guile-config} at build time has | |
1332 | the necessary information about it. C code or Scheme code might adapt | |
1333 | itself accordingly (allowing for features not available in an older | |
1334 | version for instance). | |
1335 | ||
1336 | ||
07d83abe MV |
1337 | @node Variables |
1338 | @subsection Variables | |
1339 | @tpindex Variables | |
1340 | ||
1341 | Each module has its own hash table, sometimes known as an @dfn{obarray}, | |
1342 | that maps the names defined in that module to their corresponding | |
1343 | variable objects. | |
1344 | ||
1345 | A variable is a box-like object that can hold any Scheme value. It is | |
1346 | said to be @dfn{undefined} if its box holds a special Scheme value that | |
1347 | denotes undefined-ness (which is different from all other Scheme values, | |
1348 | including for example @code{#f}); otherwise the variable is | |
1349 | @dfn{defined}. | |
1350 | ||
1351 | On its own, a variable object is anonymous. A variable is said to be | |
1352 | @dfn{bound} when it is associated with a name in some way, usually a | |
1353 | symbol in a module obarray. When this happens, the relationship is | |
1354 | mutual: the variable is bound to the name (in that module), and the name | |
1355 | (in that module) is bound to the variable. | |
1356 | ||
1357 | (That's the theory, anyway. In practice, defined-ness and bound-ness | |
1358 | sometimes get confused, because Lisp and Scheme implementations have | |
1359 | often conflated --- or deliberately drawn no distinction between --- a | |
1360 | name that is unbound and a name that is bound to a variable whose value | |
1361 | is undefined. We will try to be clear about the difference and explain | |
1362 | any confusion where it is unavoidable.) | |
1363 | ||
1364 | Variables do not have a read syntax. Most commonly they are created and | |
1365 | bound implicitly by @code{define} expressions: a top-level @code{define} | |
1366 | expression of the form | |
1367 | ||
1368 | @lisp | |
1369 | (define @var{name} @var{value}) | |
1370 | @end lisp | |
1371 | ||
1372 | @noindent | |
1373 | creates a variable with initial value @var{value} and binds it to the | |
1374 | name @var{name} in the current module. But they can also be created | |
1375 | dynamically by calling one of the constructor procedures | |
1376 | @code{make-variable} and @code{make-undefined-variable}. | |
1377 | ||
1378 | First-class variables are especially useful for interacting with the | |
1379 | current module system (@pxref{The Guile module system}). | |
1380 | ||
1381 | @deffn {Scheme Procedure} make-undefined-variable | |
1382 | @deffnx {C Function} scm_make_undefined_variable () | |
1383 | Return a variable that is initially unbound. | |
1384 | @end deffn | |
1385 | ||
1386 | @deffn {Scheme Procedure} make-variable init | |
1387 | @deffnx {C Function} scm_make_variable (init) | |
1388 | Return a variable initialized to value @var{init}. | |
1389 | @end deffn | |
1390 | ||
1391 | @deffn {Scheme Procedure} variable-bound? var | |
1392 | @deffnx {C Function} scm_variable_bound_p (var) | |
1393 | Return @code{#t} iff @var{var} is bound to a value. | |
1394 | Throws an error if @var{var} is not a variable object. | |
1395 | @end deffn | |
1396 | ||
1397 | @deffn {Scheme Procedure} variable-ref var | |
1398 | @deffnx {C Function} scm_variable_ref (var) | |
1399 | Dereference @var{var} and return its value. | |
1400 | @var{var} must be a variable object; see @code{make-variable} | |
1401 | and @code{make-undefined-variable}. | |
1402 | @end deffn | |
1403 | ||
1404 | @deffn {Scheme Procedure} variable-set! var val | |
1405 | @deffnx {C Function} scm_variable_set_x (var, val) | |
1406 | Set the value of the variable @var{var} to @var{val}. | |
1407 | @var{var} must be a variable object, @var{val} can be any | |
1408 | value. Return an unspecified value. | |
1409 | @end deffn | |
1410 | ||
1411 | @deffn {Scheme Procedure} variable? obj | |
1412 | @deffnx {C Function} scm_variable_p (obj) | |
1413 | Return @code{#t} iff @var{obj} is a variable object, else | |
1414 | return @code{#f}. | |
1415 | @end deffn | |
1416 | ||
1417 | ||
1418 | @c Local Variables: | |
1419 | @c TeX-master: "guile.texi" | |
1420 | @c End: |