This section details guile-specific support in SWIG.
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".
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 "-gh" 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 possibly GOOPS support in the future.
The "-gh" wrapper generation can be used for older versions of guile. Thus eventually
the guile GH wrapper code generation will be depreciated (as guile 1.6 and above become more common) and the
SCM interface will become the default. The SCM and GH interface differ greatly in how they store
pointers and have completly different run-time code. See below for more info.
make runtime will now produce two libraries, libguilegh and libguilescm containing the
runtime code using the two different guile API's.
The GH interface to guile is deprecated. Read more about why in the Guile manual. 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
#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 ...
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.
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 linkage.
SWIG_init() is exported. Simple linkage
can be used in several ways:
SWIG_init() in the
inner_main() function. See the "simple" and "matrix" examples under
Examples/guile.
define-module, containing both Scheme code and
bindings made by SWIG; you want to load the SWIG modules as shared
libraries into Guile.
Newer Guile versions provide a shorthand for(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
dynamic-link
and dynamic-call:
You need to explicitly export those bindings made by SWIG that you want to import into other modules:(load-extension "./example.so" "SWIG_init")
In this example, the procedures(export foo bar)
foo and bar
would be exported. Alternatively, you can export all bindings with the
following module-system hack:
(module-map (lambda (sym var) (module-export! (current-module) (list sym))) (current-module))
SWIG can also generate this Scheme stub (from
define-module up to export)
semi-automagically if you pass it the command-line argument
-scmstub foo.scm. Since SWIG doesn't know how
to load your extension module (with dynamic-link or
load-extension), you need to supply this
information by including a directive like this in the interface file:
%scheme %{ (load-extension "./example.so" "SWIG_init") %}
(The %scheme directive allows to insert arbitrary Scheme
code into the generated file foo.scm; it is
placed between the define-module form and the
export form.)
If you want to include several SWIG modules, you would need to rename
SWIG_init via a preprocessor define to avoid symbol
clashes. For this case, however, passive linkage is available.
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).
You should use passive linkage rather than simple linkage when you are using multiple modules.
SWIG can also generate wrapper code that does all the Guile module
declarations on its own if you pass it the -Linkage
module command-line option. This requires Guile 1.5.0 or later.
The module name is set with the -package and
-module command-line options. Suppose you want to define
a module with name (my lib foo); then you would have to
pass the options -package my/lib -module
foo. Note that the last part of the name can also be set
via the SWIG directive %module.
You can use this linkage in several ways:
scm_init_my_modules_foo_module
in the inner_main() function.
Newer Guile versions have a shorthand procedure for this:(define my-so (dynamic-link "./foo.so")) ;; create new module and put bindings there: (dynamic-call "scm_init_my_modules_foo_module" my-so)
(load-extension "./foo.so" "scm_init_my_modules_foo_module")
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 -Linkage ltdlmod
command-line option.
Auto-loading worked like this: Suppose a module with name (my
lib foo) is required and not loaded yet. Guile will then search
all directories in its search path
for a Scheme file my/modules/foo.scm or a shared library
my/modules/libfoo.so (or
my/modules/libfoo.la;
see the GNU libtool documentation). If a
shared library is found that contains the symbol
scm_init_my_modules_foo_module,
the library is loaded, and the function at that symbol is called with
no arguments in order to initialize the module.
When invoked with the -Linkage ltdlmod command-line
option, SWIG generates an exported module initialization function with
an apropriate name.
The only other linkage supported at this time creates shared object
libraries suitable for use by hobbit's (hobbit4d link)
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:
would create moduleswig -guile -package my/lib foo.i swig -guile -package my/lib -module foo foo.i
(my lib foo) (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.
-c command-line argument. Compile all wrapper files
with the C compiler switch -DSWIG_GLOBAL.
-c
command-line argument and compile all wrapper files with the C
compiler switch -DSWIG_GLOBAL. Then link against the
runtime library libswigguile or libswigguilescm, which is built by
make runtime. The needed linker flags are reported by
SWIG if you invoke it with the -guile -ldflags
command-line arguments.
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.
You can use the SWIG directives %name and
%rename to specify the Guile name of the wrapped
functions and variables (see CHANGES).
The Guile module handles all types via typemaps. This
information is read from Lib/guile/typemaps.i.
Some non-standard typemap substitutions are supported:
$descriptor expands to a type descriptor for use with
the SWIG_NewPointerObj() and
SWIG_ConvertPtr functions.
$*descriptor expands to a
descriptor for the direct base type (i.e., one pointer is stripped),
whereas $basedescriptor expands to a
descriptor for the base type (i.e., all pointers are stripped).
A function returning void (more precisely, a function
whose out typemap returns SCM_UNSPECIFIED) is
treated as returning no values. In argout typemaps, one
can use the macro GUILE_APPEND_RESULT in order to append
a value to the list of function return values.
Multiple values can be passed up to Scheme in one of three ways:
%values_as_list;
vectors instead of lists will be used.%values_as_vector;
multiple values are passed to the multiple-value continuation, as created by%multiple_values;
call-with-values or the
convenience macro receive. The latter is available if you
issue (use-modules (srfi srfi-8)). Assuming that your
divide function
wants to return two values, a quotient and a remainder, you can write:
(receive (quotient remainder)
(divide 35 17)
body...)
In body, the first result of
divide will be bound to the variable
quotient, and the second result to remainder.
For pointer types, SWIG uses Guile smobs. SWIG smobs print
like this: #<swig struct xyzzy * 0x1234affe> Two of
them are equal? if and only if they have the same type
and value.
To construct a Scheme object from a C pointer, the wrapper code calls
the function SWIG_NewPointerObj(), 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.
To get the pointer represented by a smob, the wrapper code calls the
function SWIG_ConvertPtr(), passing a pointer to a struct
representing the expected pointer type. See also
Section 8.8 The run-time type checker.
If the Scheme object passed was not a SWIG smob representing a compatible
pointer, a wrong-type-arg exception is raised.
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.
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. SWIG_Guile_Init() registers a smob type named
"swig" with Guile; its type tag is stored in the variable
swig_tag. 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.
The SCM interface (using the "-scm" argument to swig) uses common.swg. The whole type system, when it is first initialized, creates two smobs named "swig" and "collected_swig". The swig smob is used for non-garbage collected smobs, while the collected_swig smob is used as described below. Each smob has the same format, which is a double cell created by SCM_NEWSMOB2() The first word of data is the pointer to the object and the second word of data is the swig_type_info * structure describing this type. This is a lot easier than the GH interface above because we can store a pointer to the type info structure right in the type. With the GH interface, there was not enough room in the smob to store two whole words of data so we needed to store part of the "swig_type_info address" in the smob tag.
Garbage collection is a feature of the new SCM interface, and it is automaticlly included if you pass the "-scm" flag to swig. Thus the swig garbage collection support requires guile >1.6. Garbage collection works like this. Every swig_type_info structure stores in its clientdata field a pointer to the destructor for this type. The destructor is the generated wrapper around the delete function. So swig still exports a wrapper for the destructor, it just does not call scm_c_define_gsubr() for the wrapped delete function. So the only way to delete an object is from the garbage collector, since the delete function is not available to scripts. How swig determins if a type should be garbage collected is exactly like described in Section 9.2 Object ownership and %newobject in the SWIG manual. All typemaps use an $owner var, and the guile module replaces $owner with 0 or 1 depending on feature:new.
SWIG code calls scm_error on exception, using the following
mapping:
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");
The default when not specified here is to use "swig-error". See Lib/exception.i for details.
If invoked with the command-line option -procdoc
file, SWIG creates documentation strings for the
generated wrapper functions, describing the procedure signature and
return value, and writes them to file. You need Guile 1.4
or later to make use of the documentation files.
SWIG can generate documentation strings in three formats, which are
selected via the command-line option -procdocformat
format:
guile-1.4 (default): Generates a format suitable for Guile 1.4.
plain: Generates a format suitable for Guile 1.4.1 and
later.
texinfo: Generates texinfo source, which must be run
through texinfo in order to get a format suitable for Guile 1.4.1 and
later.
You need to register the generated documentation file with Guile like this:
(use-modules (ice-9 documentation))
(set! documentation-files
(cons "file" documentation-files))
Documentation strings can be configured using the Guile-specific
typemaps indoc, outdoc,
argoutdoc, varindoc, and
varoutdoc. See Lib/guile/typemaps.i for
details.
For global variables, SWIG creates a single wrapper procedure
(variable :optional value), which is used for
both getting and setting the value. For struct members, SWIG creates
two wrapper procedures (struct-member-get
pointer) and (struct-member-set pointer value).
If invoked with the command-line option -emit-setters,
SWIG will additionally create procedures with setters. For global
variables, the procedure-with-setter variable
is created, so you can use (variable) to get
the value and (set! (variable)
value) to set it. For struct members, the
procedure-with-setter struct-member
is created, so you can use (struct-member
pointer) to get the value and (set!
(struct-member pointer)
value) to set it.