SWIG Engineering Manual

David Beazley
Department of Computer Science
University of Chicago
Chicago, IL 60637
beazley@cs.uchicago.edu

$Header$

1. Introduction

The purpose of this document is to describe various coding conventions and organizational aspects for SWIG developers. The idea for this document is largely borrowed from John Ousterhout's Tcl/Tk Engineering Manual. It is not my intent to overly managerial about matters--rather the intent is to make life a little less chaotic for everyone involved.

First a little background: SWIG was started in 1995 as a one-person project and continued in this mode until about 1998 (at which point development all but stopped due to some sort of post-dissertation shock syndrome). Unfortunately, as a result, the state of the code can best be described as being a huge hacked up C++ disaster. A working disaster, but a disaster nonetheless.

The primary goal of future SWIG development is to reengineer the original system and address many of its design flaws and to produce what can best be described as a highly extensible and modular compiler framework. To this end, there are a few things I want to do. First, I want to restructure SWIG as a collection of loosely coupled modules written in either ANSI C or scripting languages. Second, I want the system to be minimalistic in its use of data structures and interconnections (e.g., almost all data in the new system is passed around in hash tables for instance). The primary reason for this is that the fewer data structures there are, the less you have to remember. Finally, I was to reevaluate the whole idea of what a SWIG module is and expand the definition to include just about anything from parsers, preprocessors, optimizers, interface editors, and code generators.

The rest of this document describes the basics of how to develop code for SWIG and a few useful guidelines.

2. Programming Languages and Libraries

All SWIG modules must be written in either ANSI C or one of the scripting languages for which SWIG can generate an interface (e.g., Perl, Python, or Tcl). C++ is NOT an acceptable alternative and will not be utilized for any future development due to the fact that it is too complicated, too problematic, and that Dave would rather take a bullet to the head than write one more line of code in this most decidedly unpleasant language. Rare exceptions to this rule may be made if there is a justifiable need to interface an existing piece of software written in C++ into the SWIG module system. Anyone who finds this rule to be unreasonable is more than welcome to go write their own wrapper generator--so there.

Modules should make every attempt to use only those functions described in the POSIX.1 standard. This includes most of the functions contained the Kernighan and Ritchie C programming book. Use of operating system dependent functionality such as socket libraries should always be included inside a conditional compilation block so that it can be omitted on problematic platforms. If you are unsure about a library call, check the man page or contact Dave.

3. The Source Directory and Module Names

All SWIG modules are contained within the "Source" directory. Within this directory, each module is placed into its own subdirectory. The name of this subdirectory should exactly match the name of the module. For example, if you are creating a module called "Tcl", all of your files should be placed in a directory "Tcl".

When choosing a module name, please pick a name that is not currently in use. As a general convention, the first letter of a module name is capitalized such as "Perl". Alternatives such as "perl" or "PERL" should be avoided. In certain instances, the first two letters may be capitalized as in "CParse." The exact usage of this is somewhat inconsistent and isn't terribly important--just make sure the first letter is capitalized. Also, module names should not start with numbers, include underscores or any other special non-alphanumeric characters.

4. Include files

All modules should include a header file that defines the public interface. The name of this header file should be of the form "swigmodule.h" where "module" is the name of your module. For example, if you created a module "Perl", the header file should be named "swigperl.h". This scheme should prevent header-file naming conflicts both within SWIG and when linking parts of SWIG to the outside world.

All header files should have include guards and be C++ aware. For example:

#ifndef _SWIGPERL_H
#define _SWIGPERL_H   1

#ifdef __cplusplus
extern "C" {
#endif

/* You're declarations here */
...

#ifdef __cplusplus
}
#endif

#endif  /* _SWIGPERL_H */

To minimize compilation time, please include as few other header files as possible.

5. File Structure

Each file in a module should be given a filename that is all lowercase letters such as "parser.c", not "Parser.c" or "PARSER.c". Please note that filenames are case-insensitive on Windows so this convention will prevent you from inadvertantly creating two files that differ in case-only.

The structure of each file should include a short copyright message, author information, a CVS revision tag, and an abstract like this:

/* -----------------------------------------------------------------------------
 * Simplified Wrapper and Interface Generator (SWIG)
 * 
 * Author(s) : David Beazley (beazley@cs.uchicago.edu)
 *
 * Copyright (C) 1999-2000, University of Chicago.
 * See the file LICENSE for information on usage and redistribution. 
 * ----------------------------------------------------------------------------- */

static char cvsroot[] = "$Header$";

/* -----------------------------------------------------------------------------
 * include.c
 *
 * This file implements the functions used to locate and include files in
 * the SWIG library.  Functions for maintaining the library search path are
 * also located here.
 * ----------------------------------------------------------------------------- */

#include "swig.h"

/* Declarations */
typedef struct {
   int x, y;
} Foo;

...

/* Private Declarations (used only in this file) */
static int  avariable;

...

/* Functions */
...

The CVS revision tag should be placed into a static string as shown above. This adds the revision information to the SWIG executable and makes it possible to extract version information from a raw binary (sometimes useful in debugging). Copyright messages do not need to be attributed to the University of Chicago provided that the module is released under an Open Source copyright that allows redistribution.

As a general rule, files start to get unmanagable once they exceed about 2000 lines. Files larger than this should be broken up into multiple files.

6. Bottom-Up Design

Within each source file, the preferred organization is to use what is known as "bottom-up" design. Under this scheme, lower-level functions appear first and the highest level function appears last. The easy way to remember is that the "main" function of your module should always appear last in the source file. For example:

/* Simple bottom-up program */
#include <stdio.h>

int foo(int x, int y) {
    /* Implement foo */
    ...
}

int bar() {
    ...
    foo(i,j);
    ...
}

...
int main(int argc, char **argv) {
    ...
    bar();   
    ...
}

This choice of design is somewhat arbitrary however it has a number of benefits particular to C. In particular, a bottom-up design generally eliminates the need to include forward references--resulting in cleaner code and fewer compilation errors.

7. Functions

All functions should have a function header that gives the function name and a short description like this:

/* -----------------------------------------------------------------------------
 * void Swig_add_directory(DOH *dirname)
 *
 * Adds a directory to the SWIG search path.
 * ----------------------------------------------------------------------------- */

void 
Swig_add_directory(DOH *dirname) {
...

}

As for the function declaration itself, the return type and specifiers (extern or static) should appear on a separate line followed by the function name as shown.

8. Naming Conventions

The following conventions are generally used to name various objects throughout SWIG.

Functions

Functions should consist of the module name and the function separated by an underscore like this:

Preprocessor_define()
Swig_add_directory()

In general, the module name should match the name of the module subdirectory and the function name should be in all lowercase with words separated by underscores.

Structures and Types

If you module defines structures, the structure name should include the name of the module and the name of the structure appended together like this:

typedef struct SwigScanner {
   ...
} SwigScanner;

typedef struct LParseType {
   ...
} LParseType;

In this case, both the name of the module and the type should be capitalized. Also, whenever possible, you should use the "typedef struct Name { ... } Name" form when defining new data structures.

Global Variables

Global variables should be avoided if at all possible. However, if you must use a global variable, please prepend the module name and use the same naming scheme as for functions.

Constants

Constants should be created using #define and should be in all caps like this:

#define   SWIG_TOKEN_LPAREN  1

Separate words in a constant should be separated by underscores as shown.

Structure members

Structure members should be in all lower-case and follow the same word-separation convention as for function names. However, the module name does not have to be included on members. For example:

typedef struct SwigScanner {
  DOH           *text;           /* Current token value */
  DOH           *scanobjs;       /* Objects being scanned */
  DOH           *str;            /* Current object being scanned */
  char          *idstart;        /* Optional identifier start characters */
  int            next_token;     /* Next token to be returned */
  int            start_line;     /* Starting line of certain declarations */
  int            yylen;          /* Length of text pushed into text */
  DOH           *file;           /* Current file name */
} SwigScanner;

Static Functions and Variables

Static declarations are free to use any naming convention. However, most existing parts of the SWIG simply use all lower-case names.

9. Visibility

Module should play by the following rules when exposing their interface:

Only publicly accessible functions should be included in the module header file.
All non-static declarations must be prepended with some form of the module name to avoid potential linker namespace conflicts with other modules.
Modules should not expose global variables or use global variables in their public interface.
Similarly, modules should discourage the direct manipulation of data contained within data structures in favor of using function calls instead. For example, instead of having this:
```
typedef struct Foo {
   int line;
} Foo;
```
It is better to simply hide the implementation of Foo and provide an interface like this:
```
typedef struct Foo Foo;
extern int  Foo_getline(Foo *f);
extern void Foo_setline(Foo *f, int line);
```
There are many good reasons for doing this not the least of which is that it allows you to change the internal representation of Foo without breaking everyone else's module (or at the very least having to recompile the universe).