SWIG Internals Manual

$Header$

(Note : This is a work in progress.)

1. Introduction

The audience is assumed to be SWIG developers (who should also read the SWIG Engineering Manual before starting to code).

Directory Guide

Overall Program Flow

• Modules1.1/swigmain.cxx:main() is the program entry point. It parses the language-specifying command-line option (for example, -java), creating a new language-specific wrapping object (each language is a C++ class derived from base class Language). This object and the command-line is passed to SWIG_main(), whose return value is the program exit value.
• SWIG1.1/main.cxx:SWIG_main() is the "real" main. It initializes the preprocessor and typemap machinery, defines some preprocessor symbols, locates the SWIG library, processes common command-line options, and then calls the language-specific command-line parser. From here there are three paths: "help", "checkout" and everything else.
  • In "help" mode, clean up open files and exit.
  • In "checkout" mode, copy specified files from the SWIG library to the current directory. Errors cause error messages but no non-lcoal exits.
  • Otherwise, do wrapping: determine output file name(s), define some preprocessor symbols and run the preprocessor, initialize the interface-definition parser, set up the typemap for handling new return strings, and finally do the language-specific parse (by calling the language object's parse() method), which creates output files by side-effect.
  Afterwards, remove temporary files, and clean up. If the command-line included -freeze, go into an infinite loop; otherwise return the error count.
• The language-specific parse() (and all other language-specific code) lives in Modules1.1/foo.{h,cxx} for language Foo. Typically, FOO::parse() calls FOO::headers() and then the global function yyparse(), which uses the callbacks registered by SWIG_main() above.

Table of Contents

• 2. DOH
• 3. Types and Typemaps
• 4. Parsing
• 5. Difference Between SWIG 1.1 and SWIG 1.3
• 6. Plans for SWIG 2.0
• 7. Reserved
• 8. Reserved
• 9. Reserved
• 10. Guile Support
• 11. Python Support
• 12. Perl Support
• 13. Java Support

Meaning of "Module"

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".

Linkage

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. The default linkage is the simplest; nothing special is done. In this case SWIG_init() is provided and users must do something like this:

(define my-so (dynamic-link "./example.so"))
(dynamic-call "SWIG_init" my-so)

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.

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: [checkme:ttn]

swig -guile -package my/lib foo.i
swig -guile -package my/lib -module foo foo.i

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 GUILE::emit_linkage().

Underscore Folding

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.

Typemaps

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:

%include guile/typemaps.i

Smobs

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.

Currently, one wrapper module must be generated without -c and compiled with -DSWIG_GLOBAL, all the other wrapper modules must be generated with -c. Maybe one should move all the global helper functions that come from guile.swg into a library, which is built by make runtime.

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. 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_Guile_MakePtr_Str(), 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.

To get the pointer represented by a smob, the wrapper code calls the function SWIG_Guile_GetPtr_Str, 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 wrong-type-arg exception is raised.

Exception Handling

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.

10. Python Support