← Back to branch summary

~ubuntu-branches/ubuntu/oneiric/swig1.3/oneiric

« back to all changes in this revision

Viewing changes to Doc/Manual/Extending.html

  • Committer: Bazaar Package Importer
  • Author(s): Matthias Klose
  • Date: 2007-12-06 10:27:08 UTC
  • mfrom: (1.2.6 upstream)
  • Revision ID: james.westby@ubuntu.com-20071206102708-t37t62i45n595w0e
Tags: 1.3.33-2ubuntu1
* Merge with Debian; remaining changes:
  - Drop support for pike.
  - Use python2.5 instead of python2.4.
  - Clean Runtime/ as well.
  - Force a few environment variables.
* debian/Rules (clean): Remove Lib/ocaml/swigp4.ml.

Show diffs side-by-side

added added

removed removed

Lines of Context:
Doc/Manual/Extending.html
60
60
<li><a href="#Extending_nn42">Examples and test cases</a>
61
61
<li><a href="#Extending_nn43">Documentation</a>
62
62
<li><a href="#Extending_prerequisites">Prerequisites for adding a new language module to the SWIG distribution</a>
 
63
<li><a href="#Extending_coding_style_guidelines">Coding style guidelines</a>
63
64
</ul>
64
65
<li><a href="#Extending_nn44">Typemaps</a>
65
66
<ul>
388
389
The SWIG parser produces a complete parse tree of the input file before any wrapper code
389
390
is actually generated.  Each item in the tree is known as a "Node".   Each node is identified
390
391
by a symbolic tag.   Furthermore, a node may have an arbitrary number of children.
391
 
The parse tree structure and tag names of an interface can be displayed using <tt>swig -dump_tags</tt>.
 
392
The parse tree structure and tag names of an interface can be displayed using <tt>swig -debug-tags</tt>.
392
393
For example:
393
394
</p>
394
395
 
395
396
<div class="shell">
396
397
<pre>
397
 
$ <b>swig -c++ -python -dump_tags example.i</b>
 
398
$ <b>swig -c++ -python -debug-tags example.i</b>
398
399
 . top (example.i:1)
399
400
 . top . include (example.i:1)
400
401
 . top . include . typemap (/r0/beazley/Projects/lib/swig1.3/swig.swg:71)
448
449
The contents of each parse tree node consist of a collection of attribute/value
449
450
pairs.  Internally, the nodes are simply represented by hash tables.  A display of
450
451
the entire parse-tree structure can be obtained using <tt>swig -dump_tree</tt>. 
451
 
There are a number of other parse tree display options, for example, <tt>swig -dump_module</tt> will
452
 
avoid displaying system parse information and only display the parse tree pertaining to the user's module.
 
452
There are a number of other parse tree display options, for example, <tt>swig -debug-module &lt;n&gt;</tt> will
 
453
avoid displaying system parse information and only display the parse tree pertaining to the user's module at
 
454
stage <tt>n</tt> of processing.
453
455
</p>
454
456
 
455
457
<div class="shell">
456
458
<pre>
457
 
$ swig -c++ -python -dump_module example.i
 
459
$ swig -c++ -python -debug-module 4 example.i
458
460
      +++ include ----------------------------------------
459
461
      | name         - "example.i"
460
462
 
678
680
</div>
679
681
 
680
682
<p>
681
 
Now, running SWIG:
 
683
There are various <tt>debug-</tt> options that can be useful for debugging and analysing the parse tree.
 
684
For example, the <tt>debug-top &lt;n&gt;</tt> or <tt>debug-module &lt;n&gt;</tt> options will
 
685
dump the entire/top of the parse tree or the module subtree at one of the four <tt>n</tt> stages of processing.
 
686
The parse tree can be viewed after the final stage of processing by running SWIG:
682
687
</p>
683
688
 
684
689
<div class="shell">
685
690
<pre>
686
 
$ swig -dump_tree example.i
 
691
$ swig -debug-top 4 example.i
687
692
...
688
693
            +++ cdecl ----------------------------------------
689
694
            | sym:name     - "foo_i"
772
777
The behavior of <tt>%feature</tt> is very easy to describe--it simply
773
778
attaches a new attribute to any parse tree node that matches the
774
779
given prototype.   When a feature is added, it shows up as an attribute in the <tt>feature:</tt> namespace.
775
 
You can see this when running with the <tt>-dump_tree</tt> option.   For example:
 
780
You can see this when running with the <tt>-debug-top 4</tt> option.   For example:
776
781
</p>
777
782
 
778
783
<div class="shell">
2868
2873
           action : delete arg1;
2869
2874
 
2870
2875
functionWrapper   : void Shape_x_set(Shape *self,double x)
2871
 
           action : if (arg1) (arg1)->x = arg2;
 
2876
           action : if (arg1) (arg1)-&gt;x = arg2;
2872
2877
 
2873
2878
functionWrapper   : double Shape_x_get(Shape *self)
2874
 
           action : result = (double) ((arg1)->x);
 
2879
           action : result = (double) ((arg1)-&gt;x);
2875
2880
 
2876
2881
functionWrapper   : void Shape_y_set(Shape *self,double y)
2877
 
           action : if (arg1) (arg1)->y = arg2;
 
2882
           action : if (arg1) (arg1)-&gt;y = arg2;
2878
2883
...
2879
2884
</pre>
2880
2885
</div>
2974
2979
  ....
2975
2980
 
2976
2981
  /* write the wrapper function definition */
2977
 
  Printv(wrapper->def,"RETURN_TYPE ", wname, "(ARGS) {",NIL);
 
2982
  Printv(wrapper-&gt;def,"RETURN_TYPE ", wname, "(ARGS) {",NIL);
2978
2983
 
2979
2984
  /* if any additional local variable needed, add them now */
2980
2985
  ...
3004
3009
  ....
3005
3010
 
3006
3011
  /* Close the function(ok) */
3007
 
  Printv(wrapper->code, "return ALL_OK;\n", NIL);
 
3012
  Printv(wrapper-&gt;code, "return ALL_OK;\n", NIL);
3008
3013
 
3009
3014
  /* add the failure cleanup code */
3010
3015
  ...
3011
3016
 
3012
3017
  /* Close the function(error) */
3013
 
  Printv(wrapper->code, "return ERROR;\n", "}\n", NIL);
 
3018
  Printv(wrapper-&gt;code, "return ERROR;\n", "}\n", NIL);
3014
3019
 
3015
3020
  /* final substititions if applicable */
3016
3021
  ...
3280
3285
which we encourage for all popular languages, there are a few requirements.
3281
3286
While we appreciate that getting all aspects of a new language working
3282
3287
won't happen at the outset, there are a set of minimum requirements before
3283
 
a module can be committed into the cvs repository for distribution with future
 
3288
a module can be committed into the SVN repository for distribution with future
3284
3289
versions of SWIG. The following are really a summary of this whole section with
3285
3290
details being outlined earlier on.
3286
3291
</p>
3312
3317
  the language module.
3313
3318
  </li>
3314
3319
  <li>
 
3320
  Ensure your source code is formatted according to the <a href="#Extending_coding_style_guidelines">coding style guidelines</a>.
 
3321
  </li>
 
3322
  <li>
3315
3323
  Finally, email the SWIG developers with a patch and a demonstration of
3316
3324
  commitment to maintaining the language module,
3317
3325
  certainly in the short term and ideally long term.
3319
3327
</ol>
3320
3328
 
3321
3329
<p>
3322
 
Once accepted into CVS, development efforts should concentrate on
 
3330
Once accepted into SVN, development efforts should concentrate on
3323
3331
getting the entire test-suite to work with plenty of runtime tests.
3324
3332
Runtime tests should be for existing testcases and new test cases 
3325
3333
should be added should there be an area not already covered by 
3326
3334
the existing tests.
3327
3335
</p>
3328
3336
 
 
3337
<H3><a name="Extending_coding_style_guidelines"></a>33.10.14 Coding style guidelines</H3>
 
3338
 
 
3339
 
 
3340
<p>
 
3341
The coding guidelines for the C/C++ source code are pretty much K&amp;R C style.
 
3342
The style can be inferred from the existing code base and is
 
3343
largely dictated by the <tt>indent</tt> code beautifier tool set to K&amp;R style.
 
3344
The code can formatted using the make targets in the Source directory.
 
3345
Below is an example of how to format the emit.cxx file:
 
3346
</p>
 
3347
 
 
3348
<blockquote>
 
3349
<pre>
 
3350
$ cd Source
 
3351
$ make beautify-file INDENTFILE=Modules/emit.cxx
 
3352
</pre>
 
3353
</blockquote>
 
3354
 
 
3355
<p>
 
3356
Of particular note is indentation is set to 2 spaces and a tab is used instead of 8 spaces.
 
3357
The generated C/C++ code should also follow this style as close as possible. However, tabs
 
3358
should be avoided as unlike the SWIG developers, users will never have consistent tab settings.
 
3359
</p>
3329
3360
 
3330
3361
<H2><a name="Extending_nn44"></a>33.11 Typemaps</H2>
3331
3362