/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 <stdio.h> 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>