(Guile Support Internals): Move section to internals.html.
The result is largely the same as revision 1.4. git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk@501 626c5289-ae23-0410-ae9c-e8d60b6d4f22
This commit is contained in:
Thien-Thi Nguyen
parent
ed8de1679f
commit
71a336e1f3
1 changed files with 1 additions and 162 deletions
|
|
@ -403,168 +403,7 @@ making your changes.
|
|||
|
||||
</ul>
|
||||
|
||||
<h2>10. Guile Support Internals</h2>
|
||||
|
||||
Please direct questions about this section to
|
||||
<a href="mailto:ttn@glug.org">ttn@glug.org</a>.
|
||||
Last update: 2000-04-03 05:27:34-0700.
|
||||
|
||||
<h3>Meaning of "Module"</h3>
|
||||
|
||||
<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".
|
||||
|
||||
<h3>Linkage</h3>
|
||||
|
||||
<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>. The default
|
||||
linkage is the simplest; nothing special is done. In this case
|
||||
<code>SWIG_init()</code> is provided and users must do something like this:
|
||||
|
||||
<blockquote>
|
||||
<pre>
|
||||
(define my-so (dynamic-link "./example.so"))
|
||||
(dynamic-call "SWIG_init" my-so)
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
At this time, the name <code>SWIG_init</code> is hardcoded; this approach does
|
||||
not work with multiple swig-modules. NOTE: The "simple" and "matrix" examples
|
||||
under Examples/guile include guilemain.i; the resulting standalone interpreter
|
||||
does not require calls to <code>dynamic-link</code> and
|
||||
<code>dynamic-call</code>, as shown here.
|
||||
|
||||
<p>
|
||||
A second linkage creates "libtool dl module" wrappers, and currently is
|
||||
broken. Whoever fixes this needs to track Guile's libtool dl module
|
||||
convention, since that is not finalized.
|
||||
|
||||
<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: [checkme:ttn]
|
||||
|
||||
<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.
|
||||
|
||||
<p>
|
||||
There are no other linkage types planned, but that could change... To add a
|
||||
new type, add the name to the enum in guile.h and add the case to
|
||||
<code>GUILE::emit_linkage()</code>.
|
||||
|
||||
<h3>Underscore Folding</h3>
|
||||
|
||||
<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.
|
||||
|
||||
<h3>Typemaps</h3>
|
||||
|
||||
<p>
|
||||
It used to be that the mappings for "native" types were included in
|
||||
guile.cxx. This information is now in Lib/guile/typemaps.i, which presents a
|
||||
new challenge: how to have SWIG include typemaps.i before processing the
|
||||
user's foo.i. At this time, we must say:
|
||||
|
||||
<blockquote>
|
||||
<pre>
|
||||
%include guile/typemaps.i
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
in foo.i. This may change in the future.
|
||||
|
||||
<h3>Smobs</h3>
|
||||
|
||||
<p>
|
||||
For pointer types, SWIG can use Guile smobs if given the command-line
|
||||
option "-with-smobs". Ultimately this will be the default (and only)
|
||||
behavior and the command-line option will no longer be supported.
|
||||
Ideally, "-with-smobs" will not even make it to beta.
|
||||
|
||||
<p>
|
||||
Currently, one wrapper module must be generated without
|
||||
<code>-c</code> and compiled with <code>-DSWIG_GLOBAL</code>, all the
|
||||
other wrapper modules must be generated with <code>-c</code>. Maybe
|
||||
one should move all the global helper functions that come from
|
||||
<code>guile.swg</code> into a library, which is built by <code>make
|
||||
runtime</code>.
|
||||
|
||||
<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_Str()</code>, passing both a
|
||||
mangled type string and a pretty type string. The former is looked up
|
||||
in the type table to get the type index to store in the upper half of
|
||||
the CAR. If the type is new, it is appended to type table.
|
||||
|
||||
<p>
|
||||
To get the pointer represented by a smob, the wrapper code calls the
|
||||
function <code>SWIG_Guile_GetPtr_Str</code>, passing the mangled name
|
||||
of the expected pointer type, which is used for looking up the type in
|
||||
the type table and accessing the list of compatible types. If the
|
||||
Scheme object passed was not a SWIG smob representing a compatible
|
||||
pointer, a <code>wrong-type-arg</code> exception is raised.
|
||||
|
||||
<h3>Exception Handling</h3>
|
||||
|
||||
<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.
|
||||
|
||||
|
||||
<h2>11. Miscellaneous </h2>
|
||||
<h2>10. Miscellaneous </h2>
|
||||
|
||||
<ul>
|
||||
<li> Do not use the ternary ?: operator. It is unnecessarily error prone,
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue