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

2.1 Motivation and Background

DOH takes a different approach to tackling the complexity problem. First, rather than going overboard with dozens of types and class definitions, DOH only defines a handful of simple yet very useful objects that are easy to remember. Second, DOH uses dynamic typing---one of the features that make scripting languages so useful and which make it possible to accomplish things with much less code. Finally, DOH utilizes a few coding tricks that allow it to perform a limited form of function overloading for certain C datatypes (more on that a little later).

The key point to using DOH is that instead of thinking about code in terms of highly specialized C data structures, just about everything ends up being represented in terms of a just a few datatypes. For example, structures are replaced by DOH hash tables whereas arrays are replaced by DOH lists. At first, this is probably a little strange to most C/C++ programmers, but in the long run in makes the system extremely flexible and highly extensible. Also, in terms of coding, many of the newly DOH-based subsystems are less than half the size (in lines of code) of the earlier C++ implementation.

2.2 Basic Types

• String. A string of characters with automatic memory management and high-level operations such as string replacement. In addition, strings support file I/O operations that make it possible to use them just about anyplace a file can be used.

• List. A list of arbitrary DOH objects (of possibly mixed types).

• Hash. A hash table that maps a set of string keys to a set of arbitrary DOH objects. The DOH version of an associative array for all of you Perl fans.

• File. A DOH wrapper around the C FILE * structure. This is provided since other objects sometimes want to behave like files (strings for instance).

• Void. A DOH wrapper around an arbitrary C pointer. This can be used if you want to place arbitrary C data structures in DOH lists and hash tables.

• DOHString *. A String object.
• DOHList *. A list object.
• DOHHash *. A hash object.
• DOHFile *. A file object.
• DOHVoid *. A void object.
• DOHString_or_char *. A DOH String object or a raw C "char *".

2.3 Creating, Copying, and Destroying Objects

• NewString(DOHString_or_char *value)
  Create a new string object with contents initially set to value. value can be either a C string or a DOH string object.

• NewStringf(char *fmt, ...)
  Create a new string object with contents initially set to a formatted string. Think of this as being sprintf() combined with an object constructor.

• NewList()
  Create a new list object that is initially empty.

• NewHash()
  Create a new hash object that is initially empty.

• NewFile(DOHString_or_char *filename, char *mode)
  Open a file and return a file object. This is a wrapper around the C fopen() library call.

• NewFileFromFile(FILE *f)
  Create a new file object given an already opened FILE * object.

• NewVoid(void *obj, void (*del)(void *))
  Create a new DOH object that is a wrapper around an arbitrary C pointer. del is an optional destructor function that will be called when the object is destroyed.

DOH *a, *b, *c, *d;
a = NewString("Hello World");
b = NewList();
c = Copy(a);         /* Copy the string a */
d = Copy(b);         /* Copy the list b */

Objects can be deleted using the Delete() function. For example:

DOH *a = NewString("Hello World");
...
Delete(a);              /* Destroy a */

DOH *a, *b;
a = NewString("Hello World");
b = NewList();
Append(b,a);         /* Increases refcnt of a to 2 */
Delete(a);           /* Decreases refcnt of a to 1 */
Delete(b);           /* Destroys b, and destroys a */

DOH *a = NewString("Hello");
DohIncref(a);

2.4 A Word About Mutability and Copying

2.5 Strings

2.6 Lists

2.7 Hash tables

2.8 Files

2.9 Void objects

2.10 Utility functions

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 uses Guile smobs. This feature used to be available only SWIG was invoked with the command-line option "-with-smobs", but as of 2000/07/06 (swig-1.3a4) this is the default behavior; the command-line option "-with-smobs" is ignored silently. We plan to drop silent recognition of this option after 1.3a4.

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