jyapayne/swig
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

*** empty log message ***

Browse source 
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk/SWIG@129 626c5289-ae23-0410-ae9c-e8d60b6d4f22
This commit is contained in:
Dave Beazley 2000-01-20 05:48:53 +00:00
commit 32b641abd6
2 changed files with 93 additions and 71 deletions
Download patch file Download diff file Expand all files Collapse all files

162
Doc/engineering.html
View file

@ -17,65 +17,69 @@ beazley@cs.uchicago.edu <br>
<p>
<b>$Header$</b>
<p>
(Note : This is a work in progress.)
<h2>1. Introduction</h2>
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.
<p>
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.
<p>
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.
<p>
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.
<h2>2. Programming Languages and Libraries </h2>
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). <B>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. </B>
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). <B>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. </B> 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.
<p>
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.
<h2>3. The Source Directory and Module Names</h2>
@ -106,10 +110,24 @@ should prevent header-file naming conflicts both within SWIG and when linking
parts of SWIG to the outside world.
<p>
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:
<blockquote>
<pre>
/* -----------------------------------------------------------------------------
* 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.
<p>
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:
<blockquote>
<pre>
/* -----------------------------------------------------------------------------
* 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).
<p>
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.
<h2>6. Bottom-Up Design </h2>
@ -242,7 +256,7 @@ and a short description like this:
<blockquote>
<pre>
/* -----------------------------------------------------------------------------
* 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) {
</pre>
</blockquote>
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.
<p>
Function declarations should <b>NOT</b> use the pre-ANSI function
declaration syntax. The ANSI standard has been around long enough for
this to be a non-issue.
<h2>8. Naming Conventions</h2>
The following conventions are generally used to name various objects throughout SWIG.
The following conventions are used to name various objects throughout SWIG.
<h4>Functions</h4>
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:
<blockquote>
<pre>
@ -280,7 +300,7 @@ words separated by underscores.
<h4>Structures and Types</h4>
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:
<blockquote>
@ -314,12 +334,12 @@ Constants should be created using #define and should be in all caps like this:
</pre>
</blockquote>
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.
<h4>Structure members</h4>
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:
<blockquote>
@ -339,12 +359,12 @@ typedef struct SwigScanner {
<h4>Static Functions and Variables </h4>
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.
<h2>9. Visibility</h2>
Module should play by the following rules when exposing their interface:
Modules should keep the following rules in mind when exposing their internals:
<ul>
<li>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.
<li>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:
<blockquote>
<pre>
@ -364,7 +384,7 @@ typedef struct Foo {
</pre>
</blockquote>
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:
<blockquote>
<pre>
@ -374,10 +394,10 @@ extern void Foo_setline(Foo *f, int line);
</pre>
</blockquote>
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.
</body>
</html>

2
README
View file

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