- Updated documentation to use CSS and <div> instead of blockquotes
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk/SWIG@7003 626c5289-ae23-0410-ae9c-e8d60b6d4f22
This commit is contained in:
John Lenz
parent
bc96925c9d
commit
13ad5fff85
35 changed files with 8013 additions and 4099 deletions
|
|
@ -3,12 +3,14 @@
|
|||
<html>
|
||||
<head>
|
||||
<title>SWIG and Guile</title>
|
||||
<link rel="stylesheet" type="text/css" href="style.css"/>
|
||||
</head>
|
||||
|
||||
<body bgcolor="#ffffff">
|
||||
|
||||
<H1><a name="Guile"></a>18 SWIG and Guile</H1>
|
||||
<!-- INDEX -->
|
||||
<div class="sectiontoc">
|
||||
<ul>
|
||||
<li><a href="#Guile_nn2">Meaning of "Module"</a>
|
||||
<li><a href="#Guile_nn3">Using the SCM or GH Guile API</a>
|
||||
|
|
@ -37,6 +39,7 @@
|
|||
<li><a href="#Guile_nn21">Linking</a>
|
||||
</ul>
|
||||
</ul>
|
||||
</div>
|
||||
<!-- INDEX -->
|
||||
|
||||
|
||||
|
|
@ -80,7 +83,7 @@ whatever custom API the language uses. This is currently implemented by the gui
|
|||
the SCM guile API rather than the GH guile API.
|
||||
For example, here are some of the current mapping file for the SCM API</p>
|
||||
|
||||
<blockquote><pre>
|
||||
<div class="code"><pre>
|
||||
|
||||
#define gh_append2(a, b) scm_append(scm_listify(a, b, SCM_UNDEFINED))
|
||||
#define gh_apply(a, b) scm_apply(a, b, SCM_EOL)
|
||||
|
|
@ -91,7 +94,7 @@ For example, here are some of the current mapping file for the SCM API</p>
|
|||
#define gh_cons scm_cons
|
||||
#define gh_double2scm scm_make_real
|
||||
...
|
||||
</pre></blockquote>
|
||||
</pre></div>
|
||||
|
||||
<p>This file is parsed by SWIG at wrapper generation time, so every reference to a gh_ function is replaced
|
||||
by a scm_ function in the wrapper file. Thus the gh_ function calls will never be seen in the wrapper;
|
||||
|
|
@ -111,9 +114,11 @@ policies implementing a usage convention is called a <b>linkage</b>.
|
|||
<H3><a name="Guile_nn5"></a>18.3.1 Simple Linkage</H3>
|
||||
|
||||
|
||||
<p>
|
||||
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:
|
||||
</p>
|
||||
|
||||
<ul>
|
||||
<li><b>Embedded Guile, no modules.</b> You want to embed a Guile
|
||||
|
|
@ -122,42 +127,54 @@ 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
|
||||
<li><p><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>
|
||||
libraries into Guile.</p>
|
||||
<div class="targetlang">
|
||||
<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>
|
||||
</div>
|
||||
|
||||
<p>
|
||||
Newer Guile versions provide a shorthand for <code>dynamic-link</code>
|
||||
and <code>dynamic-call</code>:
|
||||
<blockquote>
|
||||
</p>
|
||||
|
||||
<div class="targetlang">
|
||||
<pre>
|
||||
(load-extension "./example.so" "SWIG_init")
|
||||
</pre>
|
||||
</blockquote>
|
||||
</div>
|
||||
|
||||
<p>
|
||||
You need to explicitly export those bindings made by SWIG that you
|
||||
want to import into other modules:
|
||||
<blockquote>
|
||||
</p>
|
||||
|
||||
<div class="targetlang">
|
||||
<pre>
|
||||
(export foo bar)
|
||||
</pre>
|
||||
</blockquote>
|
||||
</div>
|
||||
|
||||
<p>
|
||||
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>
|
||||
</p>
|
||||
|
||||
<div class="targetlang">
|
||||
<pre>
|
||||
(module-map (lambda (sym var)
|
||||
(module-export! (current-module) (list sym)))
|
||||
(current-module))
|
||||
</pre>
|
||||
</blockquote>
|
||||
</div>
|
||||
|
||||
<p>SWIG can also generate this Scheme stub (from
|
||||
<code>define-module</code> up to <code>export</code>)
|
||||
|
|
@ -171,15 +188,18 @@ to load your extension module (with <code>dynamic-link</code> or
|
|||
information by including a directive like this in the interface file:
|
||||
</p>
|
||||
|
||||
<blockquote>
|
||||
<div class="code">
|
||||
<pre>
|
||||
%scheme %{ (load-extension "./example.so" "SWIG_init") %}
|
||||
</pre>
|
||||
</blockquote>
|
||||
</div>
|
||||
|
||||
<p>
|
||||
(The <code>%scheme</code> directive allows to insert arbitrary Scheme
|
||||
code into the generated file <code><var>module.scm</var></code>; it is
|
||||
placed between the <code>define-module</code> form and the
|
||||
<code>export</code> form.)
|
||||
</p>
|
||||
</ul>
|
||||
|
||||
<p>If you want to include several SWIG modules, you would need to rename
|
||||
|
|
@ -222,19 +242,19 @@ 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>
|
||||
<div class="targetlang">
|
||||
<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>
|
||||
</div>
|
||||
Newer Guile versions have a shorthand procedure for this:
|
||||
<blockquote>
|
||||
<div class="targetlang">
|
||||
<pre>
|
||||
(load-extension "./foo.so" "scm_init_my_modules_foo_module")
|
||||
</pre>
|
||||
</blockquote>
|
||||
</div>
|
||||
</ul>
|
||||
|
||||
<H3><a name="Guile_nn8"></a>18.3.4 Old Auto-Loading Guile Module Linkage</H3>
|
||||
|
|
@ -274,12 +294,12 @@ using the "-package" command line option to set the part of the module
|
|||
name before the last symbol. For example, both command lines:
|
||||
</p>
|
||||
|
||||
<blockquote>
|
||||
<div class="shell">
|
||||
<pre>
|
||||
swig -guile -package my/lib foo.i
|
||||
swig -guile -package my/lib -module foo foo.i
|
||||
</pre>
|
||||
</blockquote>
|
||||
</div>
|
||||
|
||||
<p>
|
||||
would create module <code>(my lib foo)</code> (assuming in the first
|
||||
|
|
@ -326,45 +346,65 @@ 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>
|
||||
<li><p><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>
|
||||
back to this behavior, use</p>
|
||||
|
||||
<div class="code">
|
||||
<pre>
|
||||
%values_as_list;</pre>
|
||||
</blockquote>
|
||||
</div>
|
||||
|
||||
<p>
|
||||
<li><em>Multiple values as vectors.</em>
|
||||
By issuing
|
||||
<blockquote>
|
||||
</p>
|
||||
|
||||
<div class="code">
|
||||
<pre>
|
||||
%values_as_vector;</pre>
|
||||
</blockquote>
|
||||
</div>
|
||||
|
||||
<p>
|
||||
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 issuing
|
||||
<blockquote>
|
||||
</p>
|
||||
|
||||
<div class="code">
|
||||
<pre>
|
||||
%multiple_values;</pre>
|
||||
</blockquote>
|
||||
</div>
|
||||
|
||||
<p>
|
||||
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>
|
||||
</p>
|
||||
|
||||
<div class="targetlang">
|
||||
<pre>
|
||||
(receive (quotient remainder)
|
||||
(divide 35 17)
|
||||
<var>body</var>...)
|
||||
</pre>
|
||||
</blockquote>
|
||||
</div>
|
||||
|
||||
<p>
|
||||
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>.
|
||||
</p>
|
||||
|
||||
</ul>
|
||||
|
||||
<p>
|
||||
See also the "multivalue" example.
|
||||
</p>
|
||||
|
||||
<H2><a name="Guile_nn12"></a>18.6 Representation of pointers as smobs</H2>
|
||||
|
||||
|
|
@ -388,6 +428,8 @@ If the Scheme object passed was not a SWIG smob representing a compatible
|
|||
pointer, a <code>wrong-type-arg</code> exception is raised.
|
||||
|
||||
<H3><a name="Guile_nn13"></a>18.6.1 GH Smobs</H3>
|
||||
|
||||
|
||||
<p>
|
||||
In earlier versions of SWIG, C pointers were represented as Scheme
|
||||
strings containing a hexadecimal rendering of the pointer value and a
|
||||
|
|
@ -450,6 +492,7 @@ the guile module replaces $owner with 0 or 1 depending on feature:new.</p>
|
|||
SWIG code calls <code>scm_error</code> on exception, using the following
|
||||
mapping:
|
||||
|
||||
<div class="code">
|
||||
<pre>
|
||||
MAP(SWIG_MemoryError, "swig-memory-error");
|
||||
MAP(SWIG_IOError, "swig-io-error");
|
||||
|
|
@ -462,6 +505,7 @@ mapping:
|
|||
MAP(SWIG_ValueError, "swig-value-error");
|
||||
MAP(SWIG_SystemError, "swig-system-error");
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
<p>
|
||||
The default when not specified here is to use "swig-error".
|
||||
|
|
@ -490,11 +534,14 @@ later.
|
|||
|
||||
<p>You need to register the generated documentation file with Guile
|
||||
like this:
|
||||
|
||||
<div class="targetlang">
|
||||
<pre>
|
||||
(use-modules (ice-9 documentation))
|
||||
(set! documentation-files
|
||||
(cons "<var>file</var>" documentation-files))
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
<p>Documentation strings can be configured using the Guile-specific
|
||||
typemap argument <code>doc</code>. See <code>Lib/guile/typemaps.i</code> for
|
||||
|
|
@ -550,7 +597,7 @@ current directory. GOOPS support requires either passive or module linkage.</p>
|
|||
<p>If <code>-emit-slot-accessors</code> is also passed as an argument,
|
||||
then the generated file will contain accessor methods for all the
|
||||
slots in the classes and for global variables. The input class</p>
|
||||
<blockquote><pre>
|
||||
<div class="code"><pre>
|
||||
class Foo {
|
||||
public:
|
||||
Foo(int i) : a(i) {}
|
||||
|
|
@ -559,9 +606,13 @@ slots in the classes and for global variables. The input class</p>
|
|||
Foo getFooMultBy(int i) { return Foo(a * i); }
|
||||
};
|
||||
Foo getFooPlus(int i) { return Foo(a + i); }
|
||||
</pre></blockquote>
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
will produce (if <code>-emit-slot-accessors</code> is not passed as a parameter)
|
||||
<blockquote><pre>
|
||||
</p>
|
||||
|
||||
<div class="targetlang"><pre>
|
||||
(define-class <Foo> (<swig>)
|
||||
(a #:allocation #:swig-virtual
|
||||
#:slot-ref primitive:Foo-a-get
|
||||
|
|
@ -578,9 +629,13 @@ will produce (if <code>-emit-slot-accessors</code> is not passed as a parameter)
|
|||
(make <Foo> #:init-smob (primitive:getFooPlus i)))
|
||||
|
||||
(export <Foo> getMultBy getFooMultBy getFooPlus )
|
||||
</pre></blockquote>
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
and will produce (if <code>-emit-slot-accessors</code> is passed as a parameter)
|
||||
<blockquote><pre>
|
||||
</p>
|
||||
|
||||
<div class="targetlang"><pre>
|
||||
(define-class <Foo> (<swig>)
|
||||
(a #:allocation #:swig-virtual
|
||||
#:slot-ref primitive:Foo-a-get
|
||||
|
|
@ -598,9 +653,13 @@ and will produce (if <code>-emit-slot-accessors</code> is passed as a parameter)
|
|||
(make <Foo> #:init-smob (primitive:getFooPlus i)))
|
||||
|
||||
(export <Foo> <b>a</b> getMultBy getFooMultBy getFooPlus )
|
||||
</pre></blockquote>
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
which can then be used by this code
|
||||
<blockquote><pre>
|
||||
</p>
|
||||
|
||||
<div class="targetlang"><pre>
|
||||
;; not using getters and setters
|
||||
(define foo (make <Foo> #:args '(45)))
|
||||
(slot-ref foo 'a)
|
||||
|
|
@ -616,13 +675,15 @@ which can then be used by this code
|
|||
(set! (a foo) 5)
|
||||
(getMultBy foo 4)
|
||||
(a (getFooMultBy foo 7))
|
||||
</pre></blockquote>
|
||||
</pre></div>
|
||||
|
||||
<p>Notice that constructor arguments are passed as a list after the <code>#:args</code> keyword. Hopefully in
|
||||
the future the following will be valid <code>(make <Foo> #:a 5 #:b 4)</code></p>
|
||||
|
||||
<p>Also note that the order the declarations occur in the .i file make a difference. For example,
|
||||
</p><blockquote><pre>
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
%module test
|
||||
|
||||
%{ #include "foo.h" %}
|
||||
|
|
@ -634,12 +695,16 @@ the future the following will be valid <code>(make <Foo> #:a 5 #:b 4)</cod
|
|||
%}
|
||||
|
||||
%include "foo.h"
|
||||
</pre></blockquote>
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
This is a valid SWIG file it will work as you think it will for primitive support, but the generated
|
||||
GOOPS file will be broken. Since the <code>someFunc</code> definition is parsed by SWIG before all the
|
||||
declarations in foo.h, the generated GOOPS file will contain the definition of <code>someFunc()</code>
|
||||
before the definition of <Foo>. The generated GOOPS file would look like
|
||||
<blockquote><pre>
|
||||
</p>
|
||||
|
||||
<div class="targetlang"><pre>
|
||||
;;...
|
||||
|
||||
(define-method (someFunc (swig_smob <Foo>))
|
||||
|
|
@ -652,9 +717,12 @@ before the definition of <Foo>. The generated GOOPS file would look like
|
|||
)
|
||||
|
||||
;;...
|
||||
</pre></blockquote>
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
Notice that <Foo> is used before it is defined. The fix is to just put the
|
||||
<code>%import "foo.h"</code> before the <code>%inline</code> block.
|
||||
</p>
|
||||
|
||||
<H3><a name="Guile_nn20"></a>18.10.1 Naming Issues</H3>
|
||||
|
||||
|
|
@ -688,10 +756,10 @@ In the previous example, the GOOPS definitions will be in a file named Test.scm.
|
|||
<p>Because of the naming conflicts, you can't in general use both the <code>-primitive</code> and the GOOPS
|
||||
guile-modules at the same time. To do this, you need to rename the exported symbols from one or both
|
||||
guile-modules. For example,</p>
|
||||
<blockquote><pre>
|
||||
<div class="targetlang"><pre>
|
||||
(use-modules ((Test-primitive) #:renamer (symbol-prefix-proc 'primitive:)))
|
||||
(use-modules ((Test) #:renamer (symbol-prefix-proc 'goops:)))
|
||||
</pre></blockquote>
|
||||
</pre></div>
|
||||
|
||||
<p>TODO: Renaming class name prefixes?</p>
|
||||
|
||||
|
|
@ -717,31 +785,35 @@ argument to solve this problem. If the <code>-exportprimitive</code> option is
|
|||
of the generated GOOPS guile-module.
|
||||
The <code>%goops</code> directive should contain code to load the .so library.
|
||||
|
||||
<blockquote><pre>
|
||||
<div class="code"><pre>
|
||||
%goops %{ (load-extension "./foo.so" "scm_init_my_modules_foo_module") %}
|
||||
</pre></blockquote>
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
Produces the following code at the top of the generated GOOPS guile-module
|
||||
(with the <code>-package my/modules -module foo</code> command line arguments)
|
||||
<blockquote><pre>
|
||||
</p>
|
||||
|
||||
<div class="targetlang"><pre>
|
||||
(define-module (my modules foo))
|
||||
|
||||
;; %goops directive goes here
|
||||
(load-extension "./foo.so" "scm_init_my_modules_foo_module")
|
||||
|
||||
(use-modules (oop goops) (Swig common))
|
||||
</pre></blockquote>
|
||||
</pre></div>
|
||||
</li>
|
||||
|
||||
<li><b>Passive Linkage with -scmstub</b>: Here, the name of the scmstub file should be
|
||||
<li><p><b>Passive Linkage with -scmstub</b>: Here, the name of the scmstub file should be
|
||||
<code>Module-primitive.scm</code> (with <i>primitive</i> replaced with whatever is given with the <code>-primsuffix</code>
|
||||
argument. The code to load the <code>.so</code> library should be located in the <code>%scheme</code> directive,
|
||||
which will then be added to the scmstub file.
|
||||
Swig will automatically generate the line <code>(use-modules (<i>Package</i> <i>Module-primitive</i>))</code>
|
||||
into the GOOPS guile-module. So if <i>Module-primitive.scm</i> is on the autoload path for guile, the
|
||||
<code>%goops</code> directive can be empty. Otherwise, the <code>%goops</code> directive should contain
|
||||
whatever code is needed to load the <i>Module-primitive.scm</i> file into guile.
|
||||
whatever code is needed to load the <i>Module-primitive.scm</i> file into guile.</p>
|
||||
|
||||
<blockquote><pre>
|
||||
<div class="targetlang"><pre>
|
||||
%scheme %{ (load-extension "./foo.so" "scm_init_my_modules_foo_module") %}
|
||||
// only include the following definition if (my modules foo) cannot
|
||||
// be loaded automatically
|
||||
|
|
@ -749,9 +821,13 @@ whatever code is needed to load the <i>Module-primitive.scm</i> file into guile.
|
|||
(primitive-load "/path/to/foo-primitive.scm")
|
||||
(primitive-load "/path/to/Swig/common.scm")
|
||||
%}
|
||||
</pre></blockquote>
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
Produces the following code at the top of the generated GOOPS guile-module
|
||||
<blockquote><pre>
|
||||
</p>
|
||||
|
||||
<div class="targetlang"><pre>
|
||||
(define-module (my modules foo))
|
||||
|
||||
;; %goops directive goes here (if any)
|
||||
|
|
@ -762,21 +838,23 @@ Produces the following code at the top of the generated GOOPS guile-module
|
|||
(use-modules ((my modules foo-primitive) :renamer (symbol-prefix-proc
|
||||
'primitive:)))
|
||||
|
||||
</pre></blockquote>
|
||||
</pre></div>
|
||||
</li>
|
||||
|
||||
<li><b>Module Linkage</b>: This is very similar to passive linkage with a scmstub file.
|
||||
<li><p><b>Module Linkage</b>: This is very similar to passive linkage with a scmstub file.
|
||||
Swig will also automatically generate the line <code>(use-modules
|
||||
(<i>Package</i> <i>Module-primitive</i>))</code> into the GOOPS guile-module. Again the <code>%goops</code>
|
||||
directive should contain whatever code is needed to get that module loaded into guile.
|
||||
directive should contain whatever code is needed to get that module loaded into guile.</p>
|
||||
|
||||
<blockquote><pre>
|
||||
<div class="code"><pre>
|
||||
%goops %{ (load-extension "./foo.so" "scm_init_my_modules_foo_module") %}
|
||||
</pre></blockquote>
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
Produces the following code at the top of the generated GOOPS guile-module
|
||||
</p>
|
||||
|
||||
<blockquote><pre>
|
||||
<div class="targetlang"><pre>
|
||||
(define-module (my modules foo))
|
||||
|
||||
;; %goops directive goes here (if any)
|
||||
|
|
@ -786,7 +864,7 @@ Produces the following code at the top of the generated GOOPS guile-module
|
|||
(use-modules ((my modules foo-primitive) :renamer (symbol-prefix-proc
|
||||
'primitive:)))
|
||||
|
||||
</pre></blockquote>
|
||||
</pre></div>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue