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 in 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 %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:
244 (use-modules ((ice-9 popen)
245 :select ((open-pipe . pipe-open) close-pipe)
246 :renamer (symbol-prefix-proc 'unixy:)))
249 Here, the interface specification is more complex than before, and the
250 result is that a custom interface with only two bindings is created and
251 subsequently accessed by the current module. The mapping of old to new
254 @c Use `smallexample' since `table' is ugly. --ttn
256 (ice-9 popen) sees: current module sees:
257 open-pipe unixy:pipe-open
258 close-pipe unixy:close-pipe
261 This example also shows how to use the convenience procedure
262 @code{symbol-prefix-proc}.
264 You can also directly refer to bindings in a module by using the
265 @code{@@} syntax. For example, instead of using the
266 @code{use-modules} statement from above and writing
267 @code{unixy:pipe-open} to refer to the @code{pipe-open} from the
268 @code{(ice-9 popen)}, you could also write @code{(@@ (ice-9 popen)
269 open-pipe)}. Thus an alternative to the complete @code{use-modules}
273 (define unixy:pipe-open (@@ (ice-9 popen) open-pipe))
274 (define unixy:close-pipe (@@ (ice-9 popen) close-pipe))
277 There is also @code{@@@@}, which can be used like @code{@@}, but does
278 not check whether the variable that is being accessed is actually
279 exported. Thus, @code{@@@@} can be thought of as the impolite version
280 of @code{@@} and should only be used as a last resort or for
281 debugging, for example.
283 Note that just as with a @code{use-modules} statement, any module that
284 has not yet been loaded yet will be loaded when referenced by a
285 @code{@@} or @code{@@@@} form.
287 You can also use the @code{@@} and @code{@@@@} syntaxes as the target
288 of a @code{set!} when the binding refers to a variable.
290 @c begin (scm-doc-string "boot-9.scm" "symbol-prefix-proc")
291 @deffn {Scheme Procedure} symbol-prefix-proc prefix-sym
292 Return a procedure that prefixes its arg (a symbol) with
294 @c Insert gratuitous C++ slam here. --ttn
297 @c begin (scm-doc-string "boot-9.scm" "use-modules")
298 @deffn syntax use-modules spec @dots{}
299 Resolve each interface specification @var{spec} into an interface and
300 arrange for these to be accessible by the current module. The return
301 value is unspecified.
303 @var{spec} can be a list of symbols, in which case it names a module
304 whose public interface is found and used.
306 @var{spec} can also be of the form:
309 (MODULE-NAME [:select SELECTION] [:renamer RENAMER])
312 in which case a custom interface is newly created and used.
313 @var{module-name} is a list of symbols, as above; @var{selection} is a
314 list of selection-specs; and @var{renamer} is a procedure that takes a
315 symbol and returns its new name. A selection-spec is either a symbol or
316 a pair of symbols @code{(ORIG . SEEN)}, where @var{orig} is the name in
317 the used module and @var{seen} is the name in the using module. Note
318 that @var{seen} is also passed through @var{renamer}.
320 The @code{:select} and @code{:renamer} clauses are optional. If both are
321 omitted, the returned interface has no bindings. If the @code{:select}
322 clause is omitted, @var{renamer} operates on the used module's public
325 Signal error if module name is not resolvable.
329 @c FIXME::martin: Is this correct, and is there more to say?
330 @c FIXME::martin: Define term and concept `system transformer' somewhere.
332 @deffn syntax use-syntax module-name
333 Load the module @code{module-name} and use its system
334 transformer as the system transformer for the currently defined module,
335 as well as installing it as the current system transformer.
338 @deffn syntax @@ module-name binding-name
339 Refer to the binding named @var{binding-name} in module
340 @var{module-name}. The binding must have been exported by the module.
343 @deffn syntax @@@@ module-name binding-name
344 Refer to the binding named @var{binding-name} in module
345 @var{module-name}. The binding must not have been exported by the
346 module. This syntax is only intended for debugging purposes or as a
350 @node Creating Guile Modules
351 @subsubsection Creating Guile Modules
353 When you want to create your own modules, you have to take the following
358 Create a Scheme source file and add all variables and procedures you wish
359 to export, or which are required by the exported procedures.
362 Add a @code{define-module} form at the beginning.
365 Export all bindings which should be in the public interface, either
366 by using @code{define-public} or @code{export} (both documented below).
369 @c begin (scm-doc-string "boot-9.scm" "define-module")
370 @deffn syntax define-module module-name [options @dots{}]
371 @var{module-name} is of the form @code{(hierarchy file)}. One
375 (define-module (ice-9 popen))
378 @code{define-module} makes this module available to Guile programs under
379 the given @var{module-name}.
381 The @var{options} are keyword/value pairs which specify more about the
382 defined module. The recognized options and their meaning is shown in
385 @c fixme: Should we use "#:" or ":"?
388 @item #:use-module @var{interface-specification}
389 Equivalent to a @code{(use-modules @var{interface-specification})}
390 (@pxref{Using Guile Modules}).
392 @item #:use-syntax @var{module}
393 Use @var{module} when loading the currently defined module, and install
394 it as the syntax transformer.
396 @item #:autoload @var{module} @var{symbol-list}
398 Load @var{module} when any of @var{symbol-list} are accessed. For
402 (define-module (my mod)
403 #:autoload (srfi srfi-1) (partition delete-duplicates))
406 (set! foo (delete-duplicates ...)))
409 When a module is autoloaded, all it's bindings become available.
410 @var{symbol-list} is just those that will first trigger the load.
412 An autoload is a good way to put off loading a big module until it's
413 really needed, for instance for faster startup or if it will only be
414 needed in certain circumstances.
416 @code{@@} can do a similar thing (@pxref{Using Guile Modules}), but in
417 that case an @code{@@} form must be written every time a binding from
420 @item #:export @var{list}
422 Export all identifiers in @var{list}, which must be a list of symbols.
423 This is equivalent to @code{(export @var{list})} in the module body.
427 Tell Guile not to record information for procedure backtraces when
428 executing the procedures in this module.
432 Create a @dfn{pure} module, that is a module which does not contain any
433 of the standard procedure bindings except for the syntax forms. This is
434 useful if you want to create @dfn{safe} modules, that is modules which
435 do not know anything about dangerous procedures.
441 @deffn syntax export variable @dots{}
442 Add all @var{variable}s (which must be symbols) to the list of exported
443 bindings of the current module.
446 @c begin (scm-doc-string "boot-9.scm" "define-public")
447 @deffn syntax define-public @dots{}
448 Equivalent to @code{(begin (define foo ...) (export foo))}.
452 @node Module System Reflection
453 @subsubsection Module System Reflection
455 The previous sections have described a declarative view of the module
456 system. You can also work with it programmatically by accessing and
457 modifying various parts of the Scheme objects that Guile uses to
458 implement the module system.
460 At any time, there is a @dfn{current module}. This module is the one
461 where a top-level @code{define} and similar syntax will add new
462 bindings. You can find other module objects with @code{resolve-module},
465 These module objects can be used as the second argument to @code{eval}.
467 @deffn {Scheme Procedure} current-module
468 Return the current module object.
471 @deffn {Scheme Procedure} set-current-module module
472 Set the current module to @var{module} and return
473 the previous current module.
476 @deffn {Scheme Procedure} resolve-module name
477 Find the module named @var{name} and return it. When it has not already
478 been defined, try to auto-load it. When it can't be found that way
479 either, create an empty module. The name is a list of symbols.
482 @deffn {Scheme Procedure} resolve-interface name
483 Find the module named @var{name} as with @code{resolve-module} and
484 return its interface. The interface of a module is also a module
485 object, but it contains only the exported bindings.
488 @deffn {Scheme Procedure} module-use! module interface
489 Add @var{interface} to the front of the use-list of @var{module}. Both
490 arguments should be module objects, and @var{interface} should very
491 likely be a module returned by @code{resolve-interface}.
494 @node Module System Quirks
495 @subsubsection Module System Quirks
497 Although the programming interfaces are relatively stable, the Guile
498 module system itself is still evolving. Here are some situations where
499 usage surpasses design.
504 When using a module which exports a macro definition, the other module
505 must export all bindings the macro expansion uses, too, because the
506 expanded code would otherwise not be able to see these definitions and
507 issue a ``variable unbound'' error, or worse, would use another binding
508 which might be present in the scope of the expansion.
511 When two or more used modules export bindings with the same names, the
512 last accessed module wins, and the exported binding of that last module
513 will silently be used. This might lead to hard-to-find errors because
514 wrong procedures or variables are used. To avoid this kind of
515 @dfn{name-clash} situation, use a custom interface specification
516 (@pxref{Using Guile Modules}). (We include this entry for the possible
517 benefit of users of Guile versions previous to 1.5.0, when custom
518 interfaces were added to the module system.)
521 [Add other quirks here.]
526 @node Included Guile Modules
527 @subsubsection Included Guile Modules
529 @c FIXME::martin: Review me!
531 Some modules are included in the Guile distribution; here are references
532 to the entries in this manual which describe them in more detail:
536 boot-9 is Guile's initialization module, and it is always loaded when
540 Mikael Djurfeldt's source-level debugging support for Guile
541 (@pxref{Debugging Features}).
544 Actions based on matching input from a port (@pxref{Expect}).
547 Formatted output in the style of Common Lisp (@pxref{Formatted
551 File tree walker (@pxref{File Tree Walk}).
553 @item (ice-9 getopt-long)
554 Command line option processing (@pxref{getopt-long}).
556 @item (ice-9 history)
557 Refer to previous interactive expressions (@pxref{Value History}).
560 Pipes to and from child processes (@pxref{Pipes}).
562 @item (ice-9 pretty-print)
563 Nicely formatted output of Scheme expressions and objects
564 (@pxref{Pretty Printing}).
567 First-in first-out queues (@pxref{Queues}).
570 Line- and character-delimited input (@pxref{Line/Delimited}).
572 @item (ice-9 readline)
573 @code{readline} interactive command line editing (@pxref{Readline
576 @item (ice-9 receive)
577 Multiple-value handling with @code{receive} (@pxref{Multiple Values}).
580 Regular expression matching (@pxref{Regular Expressions}).
583 Block string input/output (@pxref{Block Reading and Writing}).
585 @item (ice-9 streams)
586 Sequence of values calculated on-demand (@pxref{Streams}).
588 @item (ice-9 syncase)
589 R5RS @code{syntax-rules} macro system (@pxref{Syntax Rules}).
591 @item (ice-9 threads)
592 Guile's support for multi threaded execution (@pxref{Scheduling}).
594 @item (ice-9 documentation)
595 Online documentation (REFFIXME).
598 A library providing a lot of useful list and pair processing
599 procedures (@pxref{SRFI-1}).
602 Support for @code{and-let*} (@pxref{SRFI-2}).
605 Support for homogeneous numeric vectors (@pxref{SRFI-4}).
608 Support for some additional string port procedures (@pxref{SRFI-6}).
611 Multiple-value handling with @code{receive} (@pxref{SRFI-8}).
614 Record definition with @code{define-record-type} (@pxref{SRFI-9}).
617 Read hash extension @code{#,()} (@pxref{SRFI-10}).
620 Multiple-value handling with @code{let-values} and @code{let-values*}
624 String library (@pxref{SRFI-13}).
627 Character-set library (@pxref{SRFI-14}).
630 @code{case-lambda} procedures of variable arity (@pxref{SRFI-16}).
633 Getter-with-setter support (@pxref{SRFI-17}).
636 Time/Date library (@pxref{SRFI-19}).
639 Convenient syntax for partial application (@pxref{SRFI-26})
642 @code{rec} convenient recursive expressions (@pxref{SRFI-31})
645 This module contains hooks for using Aubrey Jaffer's portable Scheme
646 library SLIB from Guile (@pxref{SLIB}).
650 @node Accessing Modules from C
651 @subsubsection Accessing Modules from C
653 The last sections have described how modules are used in Scheme code,
654 which is the recommended way of creating and accessing modules. You
655 can also work with modules from C, but it is more cumbersome.
657 The following procedures are available.
659 @deftypefn {C Procedure} SCM scm_current_module ()
660 Return the module that is the @emph{current module}.
663 @deftypefn {C Procedure} SCM scm_set_current_module (SCM @var{module})
664 Set the current module to @var{module} and return the previous current
668 @deftypefn {C Procedure} SCM scm_c_call_with_current_module (SCM @var{module}, SCM (*@var{func})(void *), void *@var{data})
669 Call @var{func} and make @var{module} the current module during the
670 call. The argument @var{data} is passed to @var{func}. The return
671 value of @code{scm_c_call_with_current_module} is the return value of
675 @deftypefn {C Procedure} SCM scm_c_lookup (const char *@var{name})
676 Return the variable bound to the symbol indicated by @var{name} in the
677 current module. If there is no such binding or the symbol is not
678 bound to a variable, signal an error.
681 @deftypefn {C Procedure} SCM scm_lookup (SCM @var{name})
682 Like @code{scm_c_lookup}, but the symbol is specified directly.
685 @deftypefn {C Procedure} SCM scm_c_module_lookup (SCM @var{module}, const char *@var{name})
686 @deftypefnx {C Procedure} SCM scm_module_lookup (SCM @var{module}, SCM @var{name})
687 Like @code{scm_c_lookup} and @code{scm_lookup}, but the specified
688 module is used instead of the current one.
691 @deftypefn {C Procedure} SCM scm_c_define (const char *@var{name}, SCM @var{val})
692 Bind the symbol indicated by @var{name} to a variable in the current
693 module and set that variable to @var{val}. When @var{name} is already
694 bound to a variable, use that. Else create a new variable.
697 @deftypefn {C Procedure} SCM scm_define (SCM @var{name}, SCM @var{val})
698 Like @code{scm_c_define}, but the symbol is specified directly.
701 @deftypefn {C Procedure} SCM scm_c_module_define (SCM @var{module}, const char *@var{name}, SCM @var{val})
702 @deftypefnx {C Procedure} SCM scm_module_define (SCM @var{module}, SCM @var{name}, SCM @var{val})
703 Like @code{scm_c_define} and @code{scm_define}, but the specified
704 module is used instead of the current one.
707 @deftypefn {C Procedure} SCM scm_module_reverse_lookup (SCM @var{module}, SCM @var{variable})
708 Find the symbol that is bound to @var{variable} in @var{module}. When no such binding is found, return @var{#f}.
711 @deftypefn {C Procedure} SCM scm_c_define_module (const char *@var{name}, void (*@var{init})(void *), void *@var{data})
712 Define a new module named @var{name} and make it current while
713 @var{init} is called, passing it @var{data}. Return the module.
715 The parameter @var{name} is a string with the symbols that make up
716 the module name, separated by spaces. For example, @samp{"foo bar"} names
717 the module @samp{(foo bar)}.
719 When there already exists a module named @var{name}, it is used
720 unchanged, otherwise, an empty module is created.
723 @deftypefn {C Procedure} SCM scm_c_resolve_module (const char *@var{name})
724 Find the module name @var{name} and return it. When it has not
725 already been defined, try to auto-load it. When it can't be found
726 that way either, create an empty module. The name is interpreted as
727 for @code{scm_c_define_module}.
730 @deftypefn {C Procedure} SCM scm_resolve_module (SCM @var{name})
731 Like @code{scm_c_resolve_module}, but the name is given as a real list
735 @deftypefn {C Procedure} SCM scm_c_use_module (const char *@var{name})
736 Add the module named @var{name} to the uses list of the current
737 module, as with @code{(use-modules @var{name})}. The name is
738 interpreted as for @code{scm_c_define_module}.
741 @deftypefn {C Procedure} SCM scm_c_export (const char *@var{name}, ...)
742 Add the bindings designated by @var{name}, ... to the public interface
743 of the current module. The list of names is terminated by
747 @node Dynamic Libraries
748 @subsection Dynamic Libraries
750 Most modern Unices have something called @dfn{shared libraries}. This
751 ordinarily means that they have the capability to share the executable
752 image of a library between several running programs to save memory and
753 disk space. But generally, shared libraries give a lot of additional
754 flexibility compared to the traditional static libraries. In fact,
755 calling them `dynamic' libraries is as correct as calling them `shared'.
757 Shared libraries really give you a lot of flexibility in addition to the
758 memory and disk space savings. When you link a program against a shared
759 library, that library is not closely incorporated into the final
760 executable. Instead, the executable of your program only contains
761 enough information to find the needed shared libraries when the program
762 is actually run. Only then, when the program is starting, is the final
763 step of the linking process performed. This means that you need not
764 recompile all programs when you install a new, only slightly modified
765 version of a shared library. The programs will pick up the changes
766 automatically the next time they are run.
768 Now, when all the necessary machinery is there to perform part of the
769 linking at run-time, why not take the next step and allow the programmer
770 to explicitly take advantage of it from within his program? Of course,
771 many operating systems that support shared libraries do just that, and
772 chances are that Guile will allow you to access this feature from within
773 your Scheme programs. As you might have guessed already, this feature
774 is called @dfn{dynamic linking}.@footnote{Some people also refer to the
775 final linking stage at program startup as `dynamic linking', so if you
776 want to make yourself perfectly clear, it is probably best to use the
777 more technical term @dfn{dlopening}, as suggested by Gordon Matzigkeit
778 in his libtool documentation.}
780 As with many aspects of Guile, there is a low-level way to access the
781 dynamic linking apparatus, and a more high-level interface that
782 integrates dynamically linked libraries into the module system.
785 * Low level dynamic linking::
786 * Compiled Code Modules::
787 * Dynamic Linking and Compiled Code Modules::
790 @node Low level dynamic linking
791 @subsubsection Low level dynamic linking
793 When using the low level procedures to do your dynamic linking, you have
794 complete control over which library is loaded when and what gets done
797 @deffn {Scheme Procedure} dynamic-link library
798 @deffnx {C Function} scm_dynamic_link (library)
799 Find the shared library denoted by @var{library} (a string) and link it
800 into the running Guile application. When everything works out, return a
801 Scheme object suitable for representing the linked object file.
802 Otherwise an error is thrown. How object files are searched is system
805 Normally, @var{library} is just the name of some shared library file
806 that will be searched for in the places where shared libraries usually
807 reside, such as in @file{/usr/lib} and @file{/usr/local/lib}.
810 @deffn {Scheme Procedure} dynamic-object? obj
811 @deffnx {C Function} scm_dynamic_object_p (obj)
812 Return @code{#t} if @var{obj} is a dynamic library handle, or @code{#f}
816 @deffn {Scheme Procedure} dynamic-unlink dobj
817 @deffnx {C Function} scm_dynamic_unlink (dobj)
818 Unlink the indicated object file from the application. The
819 argument @var{dobj} must have been obtained by a call to
820 @code{dynamic-link}. After @code{dynamic-unlink} has been
821 called on @var{dobj}, its content is no longer accessible.
824 @deffn {Scheme Procedure} dynamic-func name dobj
825 @deffnx {C Function} scm_dynamic_func (name, dobj)
826 Search the dynamic object @var{dobj} for the C function
827 indicated by the string @var{name} and return some Scheme
828 handle that can later be used with @code{dynamic-call} to
829 actually call the function.
831 Regardless whether your C compiler prepends an underscore @samp{_} to
832 the global names in a program, you should @strong{not} include this
833 underscore in @var{function}. Guile knows whether the underscore is
834 needed or not and will add it when necessary.
837 @deffn {Scheme Procedure} dynamic-call func dobj
838 @deffnx {C Function} scm_dynamic_call (func, dobj)
839 Call the C function indicated by @var{func} and @var{dobj}.
840 The function is passed no arguments and its return value is
841 ignored. When @var{function} is something returned by
842 @code{dynamic-func}, call that function and ignore @var{dobj}.
843 When @var{func} is a string , look it up in @var{dynobj}; this
846 (dynamic-call (dynamic-func @var{func} @var{dobj}) #f)
849 Interrupts are deferred while the C function is executing (with
850 @code{SCM_DEFER_INTS}/@code{SCM_ALLOW_INTS}).
853 @deffn {Scheme Procedure} dynamic-args-call func dobj args
854 @deffnx {C Function} scm_dynamic_args_call (func, dobj, args)
855 Call the C function indicated by @var{func} and @var{dobj},
856 just like @code{dynamic-call}, but pass it some arguments and
857 return its return value. The C function is expected to take
858 two arguments and return an @code{int}, just like @code{main}:
860 int c_func (int argc, char **argv);
863 The parameter @var{args} must be a list of strings and is
864 converted into an array of @code{char *}. The array is passed
865 in @var{argv} and its size in @var{argc}. The return value is
866 converted to a Scheme number and returned from the call to
867 @code{dynamic-args-call}.
870 When dynamic linking is disabled or not supported on your system,
871 the above functions throw errors, but they are still available.
873 Here is a small example that works on GNU/Linux:
876 (define libc-obj (dynamic-link "libc.so"))
878 @result{} #<dynamic-object "libc.so">
879 (dynamic-args-call 'rand libc-obj '())
881 (dynamic-unlink libc-obj)
883 @result{} #<dynamic-object "libc.so" (unlinked)>
886 As you can see, after calling @code{dynamic-unlink} on a dynamically
887 linked library, it is marked as @samp{(unlinked)} and you are no longer
888 able to use it with @code{dynamic-call}, etc. Whether the library is
889 really removed from you program is system-dependent and will generally
890 not happen when some other parts of your program still use it. In the
891 example above, @code{libc} is almost certainly not removed from your
892 program because it is badly needed by almost everything.
894 The functions to call a function from a dynamically linked library,
895 @code{dynamic-call} and @code{dynamic-args-call}, are not very powerful.
896 They are mostly intended to be used for calling specially written
897 initialization functions that will then add new primitives to Guile.
898 For example, we do not expect that you will dynamically link
899 @file{libX11} with @code{dynamic-link} and then construct a beautiful
900 graphical user interface just by using @code{dynamic-call} and
901 @code{dynamic-args-call}. Instead, the usual way would be to write a
902 special Guile<->X11 glue library that has intimate knowledge about both
903 Guile and X11 and does whatever is necessary to make them inter-operate
904 smoothly. This glue library could then be dynamically linked into a
905 vanilla Guile interpreter and activated by calling its initialization
906 function. That function would add all the new types and primitives to
907 the Guile interpreter that it has to offer.
909 From this setup the next logical step is to integrate these glue
910 libraries into the module system of Guile so that you can load new
911 primitives into a running system just as you can load new Scheme code.
913 There is, however, another possibility to get a more thorough access to
914 the functions contained in a dynamically linked library. Anthony Green
915 has written @file{libffi}, a library that implements a @dfn{foreign
916 function interface} for a number of different platforms. With it, you
917 can extend the Spartan functionality of @code{dynamic-call} and
918 @code{dynamic-args-call} considerably. There is glue code available in
919 the Guile contrib archive to make @file{libffi} accessible from Guile.
921 @node Compiled Code Modules
922 @subsubsection Putting Compiled Code into Modules
924 The new primitives that you add to Guile with
925 @code{scm_c_define_gsubr} (@pxref{Primitive Procedures}) or with any
926 of the other mechanisms are placed into the @code{(guile-user)} module
927 by default. However, it is also possible to put new primitives into
930 The mechanism for doing so is not very well thought out and is likely to
931 change when the module system of Guile itself is revised, but it is
932 simple and useful enough to document it as it stands.
934 What @code{scm_c_define_gsubr} and the functions used by the snarfer
935 really do is to add the new primitives to whatever module is the
936 @emph{current module} when they are called. This is analogous to the
937 way Scheme code is put into modules: the @code{define-module} expression
938 at the top of a Scheme source file creates a new module and makes it the
939 current module while the rest of the file is evaluated. The
940 @code{define} expressions in that file then add their new definitions to
943 Therefore, all we need to do is to make sure that the right module is
944 current when calling @code{scm_c_define_gsubr} for our new primitives.
946 @node Dynamic Linking and Compiled Code Modules
947 @subsubsection Dynamic Linking and Compiled Code Modules
949 The most interesting application of dynamically linked libraries is
950 probably to use them for providing @emph{compiled code modules} to
951 Scheme programs. As much fun as programming in Scheme is, every now and
952 then comes the need to write some low-level C stuff to make Scheme even
955 Not only can you put these new primitives into their own module (see the
956 previous section), you can even put them into a shared library that is
957 only then linked to your running Guile image when it is actually
960 An example will hopefully make everything clear. Suppose we want to
961 make the Bessel functions of the C library available to Scheme in the
962 module @samp{(math bessel)}. First we need to write the appropriate
963 glue code to convert the arguments and return values of the functions
964 from Scheme to C and back. Additionally, we need a function that will
965 add them to the set of Guile primitives. Because this is just an
966 example, we will only implement this for the @code{j0} function.
968 @c FIXME::martin: Change all gh_ references to their scm_ equivalents.
972 #include <libguile.h>
977 return scm_double2num (j0 (scm_num2dbl (x, "j0")));
983 scm_c_define_gsubr ("j0", 1, 0, 0, j0_wrapper);
987 We can already try to bring this into action by manually calling the low
988 level functions for performing dynamic linking. The C source file needs
989 to be compiled into a shared library. Here is how to do it on
990 GNU/Linux, please refer to the @code{libtool} documentation for how to
991 create dynamically linkable libraries portably.
994 gcc -shared -o libbessel.so -fPIC bessel.c
1000 (define bessel-lib (dynamic-link "./libbessel.so"))
1001 (dynamic-call "init_math_bessel" bessel-lib)
1003 @result{} 0.223890779141236
1006 The filename @file{./libbessel.so} should be pointing to the shared
1007 library produced with the @code{gcc} command above, of course. The
1008 second line of the Guile interaction will call the
1009 @code{init_math_bessel} function which in turn will register the C
1010 function @code{j0_wrapper} with the Guile interpreter under the name
1011 @code{j0}. This function becomes immediately available and we can call
1014 Fun, isn't it? But we are only half way there. This is what
1015 @code{apropos} has to say about @code{j0}:
1019 @print{} (guile-user): j0 #<primitive-procedure j0>
1022 As you can see, @code{j0} is contained in the root module, where all
1023 the other Guile primitives like @code{display}, etc live. In general,
1024 a primitive is put into whatever module is the @dfn{current module} at
1025 the time @code{scm_c_define_gsubr} is called.
1027 A compiled module should have a specially named @dfn{module init
1028 function}. Guile knows about this special name and will call that
1029 function automatically after having linked in the shared library. For
1030 our example, we replace @code{init_math_bessel} with the following code in
1035 init_math_bessel (void *unused)
1037 scm_c_define_gsubr ("j0", 1, 0, 0, j0_wrapper);
1038 scm_c_export ("j0", NULL);
1042 scm_init_math_bessel_module ()
1044 scm_c_define_module ("math bessel", init_math_bessel, NULL);
1048 The general pattern for the name of a module init function is:
1049 @samp{scm_init_}, followed by the name of the module where the
1050 individual hierarchical components are concatenated with underscores,
1051 followed by @samp{_module}.
1053 After @file{libbessel.so} has been rebuilt, we need to place the shared
1054 library into the right place.
1056 Once the module has been correctly installed, it should be possible to
1060 guile> (load-extension "./libbessel.so" "scm_init_math_bessel_module")
1061 guile> (use-modules (math bessel))
1064 guile> (apropos "j0")
1065 @print{} (math bessel): j0 #<primitive-procedure j0>
1070 @deffn {Scheme Procedure} load-extension lib init
1071 @deffnx {C Function} scm_load_extension (lib, init)
1072 Load and initialize the extension designated by LIB and INIT.
1073 When there is no pre-registered function for LIB/INIT, this is
1077 (dynamic-call INIT (dynamic-link LIB))
1080 When there is a pre-registered function, that function is called
1083 Normally, there is no pre-registered function. This option exists
1084 only for situations where dynamic linking is unavailable or unwanted.
1085 In that case, you would statically link your program with the desired
1086 library, and register its init function right after Guile has been
1089 LIB should be a string denoting a shared library without any file type
1090 suffix such as ".so". The suffix is provided automatically. It
1091 should also not contain any directory components. Libraries that
1092 implement Guile Extensions should be put into the normal locations for
1093 shared libraries. We recommend to use the naming convention
1094 libguile-bla-blum for a extension related to a module `(bla blum)'.
1096 The normal way for a extension to be used is to write a small Scheme
1097 file that defines a module, and to load the extension into this
1098 module. When the module is auto-loaded, the extension is loaded as
1102 (define-module (bla blum))
1104 (load-extension "libguile-bla-blum" "bla_init_blum")
1109 @subsection Variables
1112 Each module has its own hash table, sometimes known as an @dfn{obarray},
1113 that maps the names defined in that module to their corresponding
1116 A variable is a box-like object that can hold any Scheme value. It is
1117 said to be @dfn{undefined} if its box holds a special Scheme value that
1118 denotes undefined-ness (which is different from all other Scheme values,
1119 including for example @code{#f}); otherwise the variable is
1122 On its own, a variable object is anonymous. A variable is said to be
1123 @dfn{bound} when it is associated with a name in some way, usually a
1124 symbol in a module obarray. When this happens, the relationship is
1125 mutual: the variable is bound to the name (in that module), and the name
1126 (in that module) is bound to the variable.
1128 (That's the theory, anyway. In practice, defined-ness and bound-ness
1129 sometimes get confused, because Lisp and Scheme implementations have
1130 often conflated --- or deliberately drawn no distinction between --- a
1131 name that is unbound and a name that is bound to a variable whose value
1132 is undefined. We will try to be clear about the difference and explain
1133 any confusion where it is unavoidable.)
1135 Variables do not have a read syntax. Most commonly they are created and
1136 bound implicitly by @code{define} expressions: a top-level @code{define}
1137 expression of the form
1140 (define @var{name} @var{value})
1144 creates a variable with initial value @var{value} and binds it to the
1145 name @var{name} in the current module. But they can also be created
1146 dynamically by calling one of the constructor procedures
1147 @code{make-variable} and @code{make-undefined-variable}.
1149 First-class variables are especially useful for interacting with the
1150 current module system (@pxref{The Guile module system}).
1152 @deffn {Scheme Procedure} make-undefined-variable
1153 @deffnx {C Function} scm_make_undefined_variable ()
1154 Return a variable that is initially unbound.
1157 @deffn {Scheme Procedure} make-variable init
1158 @deffnx {C Function} scm_make_variable (init)
1159 Return a variable initialized to value @var{init}.
1162 @deffn {Scheme Procedure} variable-bound? var
1163 @deffnx {C Function} scm_variable_bound_p (var)
1164 Return @code{#t} iff @var{var} is bound to a value.
1165 Throws an error if @var{var} is not a variable object.
1168 @deffn {Scheme Procedure} variable-ref var
1169 @deffnx {C Function} scm_variable_ref (var)
1170 Dereference @var{var} and return its value.
1171 @var{var} must be a variable object; see @code{make-variable}
1172 and @code{make-undefined-variable}.
1175 @deffn {Scheme Procedure} variable-set! var val
1176 @deffnx {C Function} scm_variable_set_x (var, val)
1177 Set the value of the variable @var{var} to @var{val}.
1178 @var{var} must be a variable object, @var{val} can be any
1179 value. Return an unspecified value.
1182 @deffn {Scheme Procedure} variable? obj
1183 @deffnx {C Function} scm_variable_p (obj)
1184 Return @code{#t} iff @var{obj} is a variable object, else
1190 @c TeX-master: "guile.texi"