PageRenderTime 36ms CodeModel.GetById 24ms app.highlight 7ms RepoModel.GetById 1ms app.codeStats 0ms

/tags/rel-1-3-26/SWIG/Doc/Devel/engineering.html

#
HTML | 479 lines | 387 code | 92 blank | 0 comment | 0 complexity | 0a573f9532bc8dc3bf85f30bd8d063d9 MD5 | raw file
Possible License(s): LGPL-2.1, Cube, GPL-3.0, 0BSD, GPL-2.0
  1<html>
  2<head>
  3<title>SWIG Engineering Manual</title>
  4</head>
  5<body bgcolor="#ffffff">
  6<center>
  7<h1>SWIG Engineering Manual</h1>
  8
  9<b>David Beazley <br>
 10Department of Computer Science <br>
 11University of Chicago <br>
 12Chicago, IL  60637 <br>
 13beazley@cs.uchicago.edu <br>
 14</b>
 15</center>
 16
 17<p>
 18<b>$Header$</b>
 19
 20<p>
 21(Note : This is a work in progress.) 
 22
 23<h2>Table of Contents</h2>
 24<ul>
 25<li><a name="i1" href="#1">1. Introduction</a>
 26<li><a name="i2" href="#2">2. Programming Languages and Libraries</a>
 27<li><a name="i3" href="#3">3. The Source Directory and Module Names</a>
 28<li><a name="i4" href="#4">4. Include Files</a>
 29<li><a name="i5" href="#5">5. File Structure</a>
 30<li><a name="i6" href="#6">6. Bottom-Up Design</a>
 31<li><a name="i7" href="#7">7. Functions</a>
 32<li><a name="i8" href="#8">8. Naming Conventions</a>
 33<li><a name="i9" href="#9">9. Visibility</a>
 34<li><a name="i10" href="#10">10. Miscellaneous Coding Guidelines</a>
 35<li><a name="i11" href="#11">11. CVS Tagging Conventions</a>
 36</ul>
 37
 38<a name="1" href="#i1">
 39<h2>1. Introduction</h2>
 40</a>
 41
 42The purpose of this document is to describe various coding conventions
 43and organizational aspects for SWIG developers. The idea for this
 44document is largely borrowed from John Ousterhout's Tcl/Tk Engineering
 45Manual.  It is not my intent to overly managerial about matters--rather I'm
 46hoping to make life a little less chaotic for everyone.
 47
 48<p>
 49First a little background: SWIG was started in 1995 as a one-person
 50project and continued in this mode of operation until about 1998.
 51Most of this development was driven by ideas submitted by early SWIG
 52users as opposed to being motivated by a grand design.  As a result,
 53the code ended up being a pretty horrible C++ coding disaster.  A
 54mostly working disaster perhaps, but a disaster nonetheless.
 55
 56<p>
 57With that said, the primary goal of future SWIG development is to
 58reengineer the original system, fix most of its inherent design flaws,
 59and to produce what I hope will become a highly extensible and modular
 60interface compiler framework.  To this do this, there are a few
 61critical areas of work.  First, I want to restructure SWIG as a
 62collection of loosely coupled modules written in either ANSI C or an
 63scripting language.  Second, I want the system to be minimalistic in
 64its use of data structures and interconnections.  The primary reason
 65for this is that the fewer data structures there are, the less users
 66will have to remember.  This will also make the system more accessible
 67to non-experts.  Finally, I want to reevaluate the whole idea of a
 68SWIG module is and expand the definition to include just about
 69anything from parsers, preprocessors, optimizers, interface editors,
 70and code generators.
 71
 72<p>
 73The rest of this document outlines a few general rules of how code
 74should be developed within the SWIG project.  These rules are
 75primarily drawn from my own experience developing software and
 76observing the practices of other successful projects.
 77
 78<a name="2" href="#i2">
 79<h2>2. Programming Languages and Libraries </h2>
 80</a>
 81
 82All SWIG modules must be written in either ANSI C or one of the
 83scripting languages for which SWIG can generate an interface (e.g.,
 84Perl, Python, or Tcl).  C++ is currently being used to write
 85SWIG modules, but it is only being utilized to avoid working with 
 86a lot of pointers to functions.  <b>Advanced C++ features like namespaces, templates,
 87and overloading should not be used.</b>.
 88
 89<p>
 90Module writers should make every attempt to use only those functions
 91described in the POSIX.1 standard.  This includes most of the
 92functions contained the Kernighan and Ritchie C programming book.  Use
 93of operating system dependent functionality such as socket libraries
 94should always be included inside a conditional compilation block so
 95that it can be omitted on problematic platforms.  If you are unsure
 96about a library call, check the man page or contact Dave.
 97
 98<a name="3" href="#i3">
 99<h2>3. The Source Directory and Module Names</h2>
100</a>
101
102All SWIG modules are contained within the "Source" directory.  Within
103this directory, each module is placed into its own subdirectory.  The
104name of this subdirectory should exactly match the name of the module.
105For example, if you are creating a module called "Tcl", all of your
106files should be placed in a directory "Tcl".
107
108<p>
109When choosing a module name, please pick a name that is not
110currently in use.  As a general convention, the first letter of a
111module name is capitalized such as "Perl".  Alternatives such as
112"perl" or "PERL" should be avoided.  In certain instances, the first
113two letters may be capitalized as in "CParse."  The exact usage of
114this is somewhat inconsistent and isn't terribly important--just make
115sure the first letter is capitalized.  Also, module names should not
116start with numbers, include underscores or any other special
117non-alphanumeric characters.
118
119<a name="4" href="#i4">
120<h2>4. Include Files </h2>
121</a>
122
123All modules should include a header file that defines the public interface. 
124The name of this header file should be of the form "swigmodule.h" where
125"module" is the name of your module.  For example, if you created a 
126module "Perl", the header file should be named "swigperl.h".   This scheme
127should prevent header-file naming conflicts both within SWIG and when linking
128parts of SWIG to the outside world.
129
130<p>
131All header files should include a short description, author information, copyright message,
132CVS version, include guards, and be C++ aware. For example:
133
134<blockquote>
135<pre>
136/* -------------------------------------------------------------------------
137 * swigperl.h
138 *
139 *     All of the externally visible functions in the Perl module.
140 * 
141 * Author(s) : David Beazley (beazley@cs.uchicago.edu)
142 *
143 * Copyright (C) 1999-2000, The University of Chicago.
144 * See the file LICENSE for information on usage and redistribution. 
145 *
146 * $Header$
147 * ------------------------------------------------------------------------- */
148
149#ifndef _SWIGPERL_H
150#define _SWIGPERL_H   1
151
152#ifdef __cplusplus
153extern "C" {
154#endif
155
156/* Your declarations here */
157...
158
159#ifdef __cplusplus
160}
161#endif
162
163#endif  /* _SWIGPERL_H */
164</pre>
165</blockquote>
166
167
168<p>
169To minimize compilation time, please include as few other header files as possible.
170
171<a name="5" href="#i5">
172<h2>5. File Structure </h2>
173</a>
174
175Each file in a module should be given a filename that is all lowercase letters
176such as "parser.c", not "Parser.c" or "PARSER.c".   Please note that filenames
177are case-insensitive on Windows so this convention will prevent you from inadvertantly
178creating two files that differ in case-only.
179
180<p>
181Each file should include a short abstract, author information, copyright information, and
182a CVS revision tag like this:
183
184<blockquote>
185<pre>
186/* -----------------------------------------------------------------------------
187 * include.c
188 *
189 *     This file implements the functions used to locate and include files in
190 *     the SWIG library.  Functions for maintaining the library search path are
191 *     also located here.
192 * 
193 * Author(s) : David Beazley (beazley@cs.uchicago.edu)
194 *
195 * Copyright (C) 1999-2000, The University of Chicago.
196 * See the file LICENSE for information on usage and redistribution. 
197 * ----------------------------------------------------------------------------- */
198
199static char cvsroot[] = "$Header$";
200
201#include "swig.h"
202
203/* Declarations */
204typedef struct {
205   int x, y;
206} Foo;
207
208...
209
210/* Private Declarations (used only in this file) */
211static int  avariable;
212
213...
214
215/* Functions */
216... 
217
218</pre>
219</blockquote>
220
221The CVS revision tag should be placed into a static string as shown
222above.  This adds the revision information to the SWIG executable and
223makes it possible to extract version information from a raw binary
224(sometimes useful in debugging).  
225
226<p>
227As a general rule, files start to get unmanagable once they exceed
228about 2000 lines.  Files larger than this should be broken up into
229multiple files.  Similarly, you should avoid the temptation to create
230many small files as this increases compilation time and makes the
231directory structure too complicated.
232
233<a name="6" href="#i6">
234<h2>6. Bottom-Up Design </h2>
235</a>
236
237Within each source file, the preferred organization is to use what is
238known as "bottom-up" design.  Under this scheme, lower-level functions
239appear first and the highest level function appears last.  The easy
240way to remember is that the "main" function of your module should
241always appear last in the source file.  For example:
242
243<blockquote>
244<pre>
245/* Simple bottom-up program */
246#include &lt;stdio.h&gt;
247
248int foo(int x, int y) {
249    /* Implement foo */
250    ...
251}
252
253int bar() {
254    ...
255    foo(i,j);
256    ...
257}
258
259...
260int main(int argc, char **argv) {
261    ...
262    bar();   
263    ...
264}
265</pre>
266</blockquote>
267
268This choice of design is somewhat arbitrary however it has a number of
269benefits particular to C. In particular, a bottom-up design generally
270eliminates the need to include forward references--resulting in
271cleaner code and fewer compilation errors.
272
273<a name="7" href="#i7">
274<h2>7. Functions</h2>
275</a>
276
277All functions should have a function header that gives the function name
278and a short description like this:
279
280<blockquote>
281<pre>
282/* -------------------------------------------------------------------------
283 * Swig_add_directory()
284 *
285 * Adds a directory to the SWIG search path.
286 * ------------------------------------------------------------------------- */
287
288void 
289Swig_add_directory(DOH *dirname) {
290...
291
292}
293</pre>
294</blockquote>
295
296In the function declaration, the return type and any specifiers
297(extern or static) should appear on a separate line followed by the
298function name and arguments as shown above.  The left curly brace
299should appear on the same line as the function name.
300
301<p>
302Function declarations should <b>NOT</b> use the pre-ANSI function
303declaration syntax.   The ANSI standard has been around long enough for 
304this to be a non-issue.
305
306<a name="8" href="#i8">
307<h2>8. Naming Conventions</h2>
308</a>
309
310The following conventions are used to name various objects throughout SWIG.
311
312<h4>Functions</h4>
313
314Functions should consist of the module name and the function name separated by an underscore like this:
315
316<blockquote>
317<pre>
318Preprocessor_define()
319Swig_add_directory()
320</pre>
321</blockquote>
322
323In general, the module name should match the name of the module
324subdirectory and the function name should be in all lowercase with
325words separated by underscores.
326
327<h4>Structures and Types</h4>
328
329If your module defines new structures, the structure name should include the name of the
330module and the name of the structure appended together like this:
331
332<blockquote>
333<pre>
334typedef struct SwigScanner {
335   ...
336} SwigScanner;
337
338typedef struct LParseType {
339   ...
340} LParseType;
341</pre>
342</blockquote>
343
344In this case, both the name of the module and the type should be capitalized.  Also, whenever
345possible, you should use the "typedef struct Name { ... } Name" form when defining new
346data structures. 
347
348<h4>Global Variables</h4>
349
350Global variables should be avoided if at all possible.  However, if you must use a global
351variable, please prepend the module name and use the same naming scheme as for functions.
352
353<h4>Constants</h4>
354
355Constants should be created using #define and should be in all caps like this:
356
357<blockquote>
358<pre>
359#define   SWIG_TOKEN_LPAREN  1
360</pre>
361</blockquote>
362
363Separate words in a constant should be separated by underscores as with functions.
364
365<h4>Structure members</h4>
366
367Structure members should be in all lower-case and follow the same word-separation convention
368as for function names.  However, the module name does not have to be included.
369For example:
370
371<blockquote>
372<pre>
373typedef struct SwigScanner {
374  DOH           *text;           /* Current token value */
375  DOH           *scanobjs;       /* Objects being scanned */
376  DOH           *str;            /* Current object being scanned */
377  char          *idstart;        /* Optional identifier start characters */
378  int            next_token;     /* Next token to be returned */
379  int            start_line;     /* Starting line of certain declarations */
380  int            yylen;          /* Length of text pushed into text */
381  DOH           *file;           /* Current file name */
382} SwigScanner;
383</pre>
384</blockquote>
385
386<h4>Static Functions and Variables </h4>
387
388Static declarations are free to use any naming convention that is appropriate. However, most
389existing parts of SWIG use lower-case names and follow the same convention as described for functions.
390
391<a name="9" href="#i9">
392<h2>9. Visibility</h2>
393</a>
394
395Modules should keep the following rules in mind when exposing their internals:
396
397<ul>
398<li>Only publicly accessible functions should be included in the module header file.
399<li>All non-static declarations must be prepended with some form of the module name
400to avoid potential linker namespace conflicts with other modules.
401<li>Modules should not expose global variables or use global variables in their
402public interface.
403<li>Similarly, modules should discourage the direct manipulation of data contained
404within data structures in favor of using function calls instead.  For example,
405instead of providing a user with a structure like this:
406
407<blockquote>
408<pre>
409typedef struct Foo {
410   int line;
411} Foo;
412</pre>
413</blockquote>
414
415It is better to hide the implementation of Foo and provide an
416function-call interface like this:
417
418<blockquote>
419<pre>
420typedef struct Foo Foo;
421extern int  Foo_getline(Foo *f);
422extern void Foo_setline(Foo *f, int line);
423</pre>
424</blockquote>
425
426Although this results in worse performance, there are many practical
427reasons for doing this.  The most important reason is that it allows
428you to change the internal representation of Foo without breaking all
429of the other modules or having to recompile the entire universe after
430making your changes.
431
432</ul>
433
434<a name="10" href="#i10">
435<h2>10. Miscellaneous Coding Guidelines</h2>
436</a>
437
438<ul>
439<li> Do not use the ternary ?: operator.  It is unnecessarily error prone,
440hard for people to read, and hard to maintain code that uses it.
441[I don't agree w/ this guideline.  ?: operator can be abused
442just like everything else, but it can also be used cleanly.  In some styles of
443programming, it is the best tool for the job.  --ttn]
444</ul>
445
446<a name="11" href="#i11">
447<h2>11. CVS Tagging Conventions</h2>
448</a>
449
450Use <tt>cvs tag</tt> to declare some set of file revisions as related in some
451symbolic way.  This eases reference, retrieval and manipulation of these files
452later.  At the moment (2001/01/16 14:02:53), the conventions are very simple;
453let's hope they stay that way!
454
455<p>
456There are two types of tags, internal (aka personal) and external.
457Internal tags are used by SWIG developers primarily, whereas external
458tags are used when communicating with people w/ anonymous cvs access.
459<ul>
460<li> Internal tags should start with the developer name and a hyphen.
461<li> External tags should start with "v-".
462</ul>
463
464That's all there is to it.  Some example tags:
465
466<ul>
467<li> ttn-pre-xml-patch
468<li> ttn-post-xml-patch
469<li> ttn-going-on-vacation-so-dutifully-tagging-now
470<li> v-1-3-a37-fixes-bug-2432
471<li> v-1-3-a37-fixes-bug-2433
472<li> v-1-3-a37-fixes-bug-2432-again
473<li> v-1-3-a37-release
474</ul>
475
476<hr>
477Copyright (C) 1999-2004 SWIG Development Team.
478</body>
479</html>