From e8ab41b8b92375371b1d1f6315b57218477425ec Mon Sep 17 00:00:00 2001 From: Dave Beazley Date: Wed, 19 Jan 2000 06:40:19 +0000 Subject: [PATCH] *** empty log message *** git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk@116 626c5289-ae23-0410-ae9c-e8d60b6d4f22 --- SWIG/Doc/engineering.html | 387 +++++++++++++++++++++++++++++++++++++ SWIG/Source/Swig/scanner.c | 11 ++ SWIG/Source/Swig/swig.h | 1 + 3 files changed, 399 insertions(+) create mode 100644 SWIG/Doc/engineering.html diff --git a/SWIG/Doc/engineering.html b/SWIG/Doc/engineering.html new file mode 100644 index 000000000..89c9ca45b --- /dev/null +++ b/SWIG/Doc/engineering.html @@ -0,0 +1,387 @@ + + +SWIG Engineering Manual + + +
+

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