[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Guile-commits] GNU Guile branch, master, updated. release_1-9-9-38-g726
|
From: |
Andy Wingo |
|
Subject: |
[Guile-commits] GNU Guile branch, master, updated. release_1-9-9-38-g726b8ba |
|
Date: |
Thu, 01 Apr 2010 22:21:46 +0000 |
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "GNU Guile".
http://git.savannah.gnu.org/cgit/guile.git/commit/?id=726b8ba3fd5de26d5eb8c6567cc0b15bc1a7193e
The branch, master has been updated
via 726b8ba3fd5de26d5eb8c6567cc0b15bc1a7193e (commit)
from 7b702b5391fb54114307636934e4d28101655093 (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit 726b8ba3fd5de26d5eb8c6567cc0b15bc1a7193e
Author: Andy Wingo <address@hidden>
Date: Fri Apr 2 00:23:24 2010 +0200
add api-foreign.texi
* doc/ref/api-foreign.texi: New file.
* doc/ref/api-modules.texi: Reorganize bits about dynamic linking into
api-foreign.
* doc/ref/guile.texi:
* doc/ref/Makefile.am: Adapt to api-foreign.texi.
-----------------------------------------------------------------------
Summary of changes:
doc/ref/Makefile.am | 1 +
doc/ref/api-foreign.texi | 512 +++++++++++++++++++++++++++++
doc/ref/api-modules.texi | 809 ++++++++++------------------------------------
doc/ref/guile.texi | 2 +
4 files changed, 679 insertions(+), 645 deletions(-)
create mode 100644 doc/ref/api-foreign.texi
diff --git a/doc/ref/Makefile.am b/doc/ref/Makefile.am
index 9188bcb..1277216 100644
--- a/doc/ref/Makefile.am
+++ b/doc/ref/Makefile.am
@@ -40,6 +40,7 @@ guile_TEXINFOS = preface.texi \
api-binding.texi \
api-control.texi \
api-io.texi \
+ api-foreign.texi \
api-lalr.texi \
api-evaluation.texi \
api-memory.texi \
diff --git a/doc/ref/api-foreign.texi b/doc/ref/api-foreign.texi
new file mode 100644
index 0000000..e1b7854
--- /dev/null
+++ b/doc/ref/api-foreign.texi
@@ -0,0 +1,512 @@
address@hidden -*-texinfo-*-
address@hidden This is part of the GNU Guile Reference Manual.
address@hidden Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2007,
2008, 2009, 2010
address@hidden Free Software Foundation, Inc.
address@hidden See the file guile.texi for copying conditions.
+
address@hidden
address@hidden Foreign Function Interface
address@hidden Foreign Function Interface
address@hidden foreign function interface
address@hidden ffi
+
+The more one hacks in Scheme, the more one realizes that there are
+actually two computational worlds: one which is warm and alive, that
+land of parentheses, and one cold and dead, the land of C and its ilk.
+
+But yet we as programmers live in both worlds, and Guile itself is half
+implemented in C. So it is that Guile's living half pays respect to its
+dead counterpart, via a spectrum of interfaces to C ranging from dynamic
+loading of Scheme primitives to dynamic binding of stock C library
+prodedures.
+
address@hidden
+* Foreign Libraries:: Dynamically linking to libraries.
+* Foreign Functions:: Simple calls to C procedures.
+* C Extensions:: Extending Guile in C with loadable modules.
+* Modules and Extensions:: Loading C extensions into modules.
+* Foreign Values:: Accessing global variables.
+* Dynamic FFI:: Fu.
address@hidden menu
+
+
address@hidden Foreign Libraries
address@hidden Foreign Libraries
+
+Most modern Unices have something called @dfn{shared libraries}. This
+ordinarily means that they have the capability to share the executable
+image of a library between several running programs to save memory and
+disk space. But generally, shared libraries give a lot of additional
+flexibility compared to the traditional static libraries. In fact,
+calling them `dynamic' libraries is as correct as calling them `shared'.
+
+Shared libraries really give you a lot of flexibility in addition to the
+memory and disk space savings. When you link a program against a shared
+library, that library is not closely incorporated into the final
+executable. Instead, the executable of your program only contains
+enough information to find the needed shared libraries when the program
+is actually run. Only then, when the program is starting, is the final
+step of the linking process performed. This means that you need not
+recompile all programs when you install a new, only slightly modified
+version of a shared library. The programs will pick up the changes
+automatically the next time they are run.
+
+Now, when all the necessary machinery is there to perform part of the
+linking at run-time, why not take the next step and allow the programmer
+to explicitly take advantage of it from within his program? Of course,
+many operating systems that support shared libraries do just that, and
+chances are that Guile will allow you to access this feature from within
+your Scheme programs. As you might have guessed already, this feature
+is called @dfn{dynamic address@hidden people also refer to the
+final linking stage at program startup as `dynamic linking', so if you
+want to make yourself perfectly clear, it is probably best to use the
+more technical term @dfn{dlopening}, as suggested by Gordon Matzigkeit
+in his libtool documentation.}
+
+We titled this section ``foreign libraries'' because although the name
+``foreign'' doesn't leak into the API, the world of C really is foreign
+to Scheme -- and that estrangement extends to components of foreign
+libraries as well, as we see in future sections.
+
address@hidden {Scheme Procedure} dynamic-link [library]
address@hidden {C Function} scm_dynamic_link (library)
+Find the shared library denoted by @var{library} (a string) and link it
+into the running Guile application. When everything works out, return a
+Scheme object suitable for representing the linked object file.
+Otherwise an error is thrown. How object files are searched is system
+dependent.
+
+Normally, @var{library} is just the name of some shared library file
+that will be searched for in the places where shared libraries usually
+reside, such as in @file{/usr/lib} and @file{/usr/local/lib}.
+
+When @var{library} is omitted, a @dfn{global symbol handle} is returned. This
+handle provides access to the symbols available to the program at run-time,
+including those exported by the program itself and the shared libraries already
+loaded.
address@hidden deffn
+
address@hidden {Scheme Procedure} dynamic-object? obj
address@hidden {C Function} scm_dynamic_object_p (obj)
+Return @code{#t} if @var{obj} is a dynamic library handle, or @code{#f}
+otherwise.
address@hidden deffn
+
address@hidden {Scheme Procedure} dynamic-unlink dobj
address@hidden {C Function} scm_dynamic_unlink (dobj)
+Unlink the indicated object file from the application. The
+argument @var{dobj} must have been obtained by a call to
address@hidden After @code{dynamic-unlink} has been
+called on @var{dobj}, its content is no longer accessible.
address@hidden deffn
+
address@hidden
+(define libc-obj (dynamic-link "libc.so"))
+libc-obj
address@hidden #<dynamic-object "libc.so">
+(dynamic-args-call 'rand libc-obj '())
address@hidden 269167349
+(dynamic-unlink libc-obj)
+libc-obj
address@hidden #<dynamic-object "libc.so" (unlinked)>
address@hidden smallexample
+
+As you can see, after calling @code{dynamic-unlink} on a dynamically
+linked library, it is marked as @samp{(unlinked)} and you are no longer
+able to use it with @code{dynamic-call}, etc. Whether the library is
+really removed from you program is system-dependent and will generally
+not happen when some other parts of your program still use it. In the
+example above, @code{libc} is almost certainly not removed from your
+program because it is badly needed by almost everything.
+
+When dynamic linking is disabled or not supported on your system,
+the above functions throw errors, but they are still available.
+
+
address@hidden Foreign Functions
address@hidden Foreign Functions
+
address@hidden {Scheme Procedure} dynamic-func name dobj
address@hidden {C Function} scm_dynamic_func (name, dobj)
+Return a ``handle'' for the func @var{name} in the shared object referred to
+by @var{dobj}. The handle can be passed to @code{dynamic-call} to
+actually call the function.
+
+Regardless whether your C compiler prepends an underscore @samp{_} to the
global
+names in a program, you should @strong{not} include this underscore in
address@hidden since it will be added automatically when necessary.
address@hidden deffn
+
address@hidden {Scheme Procedure} dynamic-call func dobj
address@hidden {C Function} scm_dynamic_call (func, dobj)
+Call the C function indicated by @var{func} and @var{dobj}.
+The function is passed no arguments and its return value is
+ignored. When @var{function} is something returned by
address@hidden, call that function and ignore @var{dobj}.
+When @var{func} is a string , look it up in @var{dynobj}; this
+is equivalent to
address@hidden
+(dynamic-call (dynamic-func @var{func} @var{dobj}) #f)
address@hidden smallexample
+
+Interrupts are deferred while the C function is executing (with
address@hidden/@code{SCM_ALLOW_INTS}).
address@hidden deffn
+
address@hidden {Scheme Procedure} dynamic-args-call func dobj args
address@hidden {C Function} scm_dynamic_args_call (func, dobj, args)
+Call the C function indicated by @var{func} and @var{dobj},
+just like @code{dynamic-call}, but pass it some arguments and
+return its return value. The C function is expected to take
+two arguments and return an @code{int}, just like @code{main}:
address@hidden
+int c_func (int argc, char **argv);
address@hidden smallexample
+
+The parameter @var{args} must be a list of strings and is
+converted into an array of @code{char *}. The array is passed
+in @var{argv} and its size in @var{argc}. The return value is
+converted to a Scheme number and returned from the call to
address@hidden
address@hidden deffn
+
+The functions to call a function from a dynamically linked library,
address@hidden and @code{dynamic-args-call}, are not very powerful.
+They are mostly intended to be used for calling specially written
+initialization functions that will then add new primitives to Guile.
+For example, we do not expect that you will dynamically link
address@hidden with @code{dynamic-link} and then construct a beautiful
+graphical user interface just by using @code{dynamic-call} and
address@hidden Instead, the usual way would be to write a
+special Guile<->X11 glue library that has intimate knowledge about both
+Guile and X11 and does whatever is necessary to make them inter-operate
+smoothly. This glue library could then be dynamically linked into a
+vanilla Guile interpreter and activated by calling its initialization
+function. That function would add all the new types and primitives to
+the Guile interpreter that it has to offer.
+
+From this setup the next logical step is to integrate these glue
+libraries into the module system of Guile so that you can load new
+primitives into a running system just as you can load new Scheme code.
+
+[foreshadowing regarding dynamic ffi]
+
address@hidden {Scheme Procedure} load-extension lib init
address@hidden {C Function} scm_load_extension (lib, init)
+Load and initialize the extension designated by LIB and INIT.
+When there is no pre-registered function for LIB/INIT, this is
+equivalent to
+
address@hidden
+(dynamic-call INIT (dynamic-link LIB))
address@hidden lisp
+
+When there is a pre-registered function, that function is called
+instead.
+
+Normally, there is no pre-registered function. This option exists
+only for situations where dynamic linking is unavailable or unwanted.
+In that case, you would statically link your program with the desired
+library, and register its init function right after Guile has been
+initialized.
+
+LIB should be a string denoting a shared library without any file type
+suffix such as ".so". The suffix is provided automatically. It
+should also not contain any directory components. Libraries that
+implement Guile Extensions should be put into the normal locations for
+shared libraries. We recommend to use the naming convention
+libguile-bla-blum for a extension related to a module `(bla blum)'.
+
+The normal way for a extension to be used is to write a small Scheme
+file that defines a module, and to load the extension into this
+module. When the module is auto-loaded, the extension is loaded as
+well. For example,
+
address@hidden
+(define-module (bla blum))
+
+(load-extension "libguile-bla-blum" "bla_init_blum")
address@hidden lisp
address@hidden deffn
+
address@hidden C Extensions
address@hidden C Extensions
+
+The most interesting application of dynamically linked libraries is
+probably to use them for providing @emph{compiled code modules} to
+Scheme programs. As much fun as programming in Scheme is, every now and
+then comes the need to write some low-level C stuff to make Scheme even
+more fun.
+
+Not only can you put these new primitives into their own module (see the
+previous section), you can even put them into a shared library that is
+only then linked to your running Guile image when it is actually
+needed.
+
+An example will hopefully make everything clear. Suppose we want to
+make the Bessel functions of the C library available to Scheme in the
+module @samp{(math bessel)}. First we need to write the appropriate
+glue code to convert the arguments and return values of the functions
+from Scheme to C and back. Additionally, we need a function that will
+add them to the set of Guile primitives. Because this is just an
+example, we will only implement this for the @code{j0} function.
+
address@hidden
+#include <math.h>
+#include <libguile.h>
+
+SCM
+j0_wrapper (SCM x)
address@hidden
+ return scm_from_double (j0 (scm_to_double (x, "j0")));
address@hidden
+
+void
+init_math_bessel ()
address@hidden
+ scm_c_define_gsubr ("j0", 1, 0, 0, j0_wrapper);
address@hidden
address@hidden smallexample
+
+We can already try to bring this into action by manually calling the low
+level functions for performing dynamic linking. The C source file needs
+to be compiled into a shared library. Here is how to do it on
+GNU/Linux, please refer to the @code{libtool} documentation for how to
+create dynamically linkable libraries portably.
+
address@hidden
+gcc -shared -o libbessel.so -fPIC bessel.c
address@hidden smallexample
+
+Now fire up Guile:
+
address@hidden
+(define bessel-lib (dynamic-link "./libbessel.so"))
+(dynamic-call "init_math_bessel" bessel-lib)
+(j0 2)
address@hidden 0.223890779141236
address@hidden lisp
+
+The filename @file{./libbessel.so} should be pointing to the shared
+library produced with the @code{gcc} command above, of course. The
+second line of the Guile interaction will call the
address@hidden function which in turn will register the C
+function @code{j0_wrapper} with the Guile interpreter under the name
address@hidden This function becomes immediately available and we can call
+it from Scheme.
+
+Fun, isn't it? But we are only half way there. This is what
address@hidden has to say about @code{j0}:
+
address@hidden
+(apropos "j0")
address@hidden (guile-user): j0 #<primitive-procedure j0>
address@hidden smallexample
+
+As you can see, @code{j0} is contained in the root module, where all
+the other Guile primitives like @code{display}, etc live. In general,
+a primitive is put into whatever module is the @dfn{current module} at
+the time @code{scm_c_define_gsubr} is called.
+
+A compiled module should have a specially named @dfn{module init
+function}. Guile knows about this special name and will call that
+function automatically after having linked in the shared library. For
+our example, we replace @code{init_math_bessel} with the following code in
address@hidden:
+
address@hidden
+void
+init_math_bessel (void *unused)
address@hidden
+ scm_c_define_gsubr ("j0", 1, 0, 0, j0_wrapper);
+ scm_c_export ("j0", NULL);
address@hidden
+
+void
+scm_init_math_bessel_module ()
address@hidden
+ scm_c_define_module ("math bessel", init_math_bessel, NULL);
address@hidden
address@hidden smallexample
+
+The general pattern for the name of a module init function is:
address@hidden, followed by the name of the module where the
+individual hierarchical components are concatenated with underscores,
+followed by @samp{_module}.
+
+After @file{libbessel.so} has been rebuilt, we need to place the shared
+library into the right place.
+
+Once the module has been correctly installed, it should be possible to
+use it like this:
+
address@hidden
+guile> (load-extension "./libbessel.so" "scm_init_math_bessel_module")
+guile> (use-modules (math bessel))
+guile> (j0 2)
+0.223890779141236
+guile> (apropos "j0")
address@hidden (math bessel): j0 #<primitive-procedure j0>
address@hidden smallexample
+
+That's it!
+
address@hidden {Scheme Procedure} load-extension lib init
address@hidden {C Function} scm_load_extension (lib, init)
+Load and initialize the extension designated by LIB and INIT.
+When there is no pre-registered function for LIB/INIT, this is
+equivalent to
+
address@hidden
+(dynamic-call INIT (dynamic-link LIB))
address@hidden lisp
+
+When there is a pre-registered function, that function is called
+instead.
+
+Normally, there is no pre-registered function. This option exists
+only for situations where dynamic linking is unavailable or unwanted.
+In that case, you would statically link your program with the desired
+library, and register its init function right after Guile has been
+initialized.
+
+LIB should be a string denoting a shared library without any file type
+suffix such as ".so". The suffix is provided automatically. It
+should also not contain any directory components. Libraries that
+implement Guile Extensions should be put into the normal locations for
+shared libraries. We recommend to use the naming convention
+libguile-bla-blum for a extension related to a module `(bla blum)'.
+
+The normal way for a extension to be used is to write a small Scheme
+file that defines a module, and to load the extension into this
+module. When the module is auto-loaded, the extension is loaded as
+well. For example,
+
address@hidden
+(define-module (bla blum))
+
+(load-extension "libguile-bla-blum" "bla_init_blum")
address@hidden lisp
address@hidden deffn
+
address@hidden Modules and Extensions
address@hidden Modules and Extensions
+
+The new primitives that you add to Guile with @code{scm_c_define_gsubr}
+(@pxref{Primitive Procedures}) or with any of the other mechanisms are
+placed into the module that is current when the
address@hidden is executed. Extensions loaded from the REPL,
+for example, will be placed into the @code{(guile-user)} module, if the
+REPL module was not changed.
+
+To define C primitives within a specific module, the simplest way is:
+
address@hidden
+(define-module (foo bar))
+(load-extension "foobar-c-code" "foo_bar_init")
address@hidden example
+
+When loaded with @code{(use-modules (foo bar))}, the
address@hidden call looks for the @file{foobar-c-code.so} (etc)
+object file in the standard system locations, such as @file{/usr/lib}
+or @file{/usr/local/lib}.
+
+If someone installs your module to a non-standard location then the
+object file won't be found. You can address this by inserting the
+install location in the @file{foo/bar.scm} file. This is convenient
+for the user and also guarantees the intended object is read, even if
+stray older or newer versions are in the loader's path.
+
+The usual way to specify an install location is with a @code{prefix}
+at the configure stage, for instance @samp{./configure prefix=/opt}
+results in library files as say @file{/opt/lib/foobar-c-code.so}.
+When using Autoconf (@pxref{Top, , Introduction, autoconf, The GNU
+Autoconf Manual}), the library location is in a @code{libdir}
+variable. Its value is intended to be expanded by @command{make}, and
+can by substituted into a source file like @file{foo.scm.in}
+
address@hidden
+(define-module (foo bar))
+(load-extension "XXlibdirXX/foobar-c-code" "foo_bar_init")
address@hidden example
+
address@hidden
+with the following in a @file{Makefile}, using @command{sed}
+(@pxref{Top, , Introduction, sed, SED, A Stream Editor}),
+
address@hidden
+foo.scm: foo.scm.in
+ sed 's|XXlibdirXX|$(libdir)|' <foo.scm.in >foo.scm
address@hidden example
+
+The actual pattern @code{XXlibdirXX} is arbitrary, it's only something
+which doesn't otherwise occur. If several modules need the value, it
+can be easier to create one @file{foo/config.scm} with a define of the
address@hidden location, and use that as required.
+
address@hidden
+(define-module (foo config))
+(define-public foo-config-libdir "XXlibdirXX"")
address@hidden example
+
+Such a file might have other locations too, for instance a data
+directory for auxiliary files, or @code{localedir} if the module has
+its own @code{gettext} message catalogue
+(@pxref{Internationalization}).
+
+When installing multiple C code objects, it can be convenient to put
+them in a subdirectory of @code{libdir}, thus giving for example
address@hidden/usr/lib/foo/some-obj.so}. If the objects are only meant to be
+used through the module, then a subdirectory keeps them out of sight.
+
+It will be noted all of the above requires that the Scheme code to be
+found in @code{%load-path} (@pxref{Build Config}). Presently it's
+left up to the system administrator or each user to augment that path
+when installing Guile modules in non-default locations. But having
+reached the Scheme code, that code should take care of hitting any of
+its own private files etc.
+
+Presently there's no convention for having a Guile version number in
+module C code filenames or directories. This is primarily because
+there's no established principles for two versions of Guile to be
+installed under the same prefix (eg. two both under @file{/usr}).
+Assuming upward compatibility is maintained then this should be
+unnecessary, and if compatibility is not maintained then it's highly
+likely a package will need to be revisited anyway.
+
+The present suggestion is that modules should assume when they're
+installed under a particular @code{prefix} that there's a single
+version of Guile there, and the @code{guile-config} at build time has
+the necessary information about it. C code or Scheme code might adapt
+itself accordingly (allowing for features not available in an older
+version for instance).
+
+
address@hidden Foreign Values
address@hidden Foreign Values
+
address@hidden {Scheme Procedure} dynamic-pointer name type dobj [len]
address@hidden {C Function} scm_dynamic_pointer (name, type, dobj, len)
+Return a ``handle'' for the pointer @var{name} in the shared object referred to
+by @var{dobj}. The handle aliases a C value, and is declared to be of type
address@hidden Valid types are defined in the @code{(system foreign)} module.
+
+This facility works by asking the dynamic linker for the address of a symbol,
+then assuming that it aliases a value of a given type. Obviously, the user must
+be very careful to ensure that the value actually is of the declared type, or
+bad things will happen.
+
+Regardless whether your C compiler prepends an underscore @samp{_} to the
global
+names in a program, you should @strong{not} include this underscore in
address@hidden since it will be added automatically when necessary.
address@hidden deffn
+
+
address@hidden Dynamic FFI
address@hidden Dynamic FFI
+
+TBD
+
address@hidden Local Variables:
address@hidden TeX-master: "guile.texi"
address@hidden End:
diff --git a/doc/ref/api-modules.texi b/doc/ref/api-modules.texi
index aa6eaa3..35483b4 100644
--- a/doc/ref/api-modules.texi
+++ b/doc/ref/api-modules.texi
@@ -42,121 +42,20 @@ In addition, Guile offers variables as first-class
objects. They can
be used for interacting with the module system.
@menu
-* provide and require:: The SLIB feature mechanism.
-* Environments:: R5RS top-level environments.
-* The Guile module system:: How Guile does it.
-* Dynamic Libraries:: Loading libraries of compiled code at run time.
-* Variables:: First-class variables.
address@hidden menu
-
address@hidden provide and require
address@hidden provide and require
-
-Aubrey Jaffer, mostly to support his portable Scheme library SLIB,
-implemented a provide/require mechanism for many Scheme implementations.
-Library files in SLIB @emph{provide} a feature, and when user programs
address@hidden that feature, the library file is loaded in.
-
-For example, the file @file{random.scm} in the SLIB package contains the
-line
-
address@hidden
-(provide 'random)
address@hidden lisp
-
-so to use its procedures, a user would type
-
address@hidden
-(require 'random)
address@hidden lisp
-
-and they would magically become available, @emph{but still have the same
-names!} So this method is nice, but not as good as a full-featured
-module system.
-
-When SLIB is used with Guile, provide and require can be used to access
-its facilities.
-
address@hidden Environments
address@hidden Environments
address@hidden environment
-
-Scheme, as defined in R5RS, does @emph{not} have a full module system.
-However it does define the concept of a top-level @dfn{environment}.
-Such an environment maps identifiers (symbols) to Scheme objects such
-as procedures and lists: @ref{About Closure}. In other words, it
-implements a set of @dfn{bindings}.
-
-Environments in R5RS can be passed as the second argument to
address@hidden (@pxref{Fly Evaluation}). Three procedures are defined to
-return environments: @code{scheme-report-environment},
address@hidden and @code{interaction-environment} (@pxref{Fly
-Evaluation}).
-
-In addition, in Guile any module can be used as an R5RS environment,
-i.e., passed as the second argument to @code{eval}.
-
-Note: the following two procedures are available only when the
address@hidden(ice-9 r5rs)} module is loaded:
-
address@hidden
-(use-modules (ice-9 r5rs))
address@hidden lisp
-
address@hidden {Scheme Procedure} scheme-report-environment version
address@hidden {Scheme Procedure} null-environment version
address@hidden must be the exact integer `5', corresponding to revision
-5 of the Scheme report (the Revised^5 Report on Scheme).
address@hidden returns a specifier for an
-environment that is empty except for all bindings defined in the
-report that are either required or both optional and supported by the
-implementation. @code{null-environment} returns a specifier for an
-environment that is empty except for the (syntactic) bindings for all
-syntactic keywords defined in the report that are either required or
-both optional and supported by the implementation.
-
-Currently Guile does not support values of @var{version} for other
-revisions of the report.
-
-The effect of assigning (through the use of @code{eval}) a variable
-bound in a @code{scheme-report-environment} (for example @code{car})
-is unspecified. Currently the environments specified by
address@hidden are not immutable in Guile.
address@hidden deffn
-
address@hidden The Guile module system
address@hidden The Guile module system
-
-The Guile module system extends the concept of environments, discussed
-in the previous section, with mechanisms to define, use and customise
-sets of bindings.
-
-In 1996 Tom Lord implemented a full-featured module system for Guile which
-allows loading Scheme source files into a private name space. This system has
-been available since at least Guile version 1.1.
-
-For Guile version 1.5.0 and later, the system has been improved to have better
-integration from C code, more fine-grained user control over interfaces, and
-documentation.
-
-Although it is anticipated that the module system implementation will
-change in the future, the Scheme programming interface described in this
-manual should be considered stable. The C programming interface is
-considered relatively stable, although at the time of this writing,
-there is still some flux.
-
address@hidden
* General Information about Modules:: Guile module basics.
* Using Guile Modules:: How to use existing modules.
* Creating Guile Modules:: How to package your code into modules.
* Module System Reflection:: Accessing module objects at run-time.
* Included Guile Modules:: Which modules come with Guile?
-* Accessing Modules from C:: How to work with modules with C code.
* R6RS Version References:: Using version numbers with modules.
+* Accessing Modules from C:: How to work with modules with C code.
+* Variables:: First-class variables.
+* provide and require:: The SLIB feature mechanism.
+* Environments:: R5RS top-level environments.
@end menu
@node General Information about Modules
address@hidden General Information about Modules
address@hidden General Information about Modules
A Guile module can be thought of as a collection of named procedures,
variables and macros. More precisely, it is a set of @dfn{bindings}
@@ -220,7 +119,7 @@ definition option (@pxref{Creating Guile Modules}).
@node Using Guile Modules
address@hidden Using Guile Modules
address@hidden Using Guile Modules
To use a Guile module is to access either its public interface or a
custom interface (@pxref{General Information about Modules}). Both
@@ -376,7 +275,7 @@ last resort.
@end deffn
@node Creating Guile Modules
address@hidden Creating Guile Modules
address@hidden Creating Guile Modules
When you want to create your own modules, you have to take the following
steps:
@@ -618,7 +517,7 @@ imported by the current module from some other module.
@end deffn
@node Module System Reflection
address@hidden Module System Reflection
address@hidden Module System Reflection
The previous sections have described a declarative view of the module
system. You can also work with it programmatically by accessing and
@@ -673,7 +572,7 @@ likely be a module returned by @code{resolve-interface}.
@node Included Guile Modules
address@hidden Included Guile Modules
address@hidden Included Guile Modules
@c FIXME::martin: Review me!
@@ -796,106 +695,8 @@ library SLIB from Guile (@pxref{SLIB}).
@end table
address@hidden Accessing Modules from C
address@hidden Accessing Modules from C
-
-The last sections have described how modules are used in Scheme code,
-which is the recommended way of creating and accessing modules. You
-can also work with modules from C, but it is more cumbersome.
-
-The following procedures are available.
-
address@hidden {C Procedure} SCM scm_current_module ()
-Return the module that is the @emph{current module}.
address@hidden deftypefn
-
address@hidden {C Procedure} SCM scm_set_current_module (SCM @var{module})
-Set the current module to @var{module} and return the previous current
-module.
address@hidden deftypefn
-
address@hidden {C Procedure} SCM scm_c_call_with_current_module (SCM
@var{module}, SCM (address@hidden)(void *), void address@hidden)
-Call @var{func} and make @var{module} the current module during the
-call. The argument @var{data} is passed to @var{func}. The return
-value of @code{scm_c_call_with_current_module} is the return value of
address@hidden
address@hidden deftypefn
-
address@hidden {C Procedure} SCM scm_c_lookup (const char address@hidden)
-Return the variable bound to the symbol indicated by @var{name} in the
-current module. If there is no such binding or the symbol is not
-bound to a variable, signal an error.
address@hidden deftypefn
-
address@hidden {C Procedure} SCM scm_lookup (SCM @var{name})
-Like @code{scm_c_lookup}, but the symbol is specified directly.
address@hidden deftypefn
-
address@hidden {C Procedure} SCM scm_c_module_lookup (SCM @var{module}, const
char address@hidden)
address@hidden {C Procedure} SCM scm_module_lookup (SCM @var{module}, SCM
@var{name})
-Like @code{scm_c_lookup} and @code{scm_lookup}, but the specified
-module is used instead of the current one.
address@hidden deftypefn
-
address@hidden {C Procedure} SCM scm_c_define (const char address@hidden, SCM
@var{val})
-Bind the symbol indicated by @var{name} to a variable in the current
-module and set that variable to @var{val}. When @var{name} is already
-bound to a variable, use that. Else create a new variable.
address@hidden deftypefn
-
address@hidden {C Procedure} SCM scm_define (SCM @var{name}, SCM @var{val})
-Like @code{scm_c_define}, but the symbol is specified directly.
address@hidden deftypefn
-
address@hidden {C Procedure} SCM scm_c_module_define (SCM @var{module}, const
char address@hidden, SCM @var{val})
address@hidden {C Procedure} SCM scm_module_define (SCM @var{module}, SCM
@var{name}, SCM @var{val})
-Like @code{scm_c_define} and @code{scm_define}, but the specified
-module is used instead of the current one.
address@hidden deftypefn
-
address@hidden {C Procedure} SCM scm_module_reverse_lookup (SCM @var{module},
SCM @var{variable})
-Find the symbol that is bound to @var{variable} in @var{module}. When no such
binding is found, return @var{#f}.
address@hidden deftypefn
-
address@hidden {C Procedure} SCM scm_c_define_module (const char
address@hidden, void (address@hidden)(void *), void address@hidden)
-Define a new module named @var{name} and make it current while
address@hidden is called, passing it @var{data}. Return the module.
-
-The parameter @var{name} is a string with the symbols that make up
-the module name, separated by spaces. For example, @samp{"foo bar"} names
-the module @samp{(foo bar)}.
-
-When there already exists a module named @var{name}, it is used
-unchanged, otherwise, an empty module is created.
address@hidden deftypefn
-
address@hidden {C Procedure} SCM scm_c_resolve_module (const char
address@hidden)
-Find the module name @var{name} and return it. When it has not
-already been defined, try to auto-load it. When it can't be found
-that way either, create an empty module. The name is interpreted as
-for @code{scm_c_define_module}.
address@hidden deftypefn
-
address@hidden {C Procedure} SCM scm_resolve_module (SCM @var{name})
-Like @code{scm_c_resolve_module}, but the name is given as a real list
-of symbols.
address@hidden deftypefn
-
address@hidden {C Procedure} SCM scm_c_use_module (const char address@hidden)
-Add the module named @var{name} to the uses list of the current
-module, as with @code{(use-modules @var{name})}. The name is
-interpreted as for @code{scm_c_define_module}.
address@hidden deftypefn
-
address@hidden {C Procedure} SCM scm_c_export (const char address@hidden, ...)
-Add the bindings designated by @var{name}, ... to the public interface
-of the current module. The list of names is terminated by
address@hidden
address@hidden deftypefn
-
-
@node R6RS Version References
address@hidden R6RS Version References
address@hidden R6RS Version References
Guile's module system includes support for locating modules based on
a declared version specifier of the same form as the one described in
@@ -978,458 +779,102 @@ expressions:
@end lisp
address@hidden Dynamic Libraries
address@hidden Dynamic Libraries
-
-Most modern Unices have something called @dfn{shared libraries}. This
-ordinarily means that they have the capability to share the executable
-image of a library between several running programs to save memory and
-disk space. But generally, shared libraries give a lot of additional
-flexibility compared to the traditional static libraries. In fact,
-calling them `dynamic' libraries is as correct as calling them `shared'.
-
-Shared libraries really give you a lot of flexibility in addition to the
-memory and disk space savings. When you link a program against a shared
-library, that library is not closely incorporated into the final
-executable. Instead, the executable of your program only contains
-enough information to find the needed shared libraries when the program
-is actually run. Only then, when the program is starting, is the final
-step of the linking process performed. This means that you need not
-recompile all programs when you install a new, only slightly modified
-version of a shared library. The programs will pick up the changes
-automatically the next time they are run.
-
-Now, when all the necessary machinery is there to perform part of the
-linking at run-time, why not take the next step and allow the programmer
-to explicitly take advantage of it from within his program? Of course,
-many operating systems that support shared libraries do just that, and
-chances are that Guile will allow you to access this feature from within
-your Scheme programs. As you might have guessed already, this feature
-is called @dfn{dynamic address@hidden people also refer to the
-final linking stage at program startup as `dynamic linking', so if you
-want to make yourself perfectly clear, it is probably best to use the
-more technical term @dfn{dlopening}, as suggested by Gordon Matzigkeit
-in his libtool documentation.}
-
-As with many aspects of Guile, there is a low-level way to access the
-dynamic linking apparatus, and a more high-level interface that
-integrates dynamically linked libraries into the module system.
-
address@hidden
-* Low level dynamic linking::
-* Compiled Code Modules::
-* Dynamic Linking and Compiled Code Modules::
-* Compiled Code Installation::
address@hidden menu
-
address@hidden Low level dynamic linking
address@hidden Low level dynamic linking
-
-When using the low level procedures to do your dynamic linking, you have
-complete control over which library is loaded when and what gets done
-with it.
-
address@hidden {Scheme Procedure} dynamic-link [library]
address@hidden {C Function} scm_dynamic_link (library)
-Find the shared library denoted by @var{library} (a string) and link it
-into the running Guile application. When everything works out, return a
-Scheme object suitable for representing the linked object file.
-Otherwise an error is thrown. How object files are searched is system
-dependent.
-
-Normally, @var{library} is just the name of some shared library file
-that will be searched for in the places where shared libraries usually
-reside, such as in @file{/usr/lib} and @file{/usr/local/lib}.
-
-When @var{library} is omitted, a @dfn{global symbol handle} is returned. This
-handle provides access to the symbols available to the program at run-time,
-including those exported by the program itself and the shared libraries already
-loaded.
address@hidden deffn
-
address@hidden {Scheme Procedure} dynamic-object? obj
address@hidden {C Function} scm_dynamic_object_p (obj)
-Return @code{#t} if @var{obj} is a dynamic library handle, or @code{#f}
-otherwise.
address@hidden deffn
-
address@hidden {Scheme Procedure} dynamic-unlink dobj
address@hidden {C Function} scm_dynamic_unlink (dobj)
-Unlink the indicated object file from the application. The
-argument @var{dobj} must have been obtained by a call to
address@hidden After @code{dynamic-unlink} has been
-called on @var{dobj}, its content is no longer accessible.
address@hidden deffn
-
address@hidden {Scheme Procedure} dynamic-func name dobj
address@hidden {C Function} scm_dynamic_func (name, dobj)
-Search the dynamic object @var{dobj} for the C function
-indicated by the string @var{name} and return some Scheme
-handle that can later be used with @code{dynamic-call} to
-actually call the function.
-
-Regardless whether your C compiler prepends an underscore @samp{_} to
-the global names in a program, you should @strong{not} include this
-underscore in @var{function}. Guile knows whether the underscore is
-needed or not and will add it when necessary.
address@hidden deffn
-
address@hidden {Scheme Procedure} dynamic-call func dobj
address@hidden {C Function} scm_dynamic_call (func, dobj)
-Call the C function indicated by @var{func} and @var{dobj}.
-The function is passed no arguments and its return value is
-ignored. When @var{function} is something returned by
address@hidden, call that function and ignore @var{dobj}.
-When @var{func} is a string , look it up in @var{dynobj}; this
-is equivalent to
address@hidden
-(dynamic-call (dynamic-func @var{func} @var{dobj}) #f)
address@hidden smallexample
-
-Interrupts are deferred while the C function is executing (with
address@hidden/@code{SCM_ALLOW_INTS}).
address@hidden deffn
-
address@hidden {Scheme Procedure} dynamic-args-call func dobj args
address@hidden {C Function} scm_dynamic_args_call (func, dobj, args)
-Call the C function indicated by @var{func} and @var{dobj},
-just like @code{dynamic-call}, but pass it some arguments and
-return its return value. The C function is expected to take
-two arguments and return an @code{int}, just like @code{main}:
address@hidden
-int c_func (int argc, char **argv);
address@hidden smallexample
-
-The parameter @var{args} must be a list of strings and is
-converted into an array of @code{char *}. The array is passed
-in @var{argv} and its size in @var{argc}. The return value is
-converted to a Scheme number and returned from the call to
address@hidden
address@hidden deffn
-
-When dynamic linking is disabled or not supported on your system,
-the above functions throw errors, but they are still available.
-
-Here is a small example that works on GNU/Linux:
-
address@hidden
-(define libc-obj (dynamic-link "libc.so"))
-libc-obj
address@hidden #<dynamic-object "libc.so">
-(dynamic-args-call 'rand libc-obj '())
address@hidden 269167349
-(dynamic-unlink libc-obj)
-libc-obj
address@hidden #<dynamic-object "libc.so" (unlinked)>
address@hidden smallexample
-
-As you can see, after calling @code{dynamic-unlink} on a dynamically
-linked library, it is marked as @samp{(unlinked)} and you are no longer
-able to use it with @code{dynamic-call}, etc. Whether the library is
-really removed from you program is system-dependent and will generally
-not happen when some other parts of your program still use it. In the
-example above, @code{libc} is almost certainly not removed from your
-program because it is badly needed by almost everything.
-
-The functions to call a function from a dynamically linked library,
address@hidden and @code{dynamic-args-call}, are not very powerful.
-They are mostly intended to be used for calling specially written
-initialization functions that will then add new primitives to Guile.
-For example, we do not expect that you will dynamically link
address@hidden with @code{dynamic-link} and then construct a beautiful
-graphical user interface just by using @code{dynamic-call} and
address@hidden Instead, the usual way would be to write a
-special Guile<->X11 glue library that has intimate knowledge about both
-Guile and X11 and does whatever is necessary to make them inter-operate
-smoothly. This glue library could then be dynamically linked into a
-vanilla Guile interpreter and activated by calling its initialization
-function. That function would add all the new types and primitives to
-the Guile interpreter that it has to offer.
-
-From this setup the next logical step is to integrate these glue
-libraries into the module system of Guile so that you can load new
-primitives into a running system just as you can load new Scheme code.
-
-There is, however, another possibility to get a more thorough access to
-the functions contained in a dynamically linked library. Anthony Green
-has written @file{libffi}, a library that implements a @dfn{foreign
-function interface} for a number of different platforms. With it, you
-can extend the Spartan functionality of @code{dynamic-call} and
address@hidden considerably. There is glue code available in
-the Guile contrib archive to make @file{libffi} accessible from Guile.
-
address@hidden Compiled Code Modules
address@hidden Putting Compiled Code into Modules
-
-The new primitives that you add to Guile with
address@hidden (@pxref{Primitive Procedures}) or with any
-of the other mechanisms are placed into the @code{(guile-user)} module
-by default. However, it is also possible to put new primitives into
-other modules.
-
-The mechanism for doing so is not very well thought out and is likely to
-change when the module system of Guile itself is revised, but it is
-simple and useful enough to document it as it stands.
-
-What @code{scm_c_define_gsubr} and the functions used by the snarfer
-really do is to add the new primitives to whatever module is the
address@hidden module} when they are called. This is analogous to the
-way Scheme code is put into modules: the @code{define-module} expression
-at the top of a Scheme source file creates a new module and makes it the
-current module while the rest of the file is evaluated. The
address@hidden expressions in that file then add their new definitions to
-this current module.
-
-Therefore, all we need to do is to make sure that the right module is
-current when calling @code{scm_c_define_gsubr} for our new primitives.
-
address@hidden Dynamic Linking and Compiled Code Modules
address@hidden Dynamic Linking and Compiled Code Modules
-
-The most interesting application of dynamically linked libraries is
-probably to use them for providing @emph{compiled code modules} to
-Scheme programs. As much fun as programming in Scheme is, every now and
-then comes the need to write some low-level C stuff to make Scheme even
-more fun.
-
-Not only can you put these new primitives into their own module (see the
-previous section), you can even put them into a shared library that is
-only then linked to your running Guile image when it is actually
-needed.
-
-An example will hopefully make everything clear. Suppose we want to
-make the Bessel functions of the C library available to Scheme in the
-module @samp{(math bessel)}. First we need to write the appropriate
-glue code to convert the arguments and return values of the functions
-from Scheme to C and back. Additionally, we need a function that will
-add them to the set of Guile primitives. Because this is just an
-example, we will only implement this for the @code{j0} function.
-
address@hidden FIXME::martin: Change all gh_ references to their scm_
equivalents.
-
address@hidden
-#include <math.h>
-#include <libguile.h>
-
-SCM
-j0_wrapper (SCM x)
address@hidden
- return scm_double2num (j0 (scm_num2dbl (x, "j0")));
address@hidden
-
-void
-init_math_bessel ()
address@hidden
- scm_c_define_gsubr ("j0", 1, 0, 0, j0_wrapper);
address@hidden
address@hidden smallexample
-
-We can already try to bring this into action by manually calling the low
-level functions for performing dynamic linking. The C source file needs
-to be compiled into a shared library. Here is how to do it on
-GNU/Linux, please refer to the @code{libtool} documentation for how to
-create dynamically linkable libraries portably.
-
address@hidden
-gcc -shared -o libbessel.so -fPIC bessel.c
address@hidden smallexample
-
-Now fire up Guile:
-
address@hidden
-(define bessel-lib (dynamic-link "./libbessel.so"))
-(dynamic-call "init_math_bessel" bessel-lib)
-(j0 2)
address@hidden 0.223890779141236
address@hidden lisp
-
-The filename @file{./libbessel.so} should be pointing to the shared
-library produced with the @code{gcc} command above, of course. The
-second line of the Guile interaction will call the
address@hidden function which in turn will register the C
-function @code{j0_wrapper} with the Guile interpreter under the name
address@hidden This function becomes immediately available and we can call
-it from Scheme.
-
-Fun, isn't it? But we are only half way there. This is what
address@hidden has to say about @code{j0}:
-
address@hidden
-(apropos "j0")
address@hidden (guile-user): j0 #<primitive-procedure j0>
address@hidden smallexample
-
-As you can see, @code{j0} is contained in the root module, where all
-the other Guile primitives like @code{display}, etc live. In general,
-a primitive is put into whatever module is the @dfn{current module} at
-the time @code{scm_c_define_gsubr} is called.
-
-A compiled module should have a specially named @dfn{module init
-function}. Guile knows about this special name and will call that
-function automatically after having linked in the shared library. For
-our example, we replace @code{init_math_bessel} with the following code in
address@hidden:
-
address@hidden
-void
-init_math_bessel (void *unused)
address@hidden
- scm_c_define_gsubr ("j0", 1, 0, 0, j0_wrapper);
- scm_c_export ("j0", NULL);
address@hidden
-
-void
-scm_init_math_bessel_module ()
address@hidden
- scm_c_define_module ("math bessel", init_math_bessel, NULL);
address@hidden
address@hidden smallexample
-
-The general pattern for the name of a module init function is:
address@hidden, followed by the name of the module where the
-individual hierarchical components are concatenated with underscores,
-followed by @samp{_module}.
-
-After @file{libbessel.so} has been rebuilt, we need to place the shared
-library into the right place.
-
-Once the module has been correctly installed, it should be possible to
-use it like this:
-
address@hidden
-guile> (load-extension "./libbessel.so" "scm_init_math_bessel_module")
-guile> (use-modules (math bessel))
-guile> (j0 2)
-0.223890779141236
-guile> (apropos "j0")
address@hidden (math bessel): j0 #<primitive-procedure j0>
address@hidden smallexample
-
-That's it!
address@hidden Accessing Modules from C
address@hidden Accessing Modules from C
address@hidden {Scheme Procedure} load-extension lib init
address@hidden {C Function} scm_load_extension (lib, init)
-Load and initialize the extension designated by LIB and INIT.
-When there is no pre-registered function for LIB/INIT, this is
-equivalent to
+The last sections have described how modules are used in Scheme code,
+which is the recommended way of creating and accessing modules. You
+can also work with modules from C, but it is more cumbersome.
address@hidden
-(dynamic-call INIT (dynamic-link LIB))
address@hidden lisp
+The following procedures are available.
-When there is a pre-registered function, that function is called
-instead.
address@hidden {C Procedure} SCM scm_current_module ()
+Return the module that is the @emph{current module}.
address@hidden deftypefn
-Normally, there is no pre-registered function. This option exists
-only for situations where dynamic linking is unavailable or unwanted.
-In that case, you would statically link your program with the desired
-library, and register its init function right after Guile has been
-initialized.
address@hidden {C Procedure} SCM scm_set_current_module (SCM @var{module})
+Set the current module to @var{module} and return the previous current
+module.
address@hidden deftypefn
-LIB should be a string denoting a shared library without any file type
-suffix such as ".so". The suffix is provided automatically. It
-should also not contain any directory components. Libraries that
-implement Guile Extensions should be put into the normal locations for
-shared libraries. We recommend to use the naming convention
-libguile-bla-blum for a extension related to a module `(bla blum)'.
address@hidden {C Procedure} SCM scm_c_call_with_current_module (SCM
@var{module}, SCM (address@hidden)(void *), void address@hidden)
+Call @var{func} and make @var{module} the current module during the
+call. The argument @var{data} is passed to @var{func}. The return
+value of @code{scm_c_call_with_current_module} is the return value of
address@hidden
address@hidden deftypefn
-The normal way for a extension to be used is to write a small Scheme
-file that defines a module, and to load the extension into this
-module. When the module is auto-loaded, the extension is loaded as
-well. For example,
address@hidden {C Procedure} SCM scm_c_lookup (const char address@hidden)
+Return the variable bound to the symbol indicated by @var{name} in the
+current module. If there is no such binding or the symbol is not
+bound to a variable, signal an error.
address@hidden deftypefn
address@hidden
-(define-module (bla blum))
address@hidden {C Procedure} SCM scm_lookup (SCM @var{name})
+Like @code{scm_c_lookup}, but the symbol is specified directly.
address@hidden deftypefn
-(load-extension "libguile-bla-blum" "bla_init_blum")
address@hidden lisp
address@hidden deffn
address@hidden {C Procedure} SCM scm_c_module_lookup (SCM @var{module}, const
char address@hidden)
address@hidden {C Procedure} SCM scm_module_lookup (SCM @var{module}, SCM
@var{name})
+Like @code{scm_c_lookup} and @code{scm_lookup}, but the specified
+module is used instead of the current one.
address@hidden deftypefn
address@hidden {C Procedure} SCM scm_c_define (const char address@hidden, SCM
@var{val})
+Bind the symbol indicated by @var{name} to a variable in the current
+module and set that variable to @var{val}. When @var{name} is already
+bound to a variable, use that. Else create a new variable.
address@hidden deftypefn
address@hidden Compiled Code Installation
address@hidden Compiled Code Installation
address@hidden {C Procedure} SCM scm_define (SCM @var{name}, SCM @var{val})
+Like @code{scm_c_define}, but the symbol is specified directly.
address@hidden deftypefn
-The simplest way to write a module using compiled C code is
address@hidden {C Procedure} SCM scm_c_module_define (SCM @var{module}, const
char address@hidden, SCM @var{val})
address@hidden {C Procedure} SCM scm_module_define (SCM @var{module}, SCM
@var{name}, SCM @var{val})
+Like @code{scm_c_define} and @code{scm_define}, but the specified
+module is used instead of the current one.
address@hidden deftypefn
address@hidden
-(define-module (foo bar))
-(load-extension "foobar-c-code" "foo_bar_init")
address@hidden example
address@hidden {C Procedure} SCM scm_module_reverse_lookup (SCM @var{module},
SCM @var{variable})
+Find the symbol that is bound to @var{variable} in @var{module}. When no such
binding is found, return @var{#f}.
address@hidden deftypefn
-When loaded with @code{(use-modules (foo bar))}, the
address@hidden call looks for the @file{foobar-c-code.so} (etc)
-object file in the standard system locations, such as @file{/usr/lib}
-or @file{/usr/local/lib}.
-
-If someone installs your module to a non-standard location then the
-object file won't be found. You can address this by inserting the
-install location in the @file{foo/bar.scm} file. This is convenient
-for the user and also guarantees the intended object is read, even if
-stray older or newer versions are in the loader's path.
-
-The usual way to specify an install location is with a @code{prefix}
-at the configure stage, for instance @samp{./configure prefix=/opt}
-results in library files as say @file{/opt/lib/foobar-c-code.so}.
-When using Autoconf (@pxref{Top, , Introduction, autoconf, The GNU
-Autoconf Manual}), the library location is in a @code{libdir}
-variable. Its value is intended to be expanded by @command{make}, and
-can by substituted into a source file like @file{foo.scm.in}
address@hidden {C Procedure} SCM scm_c_define_module (const char
address@hidden, void (address@hidden)(void *), void address@hidden)
+Define a new module named @var{name} and make it current while
address@hidden is called, passing it @var{data}. Return the module.
address@hidden
-(define-module (foo bar))
-(load-extension "XXlibdirXX/foobar-c-code" "foo_bar_init")
address@hidden example
+The parameter @var{name} is a string with the symbols that make up
+the module name, separated by spaces. For example, @samp{"foo bar"} names
+the module @samp{(foo bar)}.
address@hidden
-with the following in a @file{Makefile}, using @command{sed}
-(@pxref{Top, , Introduction, sed, SED, A Stream Editor}),
+When there already exists a module named @var{name}, it is used
+unchanged, otherwise, an empty module is created.
address@hidden deftypefn
address@hidden
-foo.scm: foo.scm.in
- sed 's|XXlibdirXX|$(libdir)|' <foo.scm.in >foo.scm
address@hidden example
address@hidden {C Procedure} SCM scm_c_resolve_module (const char
address@hidden)
+Find the module name @var{name} and return it. When it has not
+already been defined, try to auto-load it. When it can't be found
+that way either, create an empty module. The name is interpreted as
+for @code{scm_c_define_module}.
address@hidden deftypefn
-The actual pattern @code{XXlibdirXX} is arbitrary, it's only something
-which doesn't otherwise occur. If several modules need the value, it
-can be easier to create one @file{foo/config.scm} with a define of the
address@hidden location, and use that as required.
address@hidden {C Procedure} SCM scm_resolve_module (SCM @var{name})
+Like @code{scm_c_resolve_module}, but the name is given as a real list
+of symbols.
address@hidden deftypefn
address@hidden
-(define-module (foo config))
-(define-public foo-config-libdir "XXlibdirXX"")
address@hidden example
address@hidden {C Procedure} SCM scm_c_use_module (const char address@hidden)
+Add the module named @var{name} to the uses list of the current
+module, as with @code{(use-modules @var{name})}. The name is
+interpreted as for @code{scm_c_define_module}.
address@hidden deftypefn
-Such a file might have other locations too, for instance a data
-directory for auxiliary files, or @code{localedir} if the module has
-its own @code{gettext} message catalogue
-(@pxref{Internationalization}).
-
-When installing multiple C code objects, it can be convenient to put
-them in a subdirectory of @code{libdir}, thus giving for example
address@hidden/usr/lib/foo/some-obj.so}. If the objects are only meant to be
-used through the module, then a subdirectory keeps them out of sight.
-
-It will be noted all of the above requires that the Scheme code to be
-found in @code{%load-path} (@pxref{Build Config}). Presently it's
-left up to the system administrator or each user to augment that path
-when installing Guile modules in non-default locations. But having
-reached the Scheme code, that code should take care of hitting any of
-its own private files etc.
-
-Presently there's no convention for having a Guile version number in
-module C code filenames or directories. This is primarily because
-there's no established principles for two versions of Guile to be
-installed under the same prefix (eg. two both under @file{/usr}).
-Assuming upward compatibility is maintained then this should be
-unnecessary, and if compatibility is not maintained then it's highly
-likely a package will need to be revisited anyway.
-
-The present suggestion is that modules should assume when they're
-installed under a particular @code{prefix} that there's a single
-version of Guile there, and the @code{guile-config} at build time has
-the necessary information about it. C code or Scheme code might adapt
-itself accordingly (allowing for features not available in an older
-version for instance).
address@hidden {C Procedure} SCM scm_c_export (const char address@hidden, ...)
+Add the bindings designated by @var{name}, ... to the public interface
+of the current module. The list of names is terminated by
address@hidden
address@hidden deftypefn
@node Variables
@@ -1473,9 +918,6 @@ name @var{name} in the current module. But they can also
be created
dynamically by calling one of the constructor procedures
@code{make-variable} and @code{make-undefined-variable}.
-First-class variables are especially useful for interacting with the
-current module system (@pxref{The Guile module system}).
-
@deffn {Scheme Procedure} make-undefined-variable
@deffnx {C Function} scm_make_undefined_variable ()
Return a variable that is initially unbound.
@@ -1513,6 +955,83 @@ return @code{#f}.
@end deffn
address@hidden provide and require
address@hidden provide and require
+
+Aubrey Jaffer, mostly to support his portable Scheme library SLIB,
+implemented a provide/require mechanism for many Scheme implementations.
+Library files in SLIB @emph{provide} a feature, and when user programs
address@hidden that feature, the library file is loaded in.
+
+For example, the file @file{random.scm} in the SLIB package contains the
+line
+
address@hidden
+(provide 'random)
address@hidden lisp
+
+so to use its procedures, a user would type
+
address@hidden
+(require 'random)
address@hidden lisp
+
+and they would magically become available, @emph{but still have the same
+names!} So this method is nice, but not as good as a full-featured
+module system.
+
+When SLIB is used with Guile, provide and require can be used to access
+its facilities.
+
address@hidden Environments
address@hidden Environments
address@hidden environment
+
+Scheme, as defined in R5RS, does @emph{not} have a full module system.
+However it does define the concept of a top-level @dfn{environment}.
+Such an environment maps identifiers (symbols) to Scheme objects such
+as procedures and lists: @ref{About Closure}. In other words, it
+implements a set of @dfn{bindings}.
+
+Environments in R5RS can be passed as the second argument to
address@hidden (@pxref{Fly Evaluation}). Three procedures are defined to
+return environments: @code{scheme-report-environment},
address@hidden and @code{interaction-environment} (@pxref{Fly
+Evaluation}).
+
+In addition, in Guile any module can be used as an R5RS environment,
+i.e., passed as the second argument to @code{eval}.
+
+Note: the following two procedures are available only when the
address@hidden(ice-9 r5rs)} module is loaded:
+
address@hidden
+(use-modules (ice-9 r5rs))
address@hidden lisp
+
address@hidden {Scheme Procedure} scheme-report-environment version
address@hidden {Scheme Procedure} null-environment version
address@hidden must be the exact integer `5', corresponding to revision
+5 of the Scheme report (the Revised^5 Report on Scheme).
address@hidden returns a specifier for an
+environment that is empty except for all bindings defined in the
+report that are either required or both optional and supported by the
+implementation. @code{null-environment} returns a specifier for an
+environment that is empty except for the (syntactic) bindings for all
+syntactic keywords defined in the report that are either required or
+both optional and supported by the implementation.
+
+Currently Guile does not support values of @var{version} for other
+revisions of the report.
+
+The effect of assigning (through the use of @code{eval}) a variable
+bound in a @code{scheme-report-environment} (for example @code{car})
+is unspecified. Currently the environments specified by
address@hidden are not immutable in Guile.
address@hidden deffn
+
+
+
@c Local Variables:
@c TeX-master: "guile.texi"
@c End:
diff --git a/doc/ref/guile.texi b/doc/ref/guile.texi
index bb76545..91d391e 100644
--- a/doc/ref/guile.texi
+++ b/doc/ref/guile.texi
@@ -306,6 +306,7 @@ available through both Scheme and C interfaces.
* Memory Management:: Memory management and garbage collection.
* Objects:: Low level object orientation support.
* Modules:: Designing reusable code libraries.
+* Foreign Function Interface:: Interacting with C procedures and data.
* Scheduling:: Threads, mutexes, asyncs and dynamic roots.
* Options and Config:: Configuration, features and runtime options.
* Translation:: Support for translating other languages.
@@ -330,6 +331,7 @@ available through both Scheme and C interfaces.
@include api-evaluation.texi
@include api-memory.texi
@include api-modules.texi
address@hidden api-foreign.texi
@include api-scheduling.texi
@c object orientation support here
@include api-options.texi
hooks/post-receive
--
GNU Guile
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Guile-commits] GNU Guile branch, master, updated. release_1-9-9-38-g726b8ba,
Andy Wingo <=