12a43edc2d
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk/SWIG@4141 626c5289-ae23-0410-ae9c-e8d60b6d4f22
456 lines
No EOL
16 KiB
HTML
456 lines
No EOL
16 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<!-- Hand-written HTML -->
|
|
<html>
|
|
<head>
|
|
<title>SWIG and Guile</title>
|
|
</head>
|
|
|
|
<body bgcolor="#ffffff">
|
|
|
|
<a name="n1"></a><H1>14 SWIG and Guile</H1>
|
|
<!-- INDEX -->
|
|
<ul>
|
|
<li><a href="#n2">Meaning of "Module"</a>
|
|
<li><a href="#n3">Linkage</a>
|
|
<ul>
|
|
<li><a href="#n4">Simple Linkage</a>
|
|
<li><a href="#n5">Passive Linkage</a>
|
|
<li><a href="#n6">Native Guile Module Linkage</a>
|
|
<li><a href="#n7">Old Auto-Loading Guile Module Linkage</a>
|
|
<li><a href="#n8">Hobbit4D Linkage</a>
|
|
<li><a href="#n9">General Remarks on Multiple SWIG Modules</a>
|
|
</ul>
|
|
<li><a href="#n10">Underscore Folding</a>
|
|
<li><a href="#n11">Typemaps</a>
|
|
<li><a href="#n12">Smobs</a>
|
|
<li><a href="#n13">Exception Handling</a>
|
|
<li><a href="#n14">Procedure documentation</a>
|
|
<li><a href="#n15">Procedures with setters</a>
|
|
</ul>
|
|
<!-- INDEX -->
|
|
|
|
|
|
|
|
<p>
|
|
This section details guile-specific support in SWIG.
|
|
|
|
<a name="n2"></a><H2>14.1 Meaning of "Module"</H2>
|
|
|
|
|
|
</a>
|
|
|
|
<p>
|
|
There are three different concepts of "module" involved, defined
|
|
separately for SWIG, Guile, and Libtool. To avoid horrible confusion,
|
|
we explicitly prefix the context, e.g., "guile-module".
|
|
|
|
<a name="n3"></a><H2>14.2 Linkage</H2>
|
|
|
|
|
|
</a>
|
|
|
|
<p>
|
|
Guile support is complicated by a lack of user community cohesiveness,
|
|
which manifests in multiple shared-library usage conventions. A set of
|
|
policies implementing a usage convention is called a <b>linkage</b>.
|
|
|
|
<a name="n4"></a><H3>14.2.1 Simple Linkage</H3>
|
|
|
|
|
|
The default linkage is the simplest; nothing special is done. In this
|
|
case the function <code>SWIG_init()</code> is exported. Simple linkage
|
|
can be used in several ways:
|
|
|
|
<ul>
|
|
<li><b>Embedded Guile, no modules.</b> You want to embed a Guile
|
|
interpreter into your program; all bindings made by SWIG shall show up
|
|
in the root module. Then call <code>SWIG_init()</code> in the
|
|
<code>inner_main()</code> function. See the "simple" and "matrix" examples under
|
|
<code>Examples/guile</code>.
|
|
|
|
<li><b>Dynamic module mix-in.</b> You want to create a Guile module
|
|
using <code>define-module</code>, containing both Scheme code and
|
|
bindings made by SWIG; you want to load the SWIG modules as shared
|
|
libraries into Guile.
|
|
<blockquote>
|
|
<pre>
|
|
(define-module (my module))
|
|
(define my-so (dynamic-link "./example.so"))
|
|
(dynamic-call "SWIG_init" my-so) ; make SWIG bindings
|
|
;; Scheme definitions can go here
|
|
</pre>
|
|
</blockquote>
|
|
Newer Guile versions provide a shorthand for <code>dynamic-link</code>
|
|
and <code>dynamic-call</code>:
|
|
<blockquote>
|
|
<pre>
|
|
(load-extension "./example.so" "SWIG_init")
|
|
</pre>
|
|
</blockquote>
|
|
You need to explicitly export those bindings made by SWIG that you
|
|
want to import into other modules:
|
|
<blockquote>
|
|
<pre>
|
|
(export foo bar)
|
|
</pre>
|
|
</blockquote>
|
|
In this example, the procedures <code>foo</code> and <code>bar</code>
|
|
would be exported. Alternatively, you can export all bindings with the
|
|
following module-system hack:
|
|
<blockquote>
|
|
<pre>
|
|
(module-map (lambda (sym var)
|
|
(module-export! (current-module) (list sym)))
|
|
(current-module))
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p>SWIG can also generate this Scheme stub (from
|
|
<code>define-module</code> up to <code>export</code>)
|
|
semi-automagically if you pass it the command-line argument
|
|
<code>-scmstub <var>foo.scm</var></code>. Since SWIG doesn't know how
|
|
to load your extension module (with <code>dynamic-link</code> or
|
|
<code>load-extension</code>), you need to supply this
|
|
information by including a directive like this in the interface file:
|
|
<blockquote>
|
|
<pre>
|
|
%scheme %{ (load-extension "./example.so" "SWIG_init") %}
|
|
</pre>
|
|
</blockquote>
|
|
(The <code>%scheme</code> directive allows to insert arbitrary Scheme
|
|
code into the generated file <code><var>foo.scm</var></code>; it is
|
|
placed between the <code>define-module</code> form and the
|
|
<code>export</code> form.)
|
|
</ul>
|
|
|
|
<p>If you want to include several SWIG modules, you would need to rename
|
|
<code>SWIG_init</code> via a preprocessor define to avoid symbol
|
|
clashes. For this case, however, passive linkage is available.
|
|
|
|
<a name="n5"></a><H3>14.2.2 Passive Linkage</H3>
|
|
|
|
|
|
<p>Passive linkage is just like simple linkage, but it generates an
|
|
initialization function whose name is derived from the module and
|
|
package name (see below).
|
|
|
|
<p>You should use passive linkage rather than simple linkage when you
|
|
are using multiple modules.
|
|
|
|
<a name="n6"></a><H3>14.2.3 Native Guile Module Linkage</H3>
|
|
|
|
|
|
<p>SWIG can also generate wrapper code that does all the Guile module
|
|
declarations on its own if you pass it the <code>-Linkage
|
|
module</code> command-line option. This requires Guile 1.5.0 or later.
|
|
|
|
<p>The module name is set with the <code>-package</code> and
|
|
<code>-module</code> command-line options. Suppose you want to define
|
|
a module with name <code>(my lib foo)</code>; then you would have to
|
|
pass the options <code>-package <var>my</var>/<var>lib</var> -module
|
|
<var>foo</var></code>. Note that the last part of the name can also be set
|
|
via the SWIG directive <code>%module</code>.
|
|
|
|
<p>You can use this linkage in several ways:
|
|
|
|
<ul>
|
|
<li><b>Embedded Guile with SWIG modules.</b> You want to embed a Guile
|
|
interpreter into your program; the SWIG bindings shall be put into
|
|
different modules. Simply call the function
|
|
<code>scm_init_<var>my</var>_<var>modules</var>_<var>foo</var>_module</code>
|
|
in the <code>inner_main()</code> function.
|
|
|
|
<li><b>Dynamic Guile modules.</b> You want to load the SWIG modules as
|
|
shared libraries into Guile; all bindings are automatically put in
|
|
newly created Guile modules.
|
|
<blockquote>
|
|
<pre>
|
|
(define my-so (dynamic-link "./foo.so"))
|
|
;; create new module and put bindings there:
|
|
(dynamic-call "scm_init_my_modules_foo_module" my-so)
|
|
</pre>
|
|
</blockquote>
|
|
Newer Guile versions have a shorthand procedure for this:
|
|
<blockquote>
|
|
<pre>
|
|
(load-extension "./foo.so" "scm_init_my_modules_foo_module")
|
|
</pre>
|
|
</blockquote>
|
|
</ul>
|
|
|
|
<a name="n7"></a><H3>14.2.4 Old Auto-Loading Guile Module Linkage</H3>
|
|
|
|
|
|
<p>Guile used to support an autoloading facility for object-code
|
|
modules. This support has been marked deprecated in version 1.4.1 and
|
|
is going to disappear sooner or later. SWIG still supports building
|
|
auto-loading modules if you pass it the <code>-Linkage ltdlmod</code>
|
|
command-line option.
|
|
|
|
<p>Auto-loading worked like this: Suppose a module with name <code>(my
|
|
lib foo)</code> is required and not loaded yet. Guile will then search
|
|
all directories in its search path
|
|
for a Scheme file <code>my/modules/foo.scm</code> or a shared library
|
|
<code><var>my</var>/<var>modules</var>/lib<var>foo</var>.so</code> (or
|
|
<code><var>my</var>/<var>modules</var>/lib<var>foo</var>.la</code>;
|
|
see the GNU libtool documentation). If a
|
|
shared library is found that contains the symbol
|
|
<code>scm_init_<var>my</var>_<var>modules</var>_<var>foo</var>_module</code>,
|
|
the library is loaded, and the function at that symbol is called with
|
|
no arguments in order to initialize the module.
|
|
|
|
<p>When invoked with the <code>-Linkage ltdlmod</code> command-line
|
|
option, SWIG generates an exported module initialization function with
|
|
an apropriate name.
|
|
|
|
|
|
<a name="n8"></a><H3>14.2.5 Hobbit4D Linkage</H3>
|
|
|
|
|
|
<p>
|
|
The only other linkage supported at this time creates shared object
|
|
libraries suitable for use by hobbit's <code>(hobbit4d link)</code>
|
|
guile module. This is called the "hobbit" linkage, and requires also
|
|
using the "-package" command line option to set the part of the module
|
|
name before the last symbol. For example, both command lines:
|
|
|
|
<blockquote>
|
|
<pre>
|
|
swig -guile -package my/lib foo.i
|
|
swig -guile -package my/lib -module foo foo.i
|
|
</pre>
|
|
</blockquote>
|
|
|
|
would create module <code>(my lib foo)</code> (assuming in the first
|
|
case foo.i declares the module to be "foo"). The installed files are
|
|
my/lib/libfoo.so.X.Y.Z and friends. This scheme is still very
|
|
experimental; the (hobbit4d link) conventions are not well understood.
|
|
|
|
|
|
<a name="n9"></a><H3>14.2.6 General Remarks on Multiple SWIG Modules</H3>
|
|
|
|
|
|
If you want to use multiple SWIG modules, they have to share some
|
|
run-time data for the typing system. You have two options:
|
|
|
|
<ul>
|
|
<li>Either generate all but one wrapper module with
|
|
the <code>-c</code> command-line argument. Compile all wrapper files
|
|
with the C compiler switch <code>-DSWIG_GLOBAL</code>.
|
|
|
|
<li>Or generate all wrapper modules with the <code>-c</code>
|
|
command-line argument and compile all wrapper files with the C
|
|
compiler switch <code>-DSWIG_GLOBAL</code>. Then link against the
|
|
runtime library <code>libswigguile</code>, which is built by
|
|
<code>make runtime</code>. The needed linker flags are reported by
|
|
SWIG if you invoke it with the <code>-guile -ldflags</code>
|
|
command-line arguments.
|
|
</ul>
|
|
|
|
<a name="n10"></a><H2>14.3 Underscore Folding</H2>
|
|
|
|
|
|
</a>
|
|
|
|
<p>
|
|
Underscores are converted to dashes in identifiers. Guile support may
|
|
grow an option to inhibit this folding in the future, but no one has
|
|
complained so far.
|
|
|
|
<p>You can use the SWIG directives <code>%name</code> and
|
|
<code>%rename</code> to specify the Guile name of the wrapped
|
|
functions and variables (see CHANGES).
|
|
|
|
<a name="n11"></a><H2>14.4 Typemaps</H2>
|
|
|
|
|
|
</a>
|
|
|
|
<p>
|
|
The Guile module handles all types via typemaps. This
|
|
information is read from <code>Lib/guile/typemaps.i</code>.
|
|
|
|
Some non-standard typemap substitutions are supported:
|
|
<ul>
|
|
<li><code>$descriptor</code> expands to a type descriptor for use with
|
|
the <code>SWIG_Guile_MakePtr()</code> and
|
|
<code>SWIG_Guile_GetPtr</code> functions.
|
|
<li>For pointer types, <code>$*descriptor</code> expands to a
|
|
descriptor for the direct base type (i.e., one pointer is stripped),
|
|
whereas <code>$basedescriptor</code> expands to a
|
|
descriptor for the base type (i.e., all pointers are stripped).
|
|
</ul>
|
|
|
|
<p>A function returning <code>void</code> (more precisely, a function
|
|
whose <code>out</code> typemap returns <code>GH_UNSPECIFIED</code>) is
|
|
treated as returning no values. In <code>argout</code> typemaps, one
|
|
can use the macro <code>GUILE_APPEND_RESULT</code> in order to append
|
|
a value to the list of function return values.
|
|
|
|
<p>Multiple values can be passed up to Scheme in one of three ways:
|
|
<ul>
|
|
<li><em>Multiple values as lists.</em>
|
|
By default, if more than one value is to
|
|
be returned, a list of the values is created and returned; to switch
|
|
back to this behavior, use
|
|
<blockquote>
|
|
<pre>%values_as_list;</pre>
|
|
</blockquote>
|
|
<li><em>Multiple values as vectors.</em>
|
|
By issueing
|
|
<blockquote>
|
|
<pre>%values_as_vector;</pre>
|
|
</blockquote>
|
|
vectors instead of lists will be used.
|
|
<li><em>Multiple values for multiple-value continuations.</em>
|
|
<strong>This is the most elegant way.</strong> By issueing
|
|
<blockquote>
|
|
<pre>%multiple_values;</pre>
|
|
</blockquote>
|
|
multiple values are passed to the multiple-value
|
|
continuation, as created by <code>call-with-values</code> or the
|
|
convenience macro <code>receive</code>. The latter is available if you
|
|
issue <code>(use-modules (srfi srfi-8))</code>. Assuming that your
|
|
<code>divide</code> function
|
|
wants to return two values, a quotient and a remainder, you can write:
|
|
<blockquote>
|
|
<pre>
|
|
(receive (quotient remainder)
|
|
(divide 35 17)
|
|
<var>body</var>...)
|
|
</pre>
|
|
</blockquote>
|
|
In <code><var>body</var></code>, the first result of
|
|
<code>divide</code> will be bound to the variable
|
|
<code>quotient</code>, and the second result to <code>remainder</code>.
|
|
</ul>
|
|
See also the "multivalue" example.
|
|
|
|
<a name="n12"></a><H2>14.5 Smobs</H2>
|
|
|
|
|
|
</a>
|
|
|
|
<p>
|
|
For pointer types, SWIG uses Guile smobs.
|
|
|
|
<p>
|
|
In earlier versions of SWIG, C pointers were represented as Scheme
|
|
strings containing a hexadecimal rendering of the pointer value and a
|
|
mangled type name. As Guile allows registering user types, so-called
|
|
"smobs" (small objects), a much cleaner representation has been
|
|
implemented now. The details will be discussed in the following.
|
|
|
|
<p>
|
|
A smob is a cons cell where the lower half of the CAR contains the
|
|
smob type tag, while the upper half of the CAR and the whole CDR are
|
|
available. <code>SWIG_Guile_Init()</code> registers a smob type named
|
|
"swig" with Guile; its type tag is stored in the variable
|
|
<code>swig_tag</code>. The upper half of the CAR store an index into
|
|
a table of all C pointer types seen so far, to which new types seen
|
|
are appended. The CDR stores the pointer value. SWIG smobs print
|
|
like this: <code>#<swig struct xyzzy * 0x1234affe></code> Two of
|
|
them are <code>equal?</code> if and only if they have the same type
|
|
and value.
|
|
|
|
<p>
|
|
To construct a Scheme object from a C pointer, the wrapper code calls
|
|
the function <code>SWIG_Guile_MakePtr()</code>, passing a pointer to a
|
|
struct representing the pointer type. The type index to store in the
|
|
upper half of the CAR is read from this struct.
|
|
|
|
<p>
|
|
To get the pointer represented by a smob, the wrapper code calls the
|
|
function <code>SWIG_Guile_GetPtr</code>, passing a pointer to a struct
|
|
representing the expected pointer type. If the
|
|
Scheme object passed was not a SWIG smob representing a compatible
|
|
pointer, a <code>wrong-type-arg</code> exception is raised.
|
|
|
|
<a name="n13"></a><H2>14.6 Exception Handling</H2>
|
|
|
|
|
|
</a>
|
|
|
|
<p>
|
|
SWIG code calls <code>scm_error</code> on exception, using the following
|
|
mapping:
|
|
|
|
<pre>
|
|
MAP(SWIG_MemoryError, "swig-memory-error");
|
|
MAP(SWIG_IOError, "swig-io-error");
|
|
MAP(SWIG_RuntimeError, "swig-runtime-error");
|
|
MAP(SWIG_IndexError, "swig-index-error");
|
|
MAP(SWIG_TypeError, "swig-type-error");
|
|
MAP(SWIG_DivisionByZero, "swig-division-by-zero");
|
|
MAP(SWIG_OverflowError, "swig-overflow-error");
|
|
MAP(SWIG_SyntaxError, "swig-syntax-error");
|
|
MAP(SWIG_ValueError, "swig-value-error");
|
|
MAP(SWIG_SystemError, "swig-system-error");
|
|
</pre>
|
|
|
|
<p>
|
|
The default when not specified here is to use "swig-error".
|
|
See Lib/exception.i for details.
|
|
|
|
<a name="n14"></a><H2>14.7 Procedure documentation</H2>
|
|
|
|
|
|
</a>
|
|
|
|
<p>If invoked with the command-line option <code>-procdoc
|
|
<var>file</var></code>, SWIG creates documentation strings for the
|
|
generated wrapper functions, describing the procedure signature and
|
|
return value, and writes them to <var>file</var>. You need Guile 1.4
|
|
or later to make use of the documentation files.
|
|
|
|
<p>SWIG can generate documentation strings in three formats, which are
|
|
selected via the command-line option <code>-procdocformat
|
|
<var>format</var></code>:
|
|
<ul>
|
|
<li><code>guile-1.4</code> (default): Generates a format suitable for Guile 1.4.
|
|
<li><code>plain</code>: Generates a format suitable for Guile 1.4.1 and
|
|
later.
|
|
<li><code>texinfo</code>: Generates texinfo source, which must be run
|
|
through texinfo in order to get a format suitable for Guile 1.4.1 and
|
|
later.
|
|
</ul>
|
|
|
|
<p>You need to register the generated documentation file with Guile
|
|
like this:
|
|
<pre>
|
|
(use-modules (ice-9 documentation))
|
|
(set! documentation-files
|
|
(cons "<var>file</var>" documentation-files))
|
|
</pre>
|
|
|
|
<p>Documentation strings can be configured using the Guile-specific
|
|
typemaps <code>indoc</code>, <code>outdoc</code>,
|
|
<code>argoutdoc</code>, <code>varindoc</code>, and
|
|
<code>varoutdoc</code>. See <code>Lib/guile/typemaps.i</code> for
|
|
details.
|
|
|
|
<a name="n15"></a><H2>14.8 Procedures with setters</H2>
|
|
|
|
|
|
</a>
|
|
|
|
<p>For global variables, SWIG creates a single wrapper procedure
|
|
<code>(<var>variable</var> :optional value)</code>, which is used for
|
|
both getting and setting the value. For struct members, SWIG creates
|
|
two wrapper procedures <code>(<var>struct</var>-<var>member</var>-get
|
|
pointer)</code> and <code>(<var>struct-member</var>-set pointer value)</code>.
|
|
|
|
<p>If invoked with the command-line option <code>-emit-setters</code>,
|
|
SWIG will additionally create procedures with setters. For global
|
|
variables, the procedure-with-setter <code><var>variable</var></code>
|
|
is created, so you can use <code>(<var>variable</var>)</code> to get
|
|
the value and <code>(set! (<var>variable</var>)
|
|
<var>value</var>)</code> to set it. For struct members, the
|
|
procedure-with-setter <code><var>struct</var>-<var>member</var></code>
|
|
is created, so you can use <code>(<var>struct</var>-<var>member</var>
|
|
<var>pointer</var>)</code> to get the value and <code>(set!
|
|
(<var>struct</var>-<var>member</var> <var>pointer</var>)
|
|
<var>value</var>)</code> to set it.
|
|
|
|
</body>
|
|
</html> |