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