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}
397 Load @var{module} whenever @var{symbol} is accessed.
399 @item #:export @var{list}
400 Export all identifiers in @var{list}, which must be a list of symbols.
401 This is equivalent to @code{(export @var{list})} in the module body.
404 Tell Guile not to record information for procedure backtraces when
405 executing the procedures in this module.
408 Create a @dfn{pure} module, that is a module which does not contain any
409 of the standard procedure bindings except for the syntax forms. This is
410 useful if you want to create @dfn{safe} modules, that is modules which
411 do not know anything about dangerous procedures.
417 @deffn syntax export variable @dots{}
418 Add all @var{variable}s (which must be symbols) to the list of exported
419 bindings of the current module.
422 @c begin (scm-doc-string "boot-9.scm" "define-public")
423 @deffn syntax define-public @dots{}
424 Equivalent to @code{(begin (define foo ...) (export foo))}.
428 @node Module System Reflection
429 @subsubsection Module System Reflection
431 The previous sections have described a declarative view of the module
432 system. You can also work with it programmatically by accessing and
433 modifying various parts of the Scheme objects that Guile uses to
434 implement the module system.
436 At any time, there is a @dfn{current module}. This module is the one
437 where a top-level @code{define} and similar syntax will add new
438 bindings. You can find other module objects with @code{resolve-module},
441 These module objects can be used as the second argument to @code{eval}.
443 @deffn {Scheme Procedure} current-module
444 Return the current module object.
447 @deffn {Scheme Procedure} set-current-module module
448 Set the current module to @var{module} and return
449 the previous current module.
452 @deffn {Scheme Procedure} resolve-module name
453 Find the module named @var{name} and return it. When it has not already
454 been defined, try to auto-load it. When it can't be found that way
455 either, create an empty module. The name is a list of symbols.
458 @deffn {Scheme Procedure} resolve-interface name
459 Find the module named @var{name} as with @code{resolve-module} and
460 return its interface. The interface of a module is also a module
461 object, but it contains only the exported bindings.
464 @deffn {Scheme Procedure} module-use! module interface
465 Add @var{interface} to the front of the use-list of @var{module}. Both
466 arguments should be module objects, and @var{interface} should very
467 likely be a module returned by @code{resolve-interface}.
470 @node Module System Quirks
471 @subsubsection Module System Quirks
473 Although the programming interfaces are relatively stable, the Guile
474 module system itself is still evolving. Here are some situations where
475 usage surpasses design.
480 When using a module which exports a macro definition, the other module
481 must export all bindings the macro expansion uses, too, because the
482 expanded code would otherwise not be able to see these definitions and
483 issue a ``variable unbound'' error, or worse, would use another binding
484 which might be present in the scope of the expansion.
487 When two or more used modules export bindings with the same names, the
488 last accessed module wins, and the exported binding of that last module
489 will silently be used. This might lead to hard-to-find errors because
490 wrong procedures or variables are used. To avoid this kind of
491 @dfn{name-clash} situation, use a custom interface specification
492 (@pxref{Using Guile Modules}). (We include this entry for the possible
493 benefit of users of Guile versions previous to 1.5.0, when custom
494 interfaces were added to the module system.)
497 [Add other quirks here.]
502 @node Included Guile Modules
503 @subsubsection Included Guile Modules
505 @c FIXME::martin: Review me!
507 Some modules are included in the Guile distribution; here are references
508 to the entries in this manual which describe them in more detail:
512 boot-9 is Guile's initialization module, and it is always loaded when
516 Mikael Djurfeldt's source-level debugging support for Guile
517 (@pxref{Debugging Features}).
519 @item (ice-9 threads)
520 Guile's support for multi threaded execution (@pxref{Scheduling}).
523 Line- and character-delimited input (@pxref{Line/Delimited}).
526 Block string input/output (@pxref{Block Reading and Writing}).
528 @item (ice-9 documentation)
529 Online documentation (REFFIXME).
532 A library providing a lot of useful list and pair processing
533 procedures (@pxref{SRFI-1}).
536 Support for @code{and-let*} (@pxref{SRFI-2}).
539 Support for homogeneous numeric vectors (@pxref{SRFI-4}).
542 Support for some additional string port procedures (@pxref{SRFI-6}).
545 Multiple-value handling with @code{receive} (@pxref{SRFI-8}).
548 Record definition with @code{define-record-type} (@pxref{SRFI-9}).
551 Read hash extension @code{#,()} (@pxref{SRFI-10}).
554 Multiple-value handling with @code{let-values} and @code{let-values*}
558 String library (@pxref{SRFI-13}).
561 Character-set library (@pxref{SRFI-14}).
564 Getter-with-setter support (@pxref{SRFI-17}).
567 Convenient syntax for partial application (@pxref{SRFI-26})
570 This module contains hooks for using Aubrey Jaffer's portable Scheme
571 library SLIB from Guile (@pxref{SLIB}).
573 @c FIXME::martin: This module is not in the distribution. Remove it
576 This module contains hooks for using Aubrey Jaffer's symbolic math
577 package Jacal from Guile (@pxref{JACAL}).
581 @node Accessing Modules from C
582 @subsubsection Accessing Modules from C
584 The last sections have described how modules are used in Scheme code,
585 which is the recommended way of creating and accessing modules. You
586 can also work with modules from C, but it is more cumbersome.
588 The following procedures are available.
590 @deftypefn {C Procedure} SCM scm_current_module ()
591 Return the module that is the @emph{current module}.
594 @deftypefn {C Procedure} SCM scm_set_current_module (SCM @var{module})
595 Set the current module to @var{module} and return the previous current
599 @deftypefn {C Procedure} SCM scm_c_call_with_current_module (SCM @var{module}, SCM (*@var{func})(void *), void *@var{data})
600 Call @var{func} and make @var{module} the current module during the
601 call. The argument @var{data} is passed to @var{func}. The return
602 value of @code{scm_c_call_with_current_module} is the return value of
606 @deftypefn {C Procedure} SCM scm_c_lookup (const char *@var{name})
607 Return the variable bound to the symbol indicated by @var{name} in the
608 current module. If there is no such binding or the symbol is not
609 bound to a variable, signal an error.
612 @deftypefn {C Procedure} SCM scm_lookup (SCM @var{name})
613 Like @code{scm_c_lookup}, but the symbol is specified directly.
616 @deftypefn {C Procedure} SCM scm_c_module_lookup (SCM @var{module}, const char *@var{name})
617 @deftypefnx {C Procedure} SCM scm_module_lookup (SCM @var{module}, SCM @var{name})
618 Like @code{scm_c_lookup} and @code{scm_lookup}, but the specified
619 module is used instead of the current one.
622 @deftypefn {C Procedure} SCM scm_c_define (const char *@var{name}, SCM @var{val})
623 Bind the symbol indicated by @var{name} to a variable in the current
624 module and set that variable to @var{val}. When @var{name} is already
625 bound to a variable, use that. Else create a new variable.
628 @deftypefn {C Procedure} SCM scm_define (SCM @var{name}, SCM @var{val})
629 Like @code{scm_c_define}, but the symbol is specified directly.
632 @deftypefn {C Procedure} SCM scm_c_module_define (SCM @var{module}, const char *@var{name}, SCM @var{val})
633 @deftypefnx {C Procedure} SCM scm_module_define (SCM @var{module}, SCM @var{name}, SCM @var{val})
634 Like @code{scm_c_define} and @code{scm_define}, but the specified
635 module is used instead of the current one.
638 @deftypefn {C Procedure} SCM scm_module_reverse_lookup (SCM @var{module}, SCM @var{variable})
639 Find the symbol that is bound to @var{variable} in @var{module}. When no such binding is found, return @var{#f}.
642 @deftypefn {C Procedure} SCM scm_c_define_module (const char *@var{name}, void (*@var{init})(void *), void *@var{data})
643 Define a new module named @var{name} and make it current while
644 @var{init} is called, passing it @var{data}. Return the module.
646 The parameter @var{name} is a string with the symbols that make up
647 the module name, separated by spaces. For example, @samp{"foo bar"} names
648 the module @samp{(foo bar)}.
650 When there already exists a module named @var{name}, it is used
651 unchanged, otherwise, an empty module is created.
654 @deftypefn {C Procedure} SCM scm_c_resolve_module (const char *@var{name})
655 Find the module name @var{name} and return it. When it has not
656 already been defined, try to auto-load it. When it can't be found
657 that way either, create an empty module. The name is interpreted as
658 for @code{scm_c_define_module}.
661 @deftypefn {C Procedure} SCM scm_resolve_module (SCM @var{name})
662 Like @code{scm_c_resolve_module}, but the name is given as a real list
666 @deftypefn {C Procedure} SCM scm_c_use_module (const char *@var{name})
667 Add the module named @var{name} to the uses list of the current
668 module, as with @code{(use-modules @var{name})}. The name is
669 interpreted as for @code{scm_c_define_module}.
672 @deftypefn {C Procedure} SCM scm_c_export (const char *@var{name}, ...)
673 Add the bindings designated by @var{name}, ... to the public interface
674 of the current module. The list of names is terminated by
678 @node Dynamic Libraries
679 @subsection Dynamic Libraries
681 Most modern Unices have something called @dfn{shared libraries}. This
682 ordinarily means that they have the capability to share the executable
683 image of a library between several running programs to save memory and
684 disk space. But generally, shared libraries give a lot of additional
685 flexibility compared to the traditional static libraries. In fact,
686 calling them `dynamic' libraries is as correct as calling them `shared'.
688 Shared libraries really give you a lot of flexibility in addition to the
689 memory and disk space savings. When you link a program against a shared
690 library, that library is not closely incorporated into the final
691 executable. Instead, the executable of your program only contains
692 enough information to find the needed shared libraries when the program
693 is actually run. Only then, when the program is starting, is the final
694 step of the linking process performed. This means that you need not
695 recompile all programs when you install a new, only slightly modified
696 version of a shared library. The programs will pick up the changes
697 automatically the next time they are run.
699 Now, when all the necessary machinery is there to perform part of the
700 linking at run-time, why not take the next step and allow the programmer
701 to explicitly take advantage of it from within his program? Of course,
702 many operating systems that support shared libraries do just that, and
703 chances are that Guile will allow you to access this feature from within
704 your Scheme programs. As you might have guessed already, this feature
705 is called @dfn{dynamic linking}.@footnote{Some people also refer to the
706 final linking stage at program startup as `dynamic linking', so if you
707 want to make yourself perfectly clear, it is probably best to use the
708 more technical term @dfn{dlopening}, as suggested by Gordon Matzigkeit
709 in his libtool documentation.}
711 As with many aspects of Guile, there is a low-level way to access the
712 dynamic linking apparatus, and a more high-level interface that
713 integrates dynamically linked libraries into the module system.
716 * Low level dynamic linking::
717 * Compiled Code Modules::
718 * Dynamic Linking and Compiled Code Modules::
721 @node Low level dynamic linking
722 @subsubsection Low level dynamic linking
724 When using the low level procedures to do your dynamic linking, you have
725 complete control over which library is loaded when and what gets done
728 @deffn {Scheme Procedure} dynamic-link library
729 @deffnx {C Function} scm_dynamic_link (library)
730 Find the shared library denoted by @var{library} (a string) and link it
731 into the running Guile application. When everything works out, return a
732 Scheme object suitable for representing the linked object file.
733 Otherwise an error is thrown. How object files are searched is system
736 Normally, @var{library} is just the name of some shared library file
737 that will be searched for in the places where shared libraries usually
738 reside, such as in @file{/usr/lib} and @file{/usr/local/lib}.
741 @deffn {Scheme Procedure} dynamic-object? obj
742 @deffnx {C Function} scm_dynamic_object_p (obj)
743 Return @code{#t} if @var{obj} is a dynamic library handle, or @code{#f}
747 @deffn {Scheme Procedure} dynamic-unlink dobj
748 @deffnx {C Function} scm_dynamic_unlink (dobj)
749 Unlink the indicated object file from the application. The
750 argument @var{dobj} must have been obtained by a call to
751 @code{dynamic-link}. After @code{dynamic-unlink} has been
752 called on @var{dobj}, its content is no longer accessible.
755 @deffn {Scheme Procedure} dynamic-func name dobj
756 @deffnx {C Function} scm_dynamic_func (name, dobj)
757 Search the dynamic object @var{dobj} for the C function
758 indicated by the string @var{name} and return some Scheme
759 handle that can later be used with @code{dynamic-call} to
760 actually call the function.
762 Regardless whether your C compiler prepends an underscore @samp{_} to
763 the global names in a program, you should @strong{not} include this
764 underscore in @var{function}. Guile knows whether the underscore is
765 needed or not and will add it when necessary.
768 @deffn {Scheme Procedure} dynamic-call func dobj
769 @deffnx {C Function} scm_dynamic_call (func, dobj)
770 Call the C function indicated by @var{func} and @var{dobj}.
771 The function is passed no arguments and its return value is
772 ignored. When @var{function} is something returned by
773 @code{dynamic-func}, call that function and ignore @var{dobj}.
774 When @var{func} is a string , look it up in @var{dynobj}; this
777 (dynamic-call (dynamic-func @var{func} @var{dobj}) #f)
780 Interrupts are deferred while the C function is executing (with
781 @code{SCM_DEFER_INTS}/@code{SCM_ALLOW_INTS}).
784 @deffn {Scheme Procedure} dynamic-args-call func dobj args
785 @deffnx {C Function} scm_dynamic_args_call (func, dobj, args)
786 Call the C function indicated by @var{func} and @var{dobj},
787 just like @code{dynamic-call}, but pass it some arguments and
788 return its return value. The C function is expected to take
789 two arguments and return an @code{int}, just like @code{main}:
791 int c_func (int argc, char **argv);
794 The parameter @var{args} must be a list of strings and is
795 converted into an array of @code{char *}. The array is passed
796 in @var{argv} and its size in @var{argc}. The return value is
797 converted to a Scheme number and returned from the call to
798 @code{dynamic-args-call}.
801 When dynamic linking is disabled or not supported on your system,
802 the above functions throw errors, but they are still available.
804 Here is a small example that works on GNU/Linux:
807 (define libc-obj (dynamic-link "libc.so"))
809 @result{} #<dynamic-object "libc.so">
810 (dynamic-args-call 'rand libc-obj '())
812 (dynamic-unlink libc-obj)
814 @result{} #<dynamic-object "libc.so" (unlinked)>
817 As you can see, after calling @code{dynamic-unlink} on a dynamically
818 linked library, it is marked as @samp{(unlinked)} and you are no longer
819 able to use it with @code{dynamic-call}, etc. Whether the library is
820 really removed from you program is system-dependent and will generally
821 not happen when some other parts of your program still use it. In the
822 example above, @code{libc} is almost certainly not removed from your
823 program because it is badly needed by almost everything.
825 The functions to call a function from a dynamically linked library,
826 @code{dynamic-call} and @code{dynamic-args-call}, are not very powerful.
827 They are mostly intended to be used for calling specially written
828 initialization functions that will then add new primitives to Guile.
829 For example, we do not expect that you will dynamically link
830 @file{libX11} with @code{dynamic-link} and then construct a beautiful
831 graphical user interface just by using @code{dynamic-call} and
832 @code{dynamic-args-call}. Instead, the usual way would be to write a
833 special Guile<->X11 glue library that has intimate knowledge about both
834 Guile and X11 and does whatever is necessary to make them inter-operate
835 smoothly. This glue library could then be dynamically linked into a
836 vanilla Guile interpreter and activated by calling its initialization
837 function. That function would add all the new types and primitives to
838 the Guile interpreter that it has to offer.
840 From this setup the next logical step is to integrate these glue
841 libraries into the module system of Guile so that you can load new
842 primitives into a running system just as you can load new Scheme code.
844 There is, however, another possibility to get a more thorough access to
845 the functions contained in a dynamically linked library. Anthony Green
846 has written @file{libffi}, a library that implements a @dfn{foreign
847 function interface} for a number of different platforms. With it, you
848 can extend the Spartan functionality of @code{dynamic-call} and
849 @code{dynamic-args-call} considerably. There is glue code available in
850 the Guile contrib archive to make @file{libffi} accessible from Guile.
852 @node Compiled Code Modules
853 @subsubsection Putting Compiled Code into Modules
855 The new primitives that you add to Guile with
856 @code{scm_c_define_gsubr} (@pxref{Primitive Procedures}) or with any
857 of the other mechanisms are placed into the @code{(guile-user)} module
858 by default. However, it is also possible to put new primitives into
861 The mechanism for doing so is not very well thought out and is likely to
862 change when the module system of Guile itself is revised, but it is
863 simple and useful enough to document it as it stands.
865 What @code{scm_c_define_gsubr} and the functions used by the snarfer
866 really do is to add the new primitives to whatever module is the
867 @emph{current module} when they are called. This is analogous to the
868 way Scheme code is put into modules: the @code{define-module} expression
869 at the top of a Scheme source file creates a new module and makes it the
870 current module while the rest of the file is evaluated. The
871 @code{define} expressions in that file then add their new definitions to
874 Therefore, all we need to do is to make sure that the right module is
875 current when calling @code{scm_c_define_gsubr} for our new primitives.
877 @node Dynamic Linking and Compiled Code Modules
878 @subsubsection Dynamic Linking and Compiled Code Modules
880 The most interesting application of dynamically linked libraries is
881 probably to use them for providing @emph{compiled code modules} to
882 Scheme programs. As much fun as programming in Scheme is, every now and
883 then comes the need to write some low-level C stuff to make Scheme even
886 Not only can you put these new primitives into their own module (see the
887 previous section), you can even put them into a shared library that is
888 only then linked to your running Guile image when it is actually
891 An example will hopefully make everything clear. Suppose we want to
892 make the Bessel functions of the C library available to Scheme in the
893 module @samp{(math bessel)}. First we need to write the appropriate
894 glue code to convert the arguments and return values of the functions
895 from Scheme to C and back. Additionally, we need a function that will
896 add them to the set of Guile primitives. Because this is just an
897 example, we will only implement this for the @code{j0} function.
899 @c FIXME::martin: Change all gh_ references to their scm_ equivalents.
903 #include <libguile.h>
908 return scm_double2num (j0 (scm_num2dbl (x, "j0")));
914 scm_c_define_gsubr ("j0", 1, 0, 0, j0_wrapper);
918 We can already try to bring this into action by manually calling the low
919 level functions for performing dynamic linking. The C source file needs
920 to be compiled into a shared library. Here is how to do it on
921 GNU/Linux, please refer to the @code{libtool} documentation for how to
922 create dynamically linkable libraries portably.
925 gcc -shared -o libbessel.so -fPIC bessel.c
931 (define bessel-lib (dynamic-link "./libbessel.so"))
932 (dynamic-call "init_math_bessel" bessel-lib)
934 @result{} 0.223890779141236
937 The filename @file{./libbessel.so} should be pointing to the shared
938 library produced with the @code{gcc} command above, of course. The
939 second line of the Guile interaction will call the
940 @code{init_math_bessel} function which in turn will register the C
941 function @code{j0_wrapper} with the Guile interpreter under the name
942 @code{j0}. This function becomes immediately available and we can call
945 Fun, isn't it? But we are only half way there. This is what
946 @code{apropos} has to say about @code{j0}:
950 @print{} (guile-user): j0 #<primitive-procedure j0>
953 As you can see, @code{j0} is contained in the root module, where all
954 the other Guile primitives like @code{display}, etc live. In general,
955 a primitive is put into whatever module is the @dfn{current module} at
956 the time @code{scm_c_define_gsubr} is called.
958 A compiled module should have a specially named @dfn{module init
959 function}. Guile knows about this special name and will call that
960 function automatically after having linked in the shared library. For
961 our example, we replace @code{init_math_bessel} with the following code in
966 init_math_bessel (void *unused)
968 scm_c_define_gsubr ("j0", 1, 0, 0, j0_wrapper);
969 scm_c_export ("j0", NULL);
973 scm_init_math_bessel_module ()
975 scm_c_define_module ("math bessel", init_math_bessel, NULL);
979 The general pattern for the name of a module init function is:
980 @samp{scm_init_}, followed by the name of the module where the
981 individual hierarchical components are concatenated with underscores,
982 followed by @samp{_module}.
984 After @file{libbessel.so} has been rebuilt, we need to place the shared
985 library into the right place.
987 Once the module has been correctly installed, it should be possible to
991 guile> (load-extension "./libbessel.so" "scm_init_math_bessel_module")
992 guile> (use-modules (math bessel))
995 guile> (apropos "j0")
996 @print{} (math bessel): j0 #<primitive-procedure j0>
1001 @deffn {Scheme Procedure} load-extension lib init
1002 @deffnx {C Function} scm_load_extension (lib, init)
1003 Load and initialize the extension designated by LIB and INIT.
1004 When there is no pre-registered function for LIB/INIT, this is
1008 (dynamic-call INIT (dynamic-link LIB))
1011 When there is a pre-registered function, that function is called
1014 Normally, there is no pre-registered function. This option exists
1015 only for situations where dynamic linking is unavailable or unwanted.
1016 In that case, you would statically link your program with the desired
1017 library, and register its init function right after Guile has been
1020 LIB should be a string denoting a shared library without any file type
1021 suffix such as ".so". The suffix is provided automatically. It
1022 should also not contain any directory components. Libraries that
1023 implement Guile Extensions should be put into the normal locations for
1024 shared libraries. We recommend to use the naming convention
1025 libguile-bla-blum for a extension related to a module `(bla blum)'.
1027 The normal way for a extension to be used is to write a small Scheme
1028 file that defines a module, and to load the extension into this
1029 module. When the module is auto-loaded, the extension is loaded as
1033 (define-module (bla blum))
1035 (load-extension "libguile-bla-blum" "bla_init_blum")
1040 @subsection Variables
1043 Each module has its own hash table, sometimes known as an @dfn{obarray},
1044 that maps the names defined in that module to their corresponding
1047 A variable is a box-like object that can hold any Scheme value. It is
1048 said to be @dfn{undefined} if its box holds a special Scheme value that
1049 denotes undefined-ness (which is different from all other Scheme values,
1050 including for example @code{#f}); otherwise the variable is
1053 On its own, a variable object is anonymous. A variable is said to be
1054 @dfn{bound} when it is associated with a name in some way, usually a
1055 symbol in a module obarray. When this happens, the relationship is
1056 mutual: the variable is bound to the name (in that module), and the name
1057 (in that module) is bound to the variable.
1059 (That's the theory, anyway. In practice, defined-ness and bound-ness
1060 sometimes get confused, because Lisp and Scheme implementations have
1061 often conflated --- or deliberately drawn no distinction between --- a
1062 name that is unbound and a name that is bound to a variable whose value
1063 is undefined. We will try to be clear about the difference and explain
1064 any confusion where it is unavoidable.)
1066 Variables do not have a read syntax. Most commonly they are created and
1067 bound implicitly by @code{define} expressions: a top-level @code{define}
1068 expression of the form
1071 (define @var{name} @var{value})
1075 creates a variable with initial value @var{value} and binds it to the
1076 name @var{name} in the current module. But they can also be created
1077 dynamically by calling one of the constructor procedures
1078 @code{make-variable} and @code{make-undefined-variable}.
1080 First-class variables are especially useful for interacting with the
1081 current module system (@pxref{The Guile module system}).
1083 @deffn {Scheme Procedure} make-undefined-variable
1084 @deffnx {C Function} scm_make_undefined_variable ()
1085 Return a variable that is initially unbound.
1088 @deffn {Scheme Procedure} make-variable init
1089 @deffnx {C Function} scm_make_variable (init)
1090 Return a variable initialized to value @var{init}.
1093 @deffn {Scheme Procedure} variable-bound? var
1094 @deffnx {C Function} scm_variable_bound_p (var)
1095 Return @code{#t} iff @var{var} is bound to a value.
1096 Throws an error if @var{var} is not a variable object.
1099 @deffn {Scheme Procedure} variable-ref var
1100 @deffnx {C Function} scm_variable_ref (var)
1101 Dereference @var{var} and return its value.
1102 @var{var} must be a variable object; see @code{make-variable}
1103 and @code{make-undefined-variable}.
1106 @deffn {Scheme Procedure} variable-set! var val
1107 @deffnx {C Function} scm_variable_set_x (var, val)
1108 Set the value of the variable @var{var} to @var{val}.
1109 @var{var} must be a variable object, @var{val} can be any
1110 value. Return an unspecified value.
1113 @deffn {Scheme Procedure} variable? obj
1114 @deffnx {C Function} scm_variable_p (obj)
1115 Return @code{#t} iff @var{obj} is a variable object, else
1121 @c TeX-master: "guile.texi"