$Header$ +
+(Note : This is a work in progress.) +
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. +project and continued in this mode of operation until about 1998. +Most of this development was driven by ideas submitted by early SWIG +users as opposed to being motivated by a grand design. As a result, +the code ended up being a pretty horrible C++ coding disaster. A +mostly working disaster perhaps, 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. +With that said, the primary goal of future SWIG development is to +reengineer the original system, fix most of its inherent design flaws, +and to produce what I hope will become a highly extensible and modular +interface compiler framework. To this do this, there are a few +critical areas of work. First, I want to restructure SWIG as a +collection of loosely coupled modules written in either ANSI C or an +scripting language. Second, I want the system to be minimalistic in +its use of data structures and interconnections. The primary reason +for this is that the fewer data structures there are, the less users +will have to remember. This will also make the system more accessible +to non-experts. Finally, I want to reevaluate the whole idea of 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. +The rest of this document outlines a few general rules of how code +should be developed within the SWIG project. These rules are +primarily drawn from my own experience developing software and +observing the practices of other successful projects.
-Modules should make every attempt to use only those functions +Module writers 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. +that it can be omitted on problematic platforms. If you are unsure +about a library call, check the man page or contact Dave.
-All header files should have include guards and be C++ aware. For example: +All header files should include a short description, author information, copyright message, +CVS version, include guards, and be C++ aware. For example:
+/* ----------------------------------------------------------------------------- + * swigperl.h + * + * All of the externally visible functions in the Perl module. + * + * Author(s) : David Beazley (beazley@cs.uchicago.edu) + * + * Copyright (C) 1999-2000, The University of Chicago. + * See the file LICENSE for information on usage and redistribution. + * + * $Header$ + * ----------------------------------------------------------------------------- */ + #ifndef _SWIGPERL_H #define _SWIGPERL_H 1 @@ -140,30 +158,26 @@ are case-insensitive on Windows so this convention will prevent you from inadver 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: +Each file should include a short abstract, author information, copyright information, and +a CVS revision tag like this:
/* ----------------------------------------------------------------------------- - * Simplified Wrapper and Interface Generator (SWIG) + * 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. * * Author(s) : David Beazley (beazley@cs.uchicago.edu) * - * Copyright (C) 1999-2000, University of Chicago. + * Copyright (C) 1999-2000, The 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 */ @@ -187,14 +201,14 @@ static int avariable; 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. +(sometimes useful in debugging).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. +about 2000 lines. Files larger than this should be broken up into +multiple files. Similarly, you should avoid the temptation to create +many small files as this increases compilation time and makes the +directory structure too complicated.
6. Bottom-Up Design
@@ -242,7 +256,7 @@ and a short description like this:-As for the function declaration itself, the return type and specifiers +In the function declaration, the return type and any specifiers (extern or static) should appear on a separate line followed by the -function name as shown. +function name and arguments as shown above. The left curly brace +should appear on the same line as the function name. + +/* ----------------------------------------------------------------------------- - * void Swig_add_directory(DOH *dirname) + * Swig_add_directory() * * Adds a directory to the SWIG search path. * ----------------------------------------------------------------------------- */ @@ -255,17 +269,23 @@ Swig_add_directory(DOH *dirname) {+Function declarations should NOT use the pre-ANSI function +declaration syntax. The ANSI standard has been around long enough for +this to be a non-issue.
8. Naming Conventions
-The following conventions are generally used to name various objects throughout SWIG. +The following conventions are used to name various objects throughout SWIG.Functions
-Functions should consist of the module name and the function separated by an underscore like this: +Functions should consist of the module name and the function name separated by an underscore like this:-Separate words in a constant should be separated by underscores as shown. +Separate words in a constant should be separated by underscores as with functions.@@ -280,7 +300,7 @@ words separated by underscores.Structures and Types
-If you module defines structures, the structure name should include the name of the +If your module defines new structures, the structure name should include the name of the module and the name of the structure appended together like this:@@ -314,12 +334,12 @@ Constants should be created using #define and should be in all caps like this: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. +as for function names. However, the module name does not have to be included. For example:@@ -339,12 +359,12 @@ typedef struct 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. +Static declarations are free to use any naming convention that is appropriate. However, most +existing parts of SWIG use lower-case names and follow the same convention as described for functions.9. Visibility
-Module should play by the following rules when exposing their interface: +Modules should keep the following rules in mind when exposing their internals:
- Only publicly accessible functions should be included in the module header file. @@ -354,7 +374,7 @@ to avoid potential linker namespace conflicts with other modules. 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: +instead of providing a user with a structure like this:
-It is better to simply hide the implementation of Foo and provide an interface like this: +It is better to hide the implementation of Foo and provide an function-call interface like this:@@ -364,7 +384,7 @@ typedef struct Foo {-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). - +Although this results in worse performance, there are many practical reasons for doing +this. The most important reason is that it allows you to change the internal representation +of Foo without breaking all of the other modules or having to recompile the entire +universe after making your changes.@@ -374,10 +394,10 @@ extern void Foo_setline(Foo *f, int line);