[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Guile-commits] branch excise-ltdl updated: docs checkpoint
|
From: |
Andy Wingo |
|
Subject: |
[Guile-commits] branch excise-ltdl updated: docs checkpoint |
|
Date: |
Wed, 27 Jan 2021 16:17:48 -0500 |
This is an automated email from the git hooks/post-receive script.
wingo pushed a commit to branch excise-ltdl
in repository guile.
The following commit(s) were added to refs/heads/excise-ltdl by this push:
new 6d9cc44 docs checkpoint
6d9cc44 is described below
commit 6d9cc44fbb86518483543078efc5237e490e5a27
Author: Andy Wingo <wingo@pobox.com>
AuthorDate: Wed Jan 27 22:17:38 2021 +0100
docs checkpoint
---
doc/ref/api-foreign.texi | 509 ++++++++++++++++-------------------------
doc/ref/libguile-parallel.texi | 6 +-
doc/ref/tour.texi | 4 +-
3 files changed, 203 insertions(+), 316 deletions(-)
diff --git a/doc/ref/api-foreign.texi b/doc/ref/api-foreign.texi
index 1782d40..e834d00 100644
--- a/doc/ref/api-foreign.texi
+++ b/doc/ref/api-foreign.texi
@@ -16,12 +16,10 @@ libraries'', look up data and functions inside them, and so
on.
@menu
* Foreign Libraries:: Dynamically linking to libraries.
-* C Extensions:: Extending Guile in C with loadable modules.
-* Modules and Extensions:: Loading C extensions into modules.
-* Foreign Pointers:: Accessing global variables.
+* Foreign Extensions:: Extending Guile in C with loadable modules.
+* Foreign Pointers:: Pointers to C data or functions.
* Foreign Types:: Expressing C types in Scheme.
* Foreign Functions:: Simple calls to C procedures.
-* Foreign Variables:: Pointers to C symbols.
* Void Pointers and Byte Access:: Pointers into the ether.
* Foreign Structs:: Packing and unpacking structs.
* More Foreign Functions:: Advanced examples.
@@ -196,66 +194,16 @@ otherwise.
@end deffn
-@node C Extensions
-@subsection C Extensions
+@node Foreign Extensions
+@subsection Foreign 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.
+One way to use shared libraries is to extend Guile. Such loadable
+modules generally define one distinguished initialization function that,
+when called, will use the @code{libguile} API to define procedures in
+the current module.
-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.
-
-@deffn {Scheme Procedure} load-extension lib init
-@deffnx {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
-
-@lisp
-(dynamic-call INIT (dynamic-link LIB))
-@end 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.
-
-As for @code{dynamic-link}, @var{lib} should not contain any suffix such
-as @code{.so} (@pxref{Foreign Libraries, dynamic-link}). 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
-@file{libguile-bla-blum} for a extension related to a module @code{(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,
-
-@lisp
-(define-module (bla blum))
-
-(load-extension "libguile-bla-blum" "bla_init_blum")
-@end lisp
-@end deffn
-
-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.
+Concretely, you might extend Guile with an implementation of the Bessel
+function, @code{j0}:
@smallexample
#include <math.h>
@@ -268,218 +216,220 @@ j0_wrapper (SCM x)
@}
void
-init_math_bessel ()
+init_math_bessel (void)
@{
scm_c_define_gsubr ("j0", 1, 0, 0, j0_wrapper);
@}
@end 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.
+The C source file would then need to be compiled into a shared library.
+On GNU/Linux, the compiler invocation might look like this:
@smallexample
-gcc -shared -o libbessel.so -fPIC bessel.c
+gcc -shared -o bessel.so -fPIC bessel.c
@end smallexample
-Now fire up Guile:
+A good default place to put shared libraries that extend Guile is into
+the extensions dir. From the command line or a build script, invoke
+@code{pkg-config --variable=extensionsdir
+guile-@value{EFFECTIVE-VERSION}} to print the extensions dir.
+@xref{Parallel Installations}, for more details.
+
+Guile can load up @code{bessel.so} via @code{load-extension}.
+
+@deffn {Scheme Procedure} load-extension lib init
+@deffnx {C Function} scm_load_extension (lib, init)
+Load and initialize the extension designated by LIB and INIT.
+@end deffn
+
+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:
@lisp
-(define bessel-lib (dynamic-link "./libbessel.so"))
-(dynamic-call "init_math_bessel" bessel-lib)
-(j0 2)
-@result{} 0.223890779141236
+(define-module (math bessel)
+ #:export (j0))
+
+(load-extension "bessel" "init_math_bessel")
@end 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
-@code{init_math_bessel} function which in turn will register the C
-function @code{j0_wrapper} with the Guile interpreter under the name
-@code{j0}. This function becomes immediately available and we can call
-it from Scheme.
+This @code{load-extension} invocation loads the @code{bessel} library
+via @code{(load-foreign-library "bessel")}, then looks up the
+@code{init_math_bessel} symbol in the library, treating it as a function
+of no arguments, and calls that function.
-Fun, isn't it? But we are only half way there. This is what
-@code{apropos} has to say about @code{j0}:
+If you decide to put your extension outside the default search path for
+@code{load-foreign-library}, probably you should adapt the Scheme module
+to specify its absolute path. For example, if you use @code{automake}
+to build your extension and place it in @code{$(pkglibdir)}, you might
+define a build-parameters module that gets created by the build system:
-@smallexample
-(apropos "j0")
-@print{} (guile-user): j0 #<primitive-procedure j0>
-@end smallexample
+@example
+(define-module (math config)
+ #:export (extensiondir))
+(define extensiondir "PKGLIBDIR")
+@end example
-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.
+This file would be @code{config.scm.in}. You would define a @code{make}
+rule to substitute in the absolute installed file name:
-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
-@file{bessel.c}:
+@example
+config.scm: config.scm.in
+ sed 's|PKGLIBDIR|$(pkglibdir)|' <$< >$@
+@end example
+
+Then your @code{(math bessel)} would import @code{(math config)}, then
+@code{(load-extension (in-vicinity extensiondir "bessel")
+"init_math_bessel")}.
+
+An alternate approach would be to rebind the
+@code{guile-extensions-path} parameter, or its corresponding environment
+variable, but that is more useful for known site installations, as
+changing those parameters applies to other users of
+@code{load-foreign-library} as well.
+
+Note that the new primitives that the extension adds 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
+@code{scm_c_define_gsubr} is executed, so to be clear about what goes
+where it's best to include the @code{load-extension} in a module, as
+above. Alternately, the C code can use @code{scm_c_define_module} to
+specify which module is being created:
@smallexample
-void
-init_math_bessel (void *unused)
+static void
+do_init (void *unused)
@{
scm_c_define_gsubr ("j0", 1, 0, 0, j0_wrapper);
scm_c_export ("j0", NULL);
@}
void
-scm_init_math_bessel_module ()
+init_math_bessel ()
@{
- scm_c_define_module ("math bessel", init_math_bessel, NULL);
+ scm_c_define_module ("math bessel", do_init, NULL);
@}
@end smallexample
-The general pattern for the name of a module init function is:
-@samp{scm_init_}, 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:
-
-@smallexample
-guile> (load-extension "./libbessel.so" "scm_init_math_bessel_module")
-guile> (use-modules (math bessel))
-guile> (j0 2)
-0.223890779141236
-guile> (apropos "j0")
-@print{} (math bessel): j0 #<primitive-procedure j0>
-@end smallexample
+And yet... if what we want is just the @code{j0} function, it seems like
+a lot of ceremony to have to compile a Guile-specific wrapper library
+complete with an initialization function and wraper module to allow
+Guile users to call it. There is another way, but to get there, we have
+to talk about function pointers and function types first. @xref{Foreign
+Functions}, to skip to the good parts.
-That's it!
+@node Foreign Pointers
+@subsection Foreign Pointers
-@node Modules and Extensions
-@subsection Modules and Extensions
+Foreign libraries are essentially key-value mappings, where the keys are
+the names of definitions exported by the module, and the
+values are the addresses of those definitions. To look up the address
+of a definition, use @code{foreign-library-pointer}.
-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
-@code{scm_c_define_gsubr} 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.
+@deffn {Scheme Procedure} foreign-library-pointer lib name
+Return a ``wrapped pointer'' for the symbol @var{name} in the shared
+object referred to by @var{lib}. The returned pointer points to a C
+object.
+@end deffn
-To define C primitives within a specific module, the simplest way is:
+If we continue with the @code{bessel.so} example from before, we can get
+the address of the @code{init_math_bessel} function via:
@example
-(define-module (foo bar))
-(load-extension "foobar-c-code" "foo_bar_init")
+(use-modules (system foreign-library))
+(define bessel (load-foreign-library "bessel"))
+(define init (foreign-library-pointer bessel init))
+init
+@result{} #<pointer 0x7fb35b1b4688>
@end example
-@cindex extensiondir
-When loaded with @code{(use-modules (foo bar))}, the
-@code{load-extension} call looks for the @file{foobar-c-code.so} (etc)
-object file in Guile's @code{extensiondir}, which is usually a
-subdirectory of the @code{libdir}. For example, if your libdir is
-@file{/usr/lib}, the @code{extensiondir} for the Guile
@value{EFFECTIVE-VERSION}.@var{x}
-series will be @file{/usr/lib/guile/@value{EFFECTIVE-VERSION}/}.
-
-The extension path includes the major and minor version of Guile (the
-``effective version''), because Guile guarantees compatibility within a
-given effective version. This allows you to install different versions
-of the same extension for different versions of Guile.
-
-If the extension is not found in the @code{extensiondir}, Guile will
-also search the standard system locations, such as @file{/usr/lib} or
-@file{/usr/local/lib}. It is preferable, however, to keep your extension
-out of the system library path, to prevent unintended interference with
-other dynamically-linked C libraries.
-
-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}
-
-@example
-(define-module (foo bar))
-(load-extension "XXextensiondirXX/foobar-c-code" "foo_bar_init")
-@end example
+A value returned by @code{foreign-library-pointer} is a Scheme wrapper
+for a C pointer. Pointers are a data type in Guile that is disjoint
+from all other types. The next section discusses ways to dereference
+pointers, but before then we describe the usual type predicates and so
+on.
-@noindent
-with the following in a @file{Makefile}, using @command{sed}
-(@pxref{Top, , Introduction, sed, SED, A Stream Editor}),
+Note that the rest of the interfaces in this section are part of the
+@code{(system foreign)} library:
@example
-foo.scm: foo.scm.in
- sed 's|XXextensiondirXX|$(libdir)/guile/@value{EFFECTIVE-VERSION}|'
<foo.scm.in >foo.scm
+(use-modules (system foreign))
@end example
-The actual pattern @code{XXextensiondirXX} 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
-@code{extensiondir} location, and use that as required.
+@deffn {Scheme Procedure} pointer-address pointer
+@deffnx {C Function} scm_pointer_address (pointer)
+Return the numerical value of @var{pointer}.
@example
-(define-module (foo config))
-(define-public foo-config-extensiondir "XXextensiondirXX"")
+(pointer-address init)
+@result{} 139984413364296 ; YMMV
@end example
+@end deffn
+
+@deffn {Scheme Procedure} make-pointer address [finalizer]
+Return a foreign pointer object pointing to @var{address}. If
+@var{finalizer} is passed, it should be a pointer to a one-argument C
+function that will be called when the pointer object becomes
+unreachable.
+@end deffn
-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}).
+@deffn {Scheme Procedure} pointer? obj
+Return @code{#t} if @var{obj} is a pointer object, or @code{#f}
+otherwise.
+@end deffn
-It will be noted all of the above requires that the Scheme code to be
-found in @code{%load-path} (@pxref{Load Paths}). 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.
+@defvr {Scheme Variable} %null-pointer
+A foreign pointer whose value is 0.
+@end defvr
+@deffn {Scheme Procedure} null-pointer? pointer
+Return @code{#t} if @var{pointer} is the null pointer, @code{#f} otherwise.
+@end deffn
-@node Foreign Pointers
-@subsection Foreign Pointers
+For the purpose of passing SCM values directly to foreign functions, and
+allowing them to return SCM values, Guile also supports some unsafe
+casting operators.
-The previous sections have shown how Guile can be extended at runtime by
-loading compiled C extensions. This approach is all well and good, but
-wouldn't it be nice if we didn't have to write any C at all? This
-section takes up the problem of accessing C values from Scheme, and the
-next discusses C functions.
+@deffn {Scheme Procedure} scm->pointer scm
+Return a foreign pointer object with the @code{object-address}
+of @var{scm}.
+@end deffn
-@deffn {Scheme Procedure} foreign-library-pointer lib name
-Return a ``wrapped pointer'' for the symbol @var{name} in the shared
-object referred to by @var{lib}. The returned pointer points to a C
-object.
+@deffn {Scheme Procedure} pointer->scm pointer
+Unsafely cast @var{pointer} to a Scheme object.
+Cross your fingers!
@end deffn
-Obsolete note: 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{name} since it will be added
-automatically when necessary.
+Sometimes you want to give C extensions access to the dynamic FFI. At
+that point, the names get confusing, because ``pointer'' can refer to a
+@code{SCM} object that wraps a pointer, or to a @code{void*} value. We
+will try to use ``pointer object'' to refer to Scheme objects, and
+``pointer value'' to refer to @code{void *} values.
-examples
+@deftypefn {C Function} SCM scm_from_pointer (void *ptr, void (*finalizer)
(void*))
+Create a pointer object from a pointer value.
+If @var{finalizer} is non-null, Guile arranges to call it on the pointer
+value at some point after the pointer object becomes collectable.
+@end deftypefn
+
+@deftypefn {C Function} void* scm_to_pointer (SCM obj)
+Unpack the pointer value from a pointer object.
+@end deftypefn
@node Foreign Types
@subsection Foreign Types
-The first impedance mismatch that one sees between C and Scheme is that
-in C, the storage locations (variables) are typed, but in Scheme types
-are associated with values, not variables. @xref{Values and Variables}.
-
-So when describing a C function or a C structure so that it can be
-accessed from Scheme, the data types of the parameters or fields must be
-passed explicitly.
+From Scheme's perspective, foreign pointers are shards of chaos. The
+user can create a foreign pointer for any address, and do with it what
+they will. The only thing that lends a sense of order to the whole is a
+shared hallucination that certain storage locations have certain types.
+When making Scheme wrappers for foreign interfaces, we hide the madness
+by explicitly representing the the data types of parameters and fields.
-These ``C type values'' may be constructed using the constants and
+These ``foreign type values'' may be constructed using the constants and
procedures from the @code{(system foreign)} module, which may be loaded
like this:
@@ -488,7 +438,7 @@ like this:
@end example
@code{(system foreign)} exports a number of values expressing the basic
-C types:
+C types.
@defvr {Scheme Variable} int8
@defvrx {Scheme Variable} uint8
@@ -505,7 +455,7 @@ signednesses.
@end defvr
In addition there are some convenience bindings for indicating types of
-platform-dependent size:
+platform-dependent size.
@defvr {Scheme Variable} int
@defvrx {Scheme Variable} unsigned-int
@@ -535,11 +485,13 @@ types. Procedures detailed in the following sections,
such as
@node Foreign Functions
@subsection Foreign Functions
-Of course, the land of C is not all nouns and no verbs: there are
-functions too, and Guile allows you to call them.
-
The most natural thing to do with a dynamic library is to grovel around
-in it for a function pointer: a @dfn{foreign function}.
+in it for a function pointer: a @dfn{foreign function}. Load the
+@code{(system foreign)} module to use these Scheme interfaces.
+
+@example
+(use-modules (system foreign))
+@end example
@deffn {Scheme Procedure} pointer->procedure return_type func_ptr arg_types @
[#:return-errno?=#f]
@@ -562,7 +514,13 @@ If @var{return-errno?} is true, or when calling
return two values, with @code{errno} as the second value.
@end deffn
-foreign-library-pointer
+Finally, in @code{(system foreign-library)} there is a convenient
+wrapper function, joining together @code{foreign-libary-pointer} and
+@code{procedure->pointer}:
+
+@deffn {Scheme Procedure} foreign-library-function lib name @
+ return_type arg_types [#:return-errno?=#f]
+@end deffn
Here is a better definition of @code{(math bessel)}:
@@ -574,96 +532,14 @@ Here is a better definition of @code{(math bessel)}:
(define libm (dynamic-link "libm"))
(define j0
- (pointer->procedure double
- (dynamic-func "j0" libm)
- (list double)))
+ (foreign-library-function libm "j0" double (list double)))
@end example
That's it! No C at all.
-more complicated types discussed later, wrapping up with example...
-
-@node Foreign Variables
-@subsection Foreign Variables
-
-Pointers to variables in the current address space may be looked up
-dynamically using @code{dynamic-pointer}.
-
-For example, currently Guile has a variable, @code{scm_numptob}, as part
-of its API. It is declared as a C @code{long}. So, to create a handle
-pointing to that foreign value, we do:
-
-@example
-(use-modules (system foreign))
-(define numptob (dynamic-pointer "scm_numptob" (dynamic-link)))
-numptob
-@result{} #<pointer 0x7fb35b1b4688>
-@end example
-
-(The next section discusses ways to dereference pointers.)
-
-A value returned by @code{dynamic-pointer} is a Scheme wrapper for a C
-pointer.
-
-@deffn {Scheme Procedure} pointer-address pointer
-@deffnx {C Function} scm_pointer_address (pointer)
-Return the numerical value of @var{pointer}.
-
-@example
-(pointer-address numptob)
-@result{} 139984413364296 ; YMMV
-@end example
-@end deffn
-
-@deffn {Scheme Procedure} make-pointer address [finalizer]
-Return a foreign pointer object pointing to @var{address}. If
-@var{finalizer} is passed, it should be a pointer to a one-argument C
-function that will be called when the pointer object becomes
-unreachable.
-@end deffn
-
-@deffn {Scheme Procedure} pointer? obj
-Return @code{#t} if @var{obj} is a pointer object, @code{#f} otherwise.
-@end deffn
-
-@defvr {Scheme Variable} %null-pointer
-A foreign pointer whose value is 0.
-@end defvr
-
-@deffn {Scheme Procedure} null-pointer? pointer
-Return @code{#t} if @var{pointer} is the null pointer, @code{#f} otherwise.
-@end deffn
-
-For the purpose of passing SCM values directly to foreign functions, and
-allowing them to return SCM values, Guile also supports some unsafe
-casting operators.
-
-@deffn {Scheme Procedure} scm->pointer scm
-Return a foreign pointer object with the @code{object-address}
-of @var{scm}.
-@end deffn
-
-@deffn {Scheme Procedure} pointer->scm pointer
-Unsafely cast @var{pointer} to a Scheme object.
-Cross your fingers!
-@end deffn
-
-Sometimes you want to give C extensions access to the dynamic FFI. At
-that point, the names get confusing, because ``pointer'' can refer to a
-@code{SCM} object that wraps a pointer, or to a @code{void*} value. We
-will try to use ``pointer object'' to refer to Scheme objects, and
-``pointer value'' to refer to @code{void *} values.
-
-@deftypefn {C Function} SCM scm_from_pointer (void *ptr, void (*finalizer)
(void*))
-Create a pointer object from a pointer value.
-
-If @var{finalizer} is non-null, Guile arranges to call it on the pointer
-value at some point after the pointer object becomes collectable.
-@end deftypefn
-
-@deftypefn {C Function} void* scm_to_pointer (SCM obj)
-Unpack the pointer value from a pointer object.
-@end deftypefn
+Before going on to more detailed examples, the next two sections discuss
+how to deal with data that is more complex than, say, @code{int8}.
+@xref{More Foreign Functions}, to continue with foreign function examples.
@node Void Pointers and Byte Access
@subsection Void Pointers and Byte Access
@@ -675,6 +551,12 @@ pointer can be accessed at the byte level. This is
achieved using
module contains procedures that can be used to convert byte sequences to
Scheme objects such as strings, floating point numbers, or integers.
+Load the @code{(system foreign)} module to use these Scheme interfaces.
+
+@example
+(use-modules (system foreign))
+@end example
+
@deffn {Scheme Procedure} pointer->bytevector pointer len [offset [uvec_type]]
@deffnx {C Function} scm_pointer_to_bytevector (pointer, len, offset,
uvec_type)
Return a bytevector aliasing the @var{len} bytes pointed to by
@@ -816,8 +698,12 @@ pointer or similar can prove equally disastrous.
Finally, one last note on foreign values before moving on to actually
calling foreign functions. Sometimes you need to deal with C structs,
which requires interpreting each element of the struct according to the
-its type, offset, and alignment. Guile has some primitives to support
-this.
+its type, offset, and alignment. The @code{(system foreign)} module has
+some primitives to support this.
+
+@example
+(use-modules (system foreign))
+@end example
@deffn {Scheme Procedure} sizeof type
@deffnx {C Function} scm_sizeof (type)
@@ -876,12 +762,13 @@ tightly packed structs and unions by hand. See the code
for
@node More Foreign Functions
@subsection More Foreign Functions
-Pointers may be passed to and returned from foreign functions as well.
-In that case the type of the argument or return value should be the
-symbol @code{*}, indicating a pointer. For example, the following
+It is possible to pass pointers to foreign functions, and to return them
+as well. In that case the type of the argument or return value should
+be the symbol @code{*}, indicating a pointer. For example, the following
code makes @code{memcpy} available to Scheme:
@example
+(use-modules (system foreign))
(define memcpy
(let ((this (dynamic-link)))
(pointer->procedure '*
diff --git a/doc/ref/libguile-parallel.texi b/doc/ref/libguile-parallel.texi
index 75fcd88..a3779a2 100644
--- a/doc/ref/libguile-parallel.texi
+++ b/doc/ref/libguile-parallel.texi
@@ -1,7 +1,7 @@
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2010, 2011,
-@c 2013-2014 Free Software Foundation, Inc.
+@c 2013-2014, 2021 Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@node Parallel Installations
@@ -52,8 +52,8 @@ how to use it from Autoconf.
@item extensiondir
@cindex @code{extensiondir}
The default directory where Guile looks for extensions---i.e., shared
-libraries providing additional features (@pxref{Modules and
-Extensions}). Run @command{pkg-config guile-@value{EFFECTIVE-VERSION}
+libraries providing additional features (@pxref{Foreign Extensions}).
+Run @command{pkg-config guile-@value{EFFECTIVE-VERSION}
--variable=extensiondir} to see its value.
@item guile
diff --git a/doc/ref/tour.texi b/doc/ref/tour.texi
index 0cac96c..c0ecb16 100644
--- a/doc/ref/tour.texi
+++ b/doc/ref/tour.texi
@@ -1,7 +1,7 @@
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2010, 2011,
-@c 2012 Free Software Foundation, Inc.
+@c 2012, 2021 Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@raisesections
@@ -280,7 +280,7 @@ scheme@@(guile-user)> (j0 2)
$1 = 0.223890779141236
@end smallexample
-@xref{Modules and Extensions}, for more information.
+@xref{Foreign Extensions}, for more information.
@lowersections
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Guile-commits] branch excise-ltdl updated: docs checkpoint,
Andy Wingo <=