jyapayne/swig
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

(Guile Support Internals): Move section to internals.html.

Browse source 
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 2000-06-28 02:21:20 +00:00
commit 71a336e1f3
1 changed files with 1 additions and 162 deletions
Download patch file Download diff file Expand all files Collapse all files

163
SWIG/Doc/engineering.html
View file

@ -403,168 +403,7 @@ making your changes.
</ul> </ul>
<h2>10. Guile Support Internals</h2> <h2>10. Miscellaneous </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>#&lt;swig struct xyzzy * 0x1234affe&gt;</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>
<ul> <ul>
<li> Do not use the ternary ?: operator. It is unnecessarily error prone, <li> Do not use the ternary ?: operator. It is unnecessarily error prone,