2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004
4 @c Free Software Foundation, Inc.
5 @c See the file guile.texi for copying conditions.
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.
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.
22 @cindex information encapsulation
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).
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.
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
41 In addition, Guile offers variables as first-class objects. They can
42 be used for interacting with the module system.
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.
52 @node provide and require
53 @subsection provide and require
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.
60 For example, the file @file{random.scm} in the SLIB package contains the
67 so to use its procedures, a user would type
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
77 When SLIB is used with Guile, provide and require can be used to access
81 @subsection Environments
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}.
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
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}.
99 Note: the following two procedures are available only when the
100 @code{(ice-9 r5rs)} module is loaded:
103 (use-modules (ice-9 r5rs))
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.
118 Currently Guile does not support values of @var{version} for other
119 revisions of the report.
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.
127 @node The Guile module system
128 @subsection The Guile module system
130 The Guile module system extends the concept of environments, discussed
131 in the previous section, with mechanisms to define, use and customise
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
136 been available since at least Guile version 1.1.
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
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.
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.
152 * Module System Reflection:: Accessing module objects at run-time.
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.
158 @node General Information about Modules
159 @subsubsection General Information about Modules
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.
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
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
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}).
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
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}).
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.
211 @node Using Guile Modules
212 @subsubsection Using Guile Modules
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
220 that code has not yet been loaded, following @code{%load-path} (@pxref{Build
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:
228 (use-modules (ice-9 popen))
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
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:
243 @cindex binding renamer
245 (use-modules ((ice-9 popen)
246 :select ((open-pipe . pipe-open) close-pipe)
247 :renamer (symbol-prefix-proc 'unixy:)))
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
255 @c Use `smallexample' since `table' is ugly. --ttn
257 (ice-9 popen) sees: current module sees:
258 open-pipe unixy:pipe-open
259 close-pipe unixy:close-pipe
262 This example also shows how to use the convenience procedure
263 @code{symbol-prefix-proc}.
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}
274 (define unixy:pipe-open (@@ (ice-9 popen) open-pipe))
275 (define unixy:close-pipe (@@ (ice-9 popen) close-pipe))
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.
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.
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.
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
295 @c Insert gratuitous C++ slam here. --ttn
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.
304 @var{spec} can be a list of symbols, in which case it names a module
305 whose public interface is found and used.
307 @var{spec} can also be of the form:
309 @cindex binding renamer
311 (MODULE-NAME [:select SELECTION] [:renamer RENAMER])
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}.
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
327 Signal error if module name is not resolvable.
331 @c FIXME::martin: Is this correct, and is there more to say?
332 @c FIXME::martin: Define term and concept `system transformer' somewhere.
334 @deffn syntax use-syntax module-name
335 Load the module @code{module-name} and use its system
336 transformer as the system transformer for the currently defined module,
337 as well as installing it as the current system transformer.
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.
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
352 @node Creating Guile Modules
353 @subsubsection Creating Guile Modules
355 When you want to create your own modules, you have to take the following
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.
364 Add a @code{define-module} form at the beginning.
367 Export all bindings which should be in the public interface, either
368 by using @code{define-public} or @code{export} (both documented below).
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
377 (define-module (ice-9 popen))
380 @code{define-module} makes this module available to Guile programs under
381 the given @var{module-name}.
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
387 @c fixme: Should we use "#:" or ":"?
390 @item #:use-module @var{interface-specification}
391 Equivalent to a @code{(use-modules @var{interface-specification})}
392 (@pxref{Using Guile Modules}).
394 @item #:use-syntax @var{module}
395 Use @var{module} when loading the currently defined module, and install
396 it as the syntax transformer.
398 @item #:autoload @var{module} @var{symbol-list}
400 Load @var{module} when any of @var{symbol-list} are accessed. For
404 (define-module (my mod)
405 #:autoload (srfi srfi-1) (partition delete-duplicates))
408 (set! foo (delete-duplicates ...)))
411 When a module is autoloaded, all its bindings become available.
412 @var{symbol-list} is just those that will first trigger the load.
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.
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
422 @item #:export @var{list}
424 Export all identifiers in @var{list} which must be a list of symbols.
425 This is equivalent to @code{(export @var{list})} in the module body.
427 @item #:re-export @var{list}
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}
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.
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.
448 @item #:replace @var{list}
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.
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.
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
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}.
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.
483 The @code{#:duplicates} (see below) provides fine-grain control about
484 duplicate binding handling on the module-user side.
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:
497 Raises an error when a binding is imported from more than one place.
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.
503 When a new binding is imported that has the same name as a previously
504 imported binding, then do the following:
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.
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.
516 If neither the old nor the new binding is replacing, then keep the old
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.
524 In case of duplicate bindings, the firstly imported binding is always
525 the one which is kept.
527 In case of duplicate bindings, the lastly imported binding is always
528 the one which is kept.
530 In case of duplicate bindings, leave the responsibility to the next
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}.
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
545 (replace warn-override-core warn last)
550 Tell Guile not to record information for procedure backtraces when
551 executing the procedures in this module.
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.
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.
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))}.
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.
581 @node Module System Reflection
582 @subsubsection Module System Reflection
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.
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},
594 These module objects can be used as the second argument to @code{eval}.
596 @deffn {Scheme Procedure} current-module
597 Return the current module object.
600 @deffn {Scheme Procedure} set-current-module module
601 Set the current module to @var{module} and return
602 the previous current module.
605 @deffn {Scheme Procedure} resolve-module name
606 Find the module named @var{name} and return it. When it has not already
607 been defined, try to auto-load it. When it can't be found that way
608 either, create an empty module. The name is a list of symbols.
611 @deffn {Scheme Procedure} resolve-interface name
612 Find the module named @var{name} as with @code{resolve-module} and
613 return its interface. The interface of a module is also a module
614 object, but it contains only the exported bindings.
617 @deffn {Scheme Procedure} module-use! module interface
618 Add @var{interface} to the front of the use-list of @var{module}. Both
619 arguments should be module objects, and @var{interface} should very
620 likely be a module returned by @code{resolve-interface}.
623 @node Module System Quirks
624 @subsubsection Module System Quirks
626 Although the programming interfaces are relatively stable, the Guile
627 module system itself is still evolving. Here are some situations where
628 usage surpasses design.
633 When using a module which exports a macro definition, the other module
634 must export all bindings the macro expansion uses, too, because the
635 expanded code would otherwise not be able to see these definitions and
636 issue a ``variable unbound'' error, or worse, would use another binding
637 which might be present in the scope of the expansion.
640 When two or more used modules export bindings with the same names, the
641 last accessed module wins, and the exported binding of that last module
642 will silently be used. This might lead to hard-to-find errors because
643 wrong procedures or variables are used. To avoid this kind of
644 @dfn{name-clash} situation, use a custom interface specification
645 (@pxref{Using Guile Modules}). (We include this entry for the possible
646 benefit of users of Guile versions previous to 1.5.0, when custom
647 interfaces were added to the module system.)
650 [Add other quirks here.]
655 @node Included Guile Modules
656 @subsubsection Included Guile Modules
658 @c FIXME::martin: Review me!
660 Some modules are included in the Guile distribution; here are references
661 to the entries in this manual which describe them in more detail:
665 boot-9 is Guile's initialization module, and it is always loaded when
669 Mikael Djurfeldt's source-level debugging support for Guile
670 (@pxref{Debugging Features}).
673 Actions based on matching input from a port (@pxref{Expect}).
676 Formatted output in the style of Common Lisp (@pxref{Formatted
680 File tree walker (@pxref{File Tree Walk}).
682 @item (ice-9 getopt-long)
683 Command line option processing (@pxref{getopt-long}).
685 @item (ice-9 history)
686 Refer to previous interactive expressions (@pxref{Value History}).
689 Pipes to and from child processes (@pxref{Pipes}).
691 @item (ice-9 pretty-print)
692 Nicely formatted output of Scheme expressions and objects
693 (@pxref{Pretty Printing}).
696 First-in first-out queues (@pxref{Queues}).
699 Line- and character-delimited input (@pxref{Line/Delimited}).
701 @item (ice-9 readline)
702 @code{readline} interactive command line editing (@pxref{Readline
705 @item (ice-9 receive)
706 Multiple-value handling with @code{receive} (@pxref{Multiple Values}).
709 Regular expression matching (@pxref{Regular Expressions}).
712 Block string input/output (@pxref{Block Reading and Writing}).
714 @item (ice-9 streams)
715 Sequence of values calculated on-demand (@pxref{Streams}).
717 @item (ice-9 syncase)
718 R5RS @code{syntax-rules} macro system (@pxref{Syntax Rules}).
720 @item (ice-9 threads)
721 Guile's support for multi threaded execution (@pxref{Scheduling}).
723 @item (ice-9 documentation)
724 Online documentation (REFFIXME).
727 A library providing a lot of useful list and pair processing
728 procedures (@pxref{SRFI-1}).
731 Support for @code{and-let*} (@pxref{SRFI-2}).
734 Support for homogeneous numeric vectors (@pxref{SRFI-4}).
737 Support for some additional string port procedures (@pxref{SRFI-6}).
740 Multiple-value handling with @code{receive} (@pxref{SRFI-8}).
743 Record definition with @code{define-record-type} (@pxref{SRFI-9}).
746 Read hash extension @code{#,()} (@pxref{SRFI-10}).
749 Multiple-value handling with @code{let-values} and @code{let-values*}
753 String library (@pxref{SRFI-13}).
756 Character-set library (@pxref{SRFI-14}).
759 @code{case-lambda} procedures of variable arity (@pxref{SRFI-16}).
762 Getter-with-setter support (@pxref{SRFI-17}).
765 Time/Date library (@pxref{SRFI-19}).
768 Convenient syntax for partial application (@pxref{SRFI-26})
771 @code{rec} convenient recursive expressions (@pxref{SRFI-31})
774 This module contains hooks for using Aubrey Jaffer's portable Scheme
775 library SLIB from Guile (@pxref{SLIB}).
779 @node Accessing Modules from C
780 @subsubsection Accessing Modules from C
782 The last sections have described how modules are used in Scheme code,
783 which is the recommended way of creating and accessing modules. You
784 can also work with modules from C, but it is more cumbersome.
786 The following procedures are available.
788 @deftypefn {C Procedure} SCM scm_current_module ()
789 Return the module that is the @emph{current module}.
792 @deftypefn {C Procedure} SCM scm_set_current_module (SCM @var{module})
793 Set the current module to @var{module} and return the previous current
797 @deftypefn {C Procedure} SCM scm_c_call_with_current_module (SCM @var{module}, SCM (*@var{func})(void *), void *@var{data})
798 Call @var{func} and make @var{module} the current module during the
799 call. The argument @var{data} is passed to @var{func}. The return
800 value of @code{scm_c_call_with_current_module} is the return value of
804 @deftypefn {C Procedure} SCM scm_c_lookup (const char *@var{name})
805 Return the variable bound to the symbol indicated by @var{name} in the
806 current module. If there is no such binding or the symbol is not
807 bound to a variable, signal an error.
810 @deftypefn {C Procedure} SCM scm_lookup (SCM @var{name})
811 Like @code{scm_c_lookup}, but the symbol is specified directly.
814 @deftypefn {C Procedure} SCM scm_c_module_lookup (SCM @var{module}, const char *@var{name})
815 @deftypefnx {C Procedure} SCM scm_module_lookup (SCM @var{module}, SCM @var{name})
816 Like @code{scm_c_lookup} and @code{scm_lookup}, but the specified
817 module is used instead of the current one.
820 @deftypefn {C Procedure} SCM scm_c_define (const char *@var{name}, SCM @var{val})
821 Bind the symbol indicated by @var{name} to a variable in the current
822 module and set that variable to @var{val}. When @var{name} is already
823 bound to a variable, use that. Else create a new variable.
826 @deftypefn {C Procedure} SCM scm_define (SCM @var{name}, SCM @var{val})
827 Like @code{scm_c_define}, but the symbol is specified directly.
830 @deftypefn {C Procedure} SCM scm_c_module_define (SCM @var{module}, const char *@var{name}, SCM @var{val})
831 @deftypefnx {C Procedure} SCM scm_module_define (SCM @var{module}, SCM @var{name}, SCM @var{val})
832 Like @code{scm_c_define} and @code{scm_define}, but the specified
833 module is used instead of the current one.
836 @deftypefn {C Procedure} SCM scm_module_reverse_lookup (SCM @var{module}, SCM @var{variable})
837 Find the symbol that is bound to @var{variable} in @var{module}. When no such binding is found, return @var{#f}.
840 @deftypefn {C Procedure} SCM scm_c_define_module (const char *@var{name}, void (*@var{init})(void *), void *@var{data})
841 Define a new module named @var{name} and make it current while
842 @var{init} is called, passing it @var{data}. Return the module.
844 The parameter @var{name} is a string with the symbols that make up
845 the module name, separated by spaces. For example, @samp{"foo bar"} names
846 the module @samp{(foo bar)}.
848 When there already exists a module named @var{name}, it is used
849 unchanged, otherwise, an empty module is created.
852 @deftypefn {C Procedure} SCM scm_c_resolve_module (const char *@var{name})
853 Find the module name @var{name} and return it. When it has not
854 already been defined, try to auto-load it. When it can't be found
855 that way either, create an empty module. The name is interpreted as
856 for @code{scm_c_define_module}.
859 @deftypefn {C Procedure} SCM scm_resolve_module (SCM @var{name})
860 Like @code{scm_c_resolve_module}, but the name is given as a real list
864 @deftypefn {C Procedure} SCM scm_c_use_module (const char *@var{name})
865 Add the module named @var{name} to the uses list of the current
866 module, as with @code{(use-modules @var{name})}. The name is
867 interpreted as for @code{scm_c_define_module}.
870 @deftypefn {C Procedure} SCM scm_c_export (const char *@var{name}, ...)
871 Add the bindings designated by @var{name}, ... to the public interface
872 of the current module. The list of names is terminated by
876 @node Dynamic Libraries
877 @subsection Dynamic Libraries
879 Most modern Unices have something called @dfn{shared libraries}. This
880 ordinarily means that they have the capability to share the executable
881 image of a library between several running programs to save memory and
882 disk space. But generally, shared libraries give a lot of additional
883 flexibility compared to the traditional static libraries. In fact,
884 calling them `dynamic' libraries is as correct as calling them `shared'.
886 Shared libraries really give you a lot of flexibility in addition to the
887 memory and disk space savings. When you link a program against a shared
888 library, that library is not closely incorporated into the final
889 executable. Instead, the executable of your program only contains
890 enough information to find the needed shared libraries when the program
891 is actually run. Only then, when the program is starting, is the final
892 step of the linking process performed. This means that you need not
893 recompile all programs when you install a new, only slightly modified
894 version of a shared library. The programs will pick up the changes
895 automatically the next time they are run.
897 Now, when all the necessary machinery is there to perform part of the
898 linking at run-time, why not take the next step and allow the programmer
899 to explicitly take advantage of it from within his program? Of course,
900 many operating systems that support shared libraries do just that, and
901 chances are that Guile will allow you to access this feature from within
902 your Scheme programs. As you might have guessed already, this feature
903 is called @dfn{dynamic linking}.@footnote{Some people also refer to the
904 final linking stage at program startup as `dynamic linking', so if you
905 want to make yourself perfectly clear, it is probably best to use the
906 more technical term @dfn{dlopening}, as suggested by Gordon Matzigkeit
907 in his libtool documentation.}
909 As with many aspects of Guile, there is a low-level way to access the
910 dynamic linking apparatus, and a more high-level interface that
911 integrates dynamically linked libraries into the module system.
914 * Low level dynamic linking::
915 * Compiled Code Modules::
916 * Dynamic Linking and Compiled Code Modules::
917 * Compiled Code Installation::
920 @node Low level dynamic linking
921 @subsubsection Low level dynamic linking
923 When using the low level procedures to do your dynamic linking, you have
924 complete control over which library is loaded when and what gets done
927 @deffn {Scheme Procedure} dynamic-link library
928 @deffnx {C Function} scm_dynamic_link (library)
929 Find the shared library denoted by @var{library} (a string) and link it
930 into the running Guile application. When everything works out, return a
931 Scheme object suitable for representing the linked object file.
932 Otherwise an error is thrown. How object files are searched is system
935 Normally, @var{library} is just the name of some shared library file
936 that will be searched for in the places where shared libraries usually
937 reside, such as in @file{/usr/lib} and @file{/usr/local/lib}.
940 @deffn {Scheme Procedure} dynamic-object? obj
941 @deffnx {C Function} scm_dynamic_object_p (obj)
942 Return @code{#t} if @var{obj} is a dynamic library handle, or @code{#f}
946 @deffn {Scheme Procedure} dynamic-unlink dobj
947 @deffnx {C Function} scm_dynamic_unlink (dobj)
948 Unlink the indicated object file from the application. The
949 argument @var{dobj} must have been obtained by a call to
950 @code{dynamic-link}. After @code{dynamic-unlink} has been
951 called on @var{dobj}, its content is no longer accessible.
954 @deffn {Scheme Procedure} dynamic-func name dobj
955 @deffnx {C Function} scm_dynamic_func (name, dobj)
956 Search the dynamic object @var{dobj} for the C function
957 indicated by the string @var{name} and return some Scheme
958 handle that can later be used with @code{dynamic-call} to
959 actually call the function.
961 Regardless whether your C compiler prepends an underscore @samp{_} to
962 the global names in a program, you should @strong{not} include this
963 underscore in @var{function}. Guile knows whether the underscore is
964 needed or not and will add it when necessary.
967 @deffn {Scheme Procedure} dynamic-call func dobj
968 @deffnx {C Function} scm_dynamic_call (func, dobj)
969 Call the C function indicated by @var{func} and @var{dobj}.
970 The function is passed no arguments and its return value is
971 ignored. When @var{function} is something returned by
972 @code{dynamic-func}, call that function and ignore @var{dobj}.
973 When @var{func} is a string , look it up in @var{dynobj}; this
976 (dynamic-call (dynamic-func @var{func} @var{dobj}) #f)
979 Interrupts are deferred while the C function is executing (with
980 @code{SCM_DEFER_INTS}/@code{SCM_ALLOW_INTS}).
983 @deffn {Scheme Procedure} dynamic-args-call func dobj args
984 @deffnx {C Function} scm_dynamic_args_call (func, dobj, args)
985 Call the C function indicated by @var{func} and @var{dobj},
986 just like @code{dynamic-call}, but pass it some arguments and
987 return its return value. The C function is expected to take
988 two arguments and return an @code{int}, just like @code{main}:
990 int c_func (int argc, char **argv);
993 The parameter @var{args} must be a list of strings and is
994 converted into an array of @code{char *}. The array is passed
995 in @var{argv} and its size in @var{argc}. The return value is
996 converted to a Scheme number and returned from the call to
997 @code{dynamic-args-call}.
1000 When dynamic linking is disabled or not supported on your system,
1001 the above functions throw errors, but they are still available.
1003 Here is a small example that works on GNU/Linux:
1006 (define libc-obj (dynamic-link "libc.so"))
1008 @result{} #<dynamic-object "libc.so">
1009 (dynamic-args-call 'rand libc-obj '())
1011 (dynamic-unlink libc-obj)
1013 @result{} #<dynamic-object "libc.so" (unlinked)>
1016 As you can see, after calling @code{dynamic-unlink} on a dynamically
1017 linked library, it is marked as @samp{(unlinked)} and you are no longer
1018 able to use it with @code{dynamic-call}, etc. Whether the library is
1019 really removed from you program is system-dependent and will generally
1020 not happen when some other parts of your program still use it. In the
1021 example above, @code{libc} is almost certainly not removed from your
1022 program because it is badly needed by almost everything.
1024 The functions to call a function from a dynamically linked library,
1025 @code{dynamic-call} and @code{dynamic-args-call}, are not very powerful.
1026 They are mostly intended to be used for calling specially written
1027 initialization functions that will then add new primitives to Guile.
1028 For example, we do not expect that you will dynamically link
1029 @file{libX11} with @code{dynamic-link} and then construct a beautiful
1030 graphical user interface just by using @code{dynamic-call} and
1031 @code{dynamic-args-call}. Instead, the usual way would be to write a
1032 special Guile<->X11 glue library that has intimate knowledge about both
1033 Guile and X11 and does whatever is necessary to make them inter-operate
1034 smoothly. This glue library could then be dynamically linked into a
1035 vanilla Guile interpreter and activated by calling its initialization
1036 function. That function would add all the new types and primitives to
1037 the Guile interpreter that it has to offer.
1039 From this setup the next logical step is to integrate these glue
1040 libraries into the module system of Guile so that you can load new
1041 primitives into a running system just as you can load new Scheme code.
1043 There is, however, another possibility to get a more thorough access to
1044 the functions contained in a dynamically linked library. Anthony Green
1045 has written @file{libffi}, a library that implements a @dfn{foreign
1046 function interface} for a number of different platforms. With it, you
1047 can extend the Spartan functionality of @code{dynamic-call} and
1048 @code{dynamic-args-call} considerably. There is glue code available in
1049 the Guile contrib archive to make @file{libffi} accessible from Guile.
1051 @node Compiled Code Modules
1052 @subsubsection Putting Compiled Code into Modules
1054 The new primitives that you add to Guile with
1055 @code{scm_c_define_gsubr} (@pxref{Primitive Procedures}) or with any
1056 of the other mechanisms are placed into the @code{(guile-user)} module
1057 by default. However, it is also possible to put new primitives into
1060 The mechanism for doing so is not very well thought out and is likely to
1061 change when the module system of Guile itself is revised, but it is
1062 simple and useful enough to document it as it stands.
1064 What @code{scm_c_define_gsubr} and the functions used by the snarfer
1065 really do is to add the new primitives to whatever module is the
1066 @emph{current module} when they are called. This is analogous to the
1067 way Scheme code is put into modules: the @code{define-module} expression
1068 at the top of a Scheme source file creates a new module and makes it the
1069 current module while the rest of the file is evaluated. The
1070 @code{define} expressions in that file then add their new definitions to
1071 this current module.
1073 Therefore, all we need to do is to make sure that the right module is
1074 current when calling @code{scm_c_define_gsubr} for our new primitives.
1076 @node Dynamic Linking and Compiled Code Modules
1077 @subsubsection Dynamic Linking and Compiled Code Modules
1079 The most interesting application of dynamically linked libraries is
1080 probably to use them for providing @emph{compiled code modules} to
1081 Scheme programs. As much fun as programming in Scheme is, every now and
1082 then comes the need to write some low-level C stuff to make Scheme even
1085 Not only can you put these new primitives into their own module (see the
1086 previous section), you can even put them into a shared library that is
1087 only then linked to your running Guile image when it is actually
1090 An example will hopefully make everything clear. Suppose we want to
1091 make the Bessel functions of the C library available to Scheme in the
1092 module @samp{(math bessel)}. First we need to write the appropriate
1093 glue code to convert the arguments and return values of the functions
1094 from Scheme to C and back. Additionally, we need a function that will
1095 add them to the set of Guile primitives. Because this is just an
1096 example, we will only implement this for the @code{j0} function.
1098 @c FIXME::martin: Change all gh_ references to their scm_ equivalents.
1102 #include <libguile.h>
1107 return scm_double2num (j0 (scm_num2dbl (x, "j0")));
1113 scm_c_define_gsubr ("j0", 1, 0, 0, j0_wrapper);
1117 We can already try to bring this into action by manually calling the low
1118 level functions for performing dynamic linking. The C source file needs
1119 to be compiled into a shared library. Here is how to do it on
1120 GNU/Linux, please refer to the @code{libtool} documentation for how to
1121 create dynamically linkable libraries portably.
1124 gcc -shared -o libbessel.so -fPIC bessel.c
1130 (define bessel-lib (dynamic-link "./libbessel.so"))
1131 (dynamic-call "init_math_bessel" bessel-lib)
1133 @result{} 0.223890779141236
1136 The filename @file{./libbessel.so} should be pointing to the shared
1137 library produced with the @code{gcc} command above, of course. The
1138 second line of the Guile interaction will call the
1139 @code{init_math_bessel} function which in turn will register the C
1140 function @code{j0_wrapper} with the Guile interpreter under the name
1141 @code{j0}. This function becomes immediately available and we can call
1144 Fun, isn't it? But we are only half way there. This is what
1145 @code{apropos} has to say about @code{j0}:
1149 @print{} (guile-user): j0 #<primitive-procedure j0>
1152 As you can see, @code{j0} is contained in the root module, where all
1153 the other Guile primitives like @code{display}, etc live. In general,
1154 a primitive is put into whatever module is the @dfn{current module} at
1155 the time @code{scm_c_define_gsubr} is called.
1157 A compiled module should have a specially named @dfn{module init
1158 function}. Guile knows about this special name and will call that
1159 function automatically after having linked in the shared library. For
1160 our example, we replace @code{init_math_bessel} with the following code in
1165 init_math_bessel (void *unused)
1167 scm_c_define_gsubr ("j0", 1, 0, 0, j0_wrapper);
1168 scm_c_export ("j0", NULL);
1172 scm_init_math_bessel_module ()
1174 scm_c_define_module ("math bessel", init_math_bessel, NULL);
1178 The general pattern for the name of a module init function is:
1179 @samp{scm_init_}, followed by the name of the module where the
1180 individual hierarchical components are concatenated with underscores,
1181 followed by @samp{_module}.
1183 After @file{libbessel.so} has been rebuilt, we need to place the shared
1184 library into the right place.
1186 Once the module has been correctly installed, it should be possible to
1190 guile> (load-extension "./libbessel.so" "scm_init_math_bessel_module")
1191 guile> (use-modules (math bessel))
1194 guile> (apropos "j0")
1195 @print{} (math bessel): j0 #<primitive-procedure j0>
1200 @deffn {Scheme Procedure} load-extension lib init
1201 @deffnx {C Function} scm_load_extension (lib, init)
1202 Load and initialize the extension designated by LIB and INIT.
1203 When there is no pre-registered function for LIB/INIT, this is
1207 (dynamic-call INIT (dynamic-link LIB))
1210 When there is a pre-registered function, that function is called
1213 Normally, there is no pre-registered function. This option exists
1214 only for situations where dynamic linking is unavailable or unwanted.
1215 In that case, you would statically link your program with the desired
1216 library, and register its init function right after Guile has been
1219 LIB should be a string denoting a shared library without any file type
1220 suffix such as ".so". The suffix is provided automatically. It
1221 should also not contain any directory components. Libraries that
1222 implement Guile Extensions should be put into the normal locations for
1223 shared libraries. We recommend to use the naming convention
1224 libguile-bla-blum for a extension related to a module `(bla blum)'.
1226 The normal way for a extension to be used is to write a small Scheme
1227 file that defines a module, and to load the extension into this
1228 module. When the module is auto-loaded, the extension is loaded as
1232 (define-module (bla blum))
1234 (load-extension "libguile-bla-blum" "bla_init_blum")
1239 @node Compiled Code Installation
1240 @subsubsection Compiled Code Installation
1242 The simplest way to write a module using compiled C code is
1245 (define-module (foo bar))
1246 (load-extension "foobar-c-code" "foo_bar_init")
1249 When loaded with @code{(use-modules (foo bar))}, the
1250 @code{load-extension} call looks for the @file{foobar-c-code.so} (etc)
1251 object file in the standard system locations, such as @file{/usr/lib}
1252 or @file{/usr/local/lib}.
1254 If someone installs your module to a non-standard location then the
1255 object file won't be found. You can address this by inserting the
1256 install location in the @file{foo/bar.scm} file. This is convenient
1257 for the user and also guarantees the intended object is read, even if
1258 stray older or newer versions are in the loader's path.
1260 The usual way to specify an install location is with a @code{prefix}
1261 at the configure stage, for instance @samp{./configure prefix=/opt}
1262 results in library files as say @file{/opt/lib/foobar-c-code.so}.
1263 When using Autoconf (@pxref{Top, , Introduction, autoconf, The GNU
1264 Autoconf Manual}), the library location is in a @code{libdir}
1265 variable. Its value is intended to be expanded by @command{make}, and
1266 can by substituted into a source file like @file{foo.scm.in}
1269 (define-module (foo bar))
1270 (load-extension "XXlibdirXX/foobar-c-code" "foo_bar_init")
1274 with the following in a @file{Makefile}, using @command{sed}
1275 (@pxref{Top, , Introduction, sed, SED, A Stream Editor}),
1279 sed 's|XXlibdirXX|$(libdir)|' <foo.scm.in >foo.scm
1282 The actual pattern @code{XXlibdirXX} is arbitrary, it's only something
1283 which doesn't otherwise occur. If several modules need the value, it
1284 can be easier to create one @file{foo/config.scm} with a define of the
1285 @code{libdir} location, and use that as required.
1288 (define-module (foo config))
1289 (define-public foo-config-libdir "XXlibdirXX"")
1292 Such a file might have other locations too, for instance a data
1293 directory for auxiliary files, or @code{localedir} if the module has
1294 its own @code{gettext} message catalogue
1295 (@pxref{Internationalization}).
1297 When installing multiple C code objects, it can be convenient to put
1298 them in a subdirectory of @code{libdir}, thus giving for example
1299 @code{/usr/lib/foo/some-obj.so}. If the objects are only meant to be
1300 used through the module, then a subdirectory keeps them out of sight.
1302 It will be noted all of the above requires that the Scheme code to be
1303 found in @code{%load-path} (@pxref{Build Config}). Presently it's
1304 left up to the system administrator or each user to augment that path
1305 when installing Guile modules in non-default locations. But having
1306 reached the Scheme code, that code should take care of hitting any of
1307 its own private files etc.
1309 Presently there's no convention for having a Guile version number in
1310 module C code filenames or directories. This is primarily because
1311 there's no established principles for two versions of Guile to be
1312 installed under the same prefix (eg. two both under @file{/usr}).
1313 Assuming upward compatibility is maintained then this should be
1314 unnecessary, and if compatibility is not maintained then it's highly
1315 likely a package will need to be revisited anyway.
1317 The present suggestion is that modules should assume when they're
1318 installed under a particular @code{prefix} that there's a single
1319 version of Guile there, and the @code{guile-config} at build time has
1320 the necessary information about it. C code or Scheme code might adapt
1321 itself accordingly (allowing for features not available in an older
1322 version for instance).
1326 @subsection Variables
1329 Each module has its own hash table, sometimes known as an @dfn{obarray},
1330 that maps the names defined in that module to their corresponding
1333 A variable is a box-like object that can hold any Scheme value. It is
1334 said to be @dfn{undefined} if its box holds a special Scheme value that
1335 denotes undefined-ness (which is different from all other Scheme values,
1336 including for example @code{#f}); otherwise the variable is
1339 On its own, a variable object is anonymous. A variable is said to be
1340 @dfn{bound} when it is associated with a name in some way, usually a
1341 symbol in a module obarray. When this happens, the relationship is
1342 mutual: the variable is bound to the name (in that module), and the name
1343 (in that module) is bound to the variable.
1345 (That's the theory, anyway. In practice, defined-ness and bound-ness
1346 sometimes get confused, because Lisp and Scheme implementations have
1347 often conflated --- or deliberately drawn no distinction between --- a
1348 name that is unbound and a name that is bound to a variable whose value
1349 is undefined. We will try to be clear about the difference and explain
1350 any confusion where it is unavoidable.)
1352 Variables do not have a read syntax. Most commonly they are created and
1353 bound implicitly by @code{define} expressions: a top-level @code{define}
1354 expression of the form
1357 (define @var{name} @var{value})
1361 creates a variable with initial value @var{value} and binds it to the
1362 name @var{name} in the current module. But they can also be created
1363 dynamically by calling one of the constructor procedures
1364 @code{make-variable} and @code{make-undefined-variable}.
1366 First-class variables are especially useful for interacting with the
1367 current module system (@pxref{The Guile module system}).
1369 @deffn {Scheme Procedure} make-undefined-variable
1370 @deffnx {C Function} scm_make_undefined_variable ()
1371 Return a variable that is initially unbound.
1374 @deffn {Scheme Procedure} make-variable init
1375 @deffnx {C Function} scm_make_variable (init)
1376 Return a variable initialized to value @var{init}.
1379 @deffn {Scheme Procedure} variable-bound? var
1380 @deffnx {C Function} scm_variable_bound_p (var)
1381 Return @code{#t} iff @var{var} is bound to a value.
1382 Throws an error if @var{var} is not a variable object.
1385 @deffn {Scheme Procedure} variable-ref var
1386 @deffnx {C Function} scm_variable_ref (var)
1387 Dereference @var{var} and return its value.
1388 @var{var} must be a variable object; see @code{make-variable}
1389 and @code{make-undefined-variable}.
1392 @deffn {Scheme Procedure} variable-set! var val
1393 @deffnx {C Function} scm_variable_set_x (var, val)
1394 Set the value of the variable @var{var} to @var{val}.
1395 @var{var} must be a variable object, @var{val} can be any
1396 value. Return an unspecified value.
1399 @deffn {Scheme Procedure} variable? obj
1400 @deffnx {C Function} scm_variable_p (obj)
1401 Return @code{#t} iff @var{obj} is a variable object, else
1407 @c TeX-master: "guile.texi"