From b0b3ba31c4e90ebaf1012676c44bd19972552c41 Mon Sep 17 00:00:00 2001 From: Dave Beazley Date: Thu, 20 Jan 2000 05:48:53 +0000 Subject: [PATCH] *** empty log message *** git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk@129 626c5289-ae23-0410-ae9c-e8d60b6d4f22 --- SWIG/Doc/engineering.html | 162 +++++++++++++++++++++----------------- SWIG/README | 2 + 2 files changed, 93 insertions(+), 71 deletions(-) diff --git a/SWIG/Doc/engineering.html b/SWIG/Doc/engineering.html index 89c9ca45b..ea5846577 100644 --- a/SWIG/Doc/engineering.html +++ b/SWIG/Doc/engineering.html @@ -17,65 +17,69 @@ beazley@cs.uchicago.edu

$Header$ +

+(Note : This is a work in progress.) +

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. +Manual. It is not my intent to overly managerial about matters--rather I'm +hoping to make life a little less chaotic for everyone.

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.

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. +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 dogmatic, 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 +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.

3. The Source Directory and Module Names

@@ -106,10 +110,24 @@ 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: +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:
 

 
 /* -----------------------------------------------------------------------------
- * 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) {
 

 

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

+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:
 
 

 
@@ -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:
 

 

 
-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.
 
 
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:
 
 
    
 
    @@ -364,7 +384,7 @@ typedef struct Foo {
 
    
 
    
 
-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:
 
 
    
 
    @@ -374,10 +394,10 @@ 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).
-
+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.
 
 
 
diff --git a/SWIG/README b/SWIG/README
index 34330f92c..863a2c4cb 100644
--- a/SWIG/README
+++ b/SWIG/README
@@ -14,6 +14,8 @@ SWIG release.  The guilty parties working on this are:
 
   -  Dave Beazley (beazley@cs.uchicago.edu)             (SWIG core)
   -  Dustin Mitchell (djmitche@cs.uchicago.edu)         (SWIG core)
+  -  Ian Cooke (iancooke@cs.uchicago.edu)               (SWIG core)
+  -  Bryan King (bwking@midway.uchicago.edu)            (SWIG core)
   -  Loic Dachary (loic@ceic.com)                       (Perl5)
   -  Harco de Hilster (Harco.de.Hilster@ATComputing.nl) (Java)