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