/tags/rel-1.3.35/Doc/Manual/Guile.html
HTML | 895 lines | 722 code | 170 blank | 3 comment | 0 complexity | 0c6a115fe5fbd212e989680cda3fe978 MD5 | raw file
Possible License(s): LGPL-2.1, Cube, GPL-3.0, 0BSD, GPL-2.0
- <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
- <!-- Hand-written HTML -->
- <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>19 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>
- <li><a href="#Guile_nn4">Linkage</a>
- <ul>
- <li><a href="#Guile_nn5">Simple Linkage</a>
- <li><a href="#Guile_nn6">Passive Linkage</a>
- <li><a href="#Guile_nn7">Native Guile Module Linkage</a>
- <li><a href="#Guile_nn8">Old Auto-Loading Guile Module Linkage</a>
- <li><a href="#Guile_nn9">Hobbit4D Linkage</a>
- </ul>
- <li><a href="#Guile_nn10">Underscore Folding</a>
- <li><a href="#Guile_nn11">Typemaps</a>
- <li><a href="#Guile_nn12">Representation of pointers as smobs</a>
- <ul>
- <li><a href="#Guile_nn13">GH Smobs</a>
- <li><a href="#Guile_nn14">SCM Smobs</a>
- <li><a href="#Guile_nn15">Garbage Collection</a>
- </ul>
- <li><a href="#Guile_nn16">Exception Handling</a>
- <li><a href="#Guile_nn17">Procedure documentation</a>
- <li><a href="#Guile_nn18">Procedures with setters</a>
- <li><a href="#Guile_nn19">GOOPS Proxy Classes</a>
- <ul>
- <li><a href="#Guile_nn20">Naming Issues</a>
- <li><a href="#Guile_nn21">Linking</a>
- </ul>
- </ul>
- </div>
- <!-- INDEX -->
- <p>
- This section details guile-specific support in SWIG.
- <H2><a name="Guile_nn2"></a>19.1 Meaning of "Module"</H2>
- <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".
- <H2><a name="Guile_nn3"></a>19.2 Using the SCM or GH Guile API</H2>
- <p>The guile module can currently export wrapper files that use the guile GH interface or the
- SCM interface. This is controlled by an argument passed to swig. The "-gh" argument causes swig
- to output GH code, and the "-scm" argument causes swig to output SCM code. Right now the "-scm" argument
- is the default. The "-scm" wrapper generation assumes a guile version >= 1.6 and has several advantages over
- the "-gh" wrapper generation including garbage collection and GOOPS support.
- The "-gh" wrapper generation can be used for older versions of guile.
- The guile GH wrapper code generation is depreciated and the
- SCM interface is the default. The SCM and GH interface differ greatly in how they store
- pointers and have completely different run-time code. See below for more info.
- <p>The GH interface to guile is deprecated. Read more about why in the
- <a href="http://www.gnu.org/software/guile/docs/guile-ref/GH-deprecation.html">Guile manual</a>.
- The idea of the GH interface was to provide a high level API that other languages and projects
- could adopt. This was a good idea, but didn't pan out well for general development. But for the
- specific, minimal uses that the SWIG typemaps put the GH interface to use is ideal for
- using a high level API. So even though the GH interface is depreciated, SWIG will continue to use
- the GH interface and provide mappings from the GH interface to whatever API we need.
- We can maintain this mapping where guile failed because SWIG uses a small subset of all the GH functions
- which map easily. All the guile typemaps like typemaps.i and std_vector.i
- will continue to use the GH functions to do things like create lists of values, convert strings to
- integers, etc. Then every language module will define a mapping between the GH interface and
- whatever custom API the language uses. This is currently implemented by the guile module to use
- 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>
- <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)
- #define gh_bool2scm SCM_BOOL
- #define gh_boolean_p SCM_BOOLP
- #define gh_car SCM_CAR
- #define gh_cdr SCM_CDR
- #define gh_cons scm_cons
- #define gh_double2scm scm_make_real
- ...
- </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;
- the wrapper will look exactly like it was generated
- for the specific API. Currently only the guile language module has created a mapping policy from gh_ to scm_,
- but there is no reason other languages (like mzscheme or chicken) couldn't also use this.
- If that happens, there is A LOT less code duplication in the standard typemaps.</p>
- <H2><a name="Guile_nn4"></a>19.3 Linkage</H2>
- <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>.
- <H3><a name="Guile_nn5"></a>19.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
- 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><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.</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>
- </div>
- <p>
- Newer Guile versions provide a shorthand for <code>dynamic-link</code>
- and <code>dynamic-call</code>:
- </p>
- <div class="targetlang">
- <pre>
- (load-extension "./example.so" "SWIG_init")
- </pre>
- </div>
- <p>
- You need to explicitly export those bindings made by SWIG that you
- want to import into other modules:
- </p>
- <div class="targetlang">
- <pre>
- (export foo bar)
- </pre>
- </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:
- </p>
- <div class="targetlang">
- <pre>
- (module-map (lambda (sym var)
- (module-export! (current-module) (list sym)))
- (current-module))
- </pre>
- </div>
- <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</code>. The code will be exported in a file called
- <code><i>module</i>.scm</code> in the directory specified by <code>-outdir</code>
- or the current directory if <code>-outdir</code> is not specified.
- 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:
- </p>
- <div class="code">
- <pre>
- %scheme %{ (load-extension "./example.so" "SWIG_init") %}
- </pre>
- </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
- <code>SWIG_init</code> via a preprocessor define to avoid symbol
- clashes. For this case, however, passive linkage is available.
- <H3><a name="Guile_nn6"></a>19.3.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.
- <H3><a name="Guile_nn7"></a>19.3.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.
- <div class="targetlang">
- <pre>
- (define my-so (dynamic-link "./foo.so"))