jyapayne/swig
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Fix typos, html errors and add new section on prerequisites for adding new language modules to swig distribution

Browse source 
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk/SWIG@8817 626c5289-ae23-0410-ae9c-e8d60b6d4f22
This commit is contained in:
William S Fulton 2006-02-14 19:59:43 +00:00
commit 1549a0fb61
1 changed files with 114 additions and 61 deletions
Download patch file Download diff file Expand all files Collapse all files

175
Doc/Manual/Extending.html
View file

@ -1,12 +1,12 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html> <html>
<head> <head>
<title>Extending SWIG</title> <title>Extending SWIG to support new languages</title>
<link rel="stylesheet" type="text/css" href="style.css"> <link rel="stylesheet" type="text/css" href="style.css">
</head> </head>
<body bgcolor="#ffffff"> <body bgcolor="#ffffff">
<H1><a name="Extending"></a>32 Extending SWIG</H1> <H1><a name="Extending"></a>32 Extending SWIG to support new languages</H1>
<!-- INDEX --> <!-- INDEX -->
<div class="sectiontoc"> <div class="sectiontoc">
<ul> <ul>
@ -59,6 +59,7 @@
<li><a href="#Extending_nn41">Standard library files</a> <li><a href="#Extending_nn41">Standard library files</a>
<li><a href="#Extending_nn42">Examples and test cases</a> <li><a href="#Extending_nn42">Examples and test cases</a>
<li><a href="#Extending_nn43">Documentation</a> <li><a href="#Extending_nn43">Documentation</a>
<li><a href="#Extending_prerequisites">Prerequisites for adding a new language module to the SWIG distribution</a>
</ul> </ul>
<li><a href="#Extending_nn44">Typemaps</a> <li><a href="#Extending_nn44">Typemaps</a>
<ul> <ul>
@ -71,18 +72,14 @@
<p>
<b>Caution: This chapter is being rewritten! (11/25/01)</b>
</p>
<H2><a name="Extending_nn2"></a>32.1 Introduction</H2> <H2><a name="Extending_nn2"></a>32.1 Introduction</H2>
<p> <p>
This chapter describes SWIG's internal organization and the process by which This chapter describes SWIG's internal organization and the process by which
new target languages can be developed. First, a brief word of warning---SWIG new target languages can be developed. First, a brief word of warning---SWIG
has been undergoing a massive redevelopment effort that has focused extensively is continually evolving.
on its internal organization. The information in this chapter is mostly up to The information in this chapter is mostly up to
date, but changes are ongoing. Expect a few inconsistencies. date, but changes are ongoing. Expect a few inconsistencies.
</p> </p>
@ -110,8 +107,8 @@ Since SWIG is essentially a specialized C++ compiler, it may be useful
to have some prior experience with compiler design (perhaps even a to have some prior experience with compiler design (perhaps even a
compilers course) to better understand certain parts of the system. A compilers course) to better understand certain parts of the system. A
number of books will also be useful. For example, "The C Programming number of books will also be useful. For example, "The C Programming
Language" by Kernighan and Ritchie (a.k.a, "K&amp;R") and the "C++ Language" by Kernighan and Ritchie (a.k.a, "K&amp;R") and the C++ standard,
Annotated Reference Manual" by Stroustrup (a.k.a, the "ARM") will be of great use. "ISO/IEC 14882 Programming Languages - C++" will be of great use.
</p> </p>
<p> <p>
@ -195,7 +192,7 @@ would determine whether or not a class allows a default constructor.
<li>A code generation pass is made using a specific target language <li>A code generation pass is made using a specific target language
module. This phase is responsible for generating the actual wrapper module. This phase is responsible for generating the actual wrapper
code. All of SWIG's user-defined modules are invoked during this code. All of SWIG's user-defined modules are invoked during this
stage of compilation. latter stage of compilation.
</li> </li>
</ul> </ul>
@ -450,13 +447,14 @@ of the output.
<p> <p>
The contents of each parse tree node consist of a collection of attribute/value The contents of each parse tree node consist of a collection of attribute/value
pairs. Internally, the nodes are simply represented by hash tables. A display of pairs. Internally, the nodes are simply represented by hash tables. A display of
the parse-tree structure can be obtained using <tt>swig -dump_tree</tt>. For example: the entire parse-tree structure can be obtained using <tt>swig -dump_tree</tt>.
There are a number of other parse tree display options, for example, <tt>swig -dump_module</tt> will
avoid displaying system parse information and only display the parse tree pertaining to the user's module.
</p> </p>
<div class="shell"> <div class="shell">
<pre> <pre>
$ swig -c++ -python -dump_tree example.i $ swig -c++ -python -dump_module example.i
...
+++ include ---------------------------------------- +++ include ----------------------------------------
| name - "example.i" | name - "example.i"
@ -793,8 +791,8 @@ You can see this when running with the <tt>-dump_tree</tt> option. For example
<p> <p>
Feature names are completely arbitrary and a target language module can be Feature names are completely arbitrary and a target language module can be
programmed to respond to any feature name that it wants to recognized. The programmed to respond to any feature name that it wants to recognize. The
data stored in a feature attribute is usually just a raw unparsed string. data stored in a feature attribute is usually just a raw unparsed string.
For example, the exception code above is simply For example, the exception code above is simply
stored without any modifications. stored without any modifications.
</p> </p>
@ -930,7 +928,7 @@ interest in using XML to represent SWIG parse trees. Although XML is
not currently used in any direct manner, the parse tree structure, use not currently used in any direct manner, the parse tree structure, use
of node tags, attributes, and attribute namespaces are all influenced of node tags, attributes, and attribute namespaces are all influenced
by aspects of XML parsing. Therefore, in trying to understand SWIG's by aspects of XML parsing. Therefore, in trying to understand SWIG's
internal data structures, it may be useful keep XML in the back of internal data structures, it may be useful to keep XML in the back of
your mind as a model. your mind as a model.
</p> </p>
@ -2444,9 +2442,13 @@ Returns the number of required (non-optional) arguments in <tt>p</tt>.
<p> <p>
This section briefly outlines the steps needed to create a bare-bones One of the easiest routes to supporting a new language module is to copy an already
language module. For more advanced techniques, you should look at the implementation supported language module implementation and modify it.
of existing modules. Since the code is relatively easy to read, this section Be sure to choose a language that is similar in nature to the new language.
All language modules follow a similar structure and
this section briefly outlines the steps needed to create a bare-bones
language module from scratch.
Since the code is relatively easy to read, this section
describes the creation of a minimal Python module. You should be able to extrapolate describes the creation of a minimal Python module. You should be able to extrapolate
this to other languages. this to other languages.
</p> </p>
@ -2456,7 +2458,7 @@ this to other languages.
<p> <p>
Code generation modules are defined by inheriting from the <tt>Language</tt> class, Code generation modules are defined by inheriting from the <tt>Language</tt> class,
currently defined in the <tt>Source/Modules1.1</tt> directory of SWIG. Starting from currently defined in the <tt>Source/Modules</tt> directory of SWIG. Starting from
the parsing of command line options, all aspects of code generation are controlled by the parsing of command line options, all aspects of code generation are controlled by
different methods of the <tt>Language</tt> that must be defined by your module. different methods of the <tt>Language</tt> that must be defined by your module.
</p> </p>
@ -2473,10 +2475,6 @@ this example as a guide:
<pre> <pre>
#include "swigmod.h" #include "swigmod.h"
#ifndef MACSWIG
#include "swigconfig.h"
#endif
class PYTHON : public Language { class PYTHON : public Language {
public: public:
@ -2529,11 +2527,10 @@ also return a pointer to the base class (<tt>Language</tt>) so that only the int
<p> <p>
Save the code for your language module in a file named "<tt>python.cxx</tt>" and. Save the code for your language module in a file named "<tt>python.cxx</tt>" and.
place this file in the <tt>Source/Modules1.1</tt> directory of the SWIG distribution. place this file in the <tt>Source/Modules</tt> directory of the SWIG distribution.
To ensure that your module is compiled into SWIG along with the other language modules, To ensure that your module is compiled into SWIG along with the other language modules,
modify the file <tt>Source/Modules1.1/Makefile.in</tt> to include the additional source modify the file <tt>Source/Modules/Makefile.am</tt> to include the additional source
files. Look for the lines that define the <tt>SRCS</tt> and <tt>OBJS</tt> variables and files. In addition, modify the file <tt>Source/Modules/swigmain.cxx</tt>
add entries for your language. In addition, modify the file <tt>Source/Modules1.1/swigmain.cxx</tt>
with an additional command line option that activates the module. Read the source---it's straightforward. with an additional command line option that activates the module. Read the source---it's straightforward.
</p> </p>
@ -2544,7 +2541,7 @@ to regenerate the various build files:
<div class="shell"> <div class="shell">
<pre> <pre>
$ <b>sh autogen.sh</b> $ <b>./autogen.sh</b>
</pre> </pre>
</div> </div>
@ -2742,11 +2739,13 @@ int Python::top(Node *n) {
<H3><a name="Extending_nn37"></a>32.10.6 Module I/O and wrapper skeleton</H3> <H3><a name="Extending_nn37"></a>32.10.6 Module I/O and wrapper skeleton</H3>
<!-- please report bugs in this section to mgossage --> <!-- please report bugs in this section to mgossage -->
<p> <p>
Within SWIG wrappers, there are four main sections. These are (in order) Within SWIG wrappers, there are four main sections. These are (in order)
</p>
<ul> <ul>
<li>runtime: This section has most of the common SWIG runtime code <li>runtime: This section has most of the common SWIG runtime code
@ -2755,7 +2754,6 @@ Within SWIG wrappers, there are four main sections. These are (in order)
<li>init: This section holds the module initalisation function <li>init: This section holds the module initalisation function
(the entry point for the interpreter) (the entry point for the interpreter)
</ul> </ul>
</p>
<p> <p>
Different parts of the SWIG code will fill different sections, Different parts of the SWIG code will fill different sections,
then upon completion of the wrappering all the sections will be saved then upon completion of the wrappering all the sections will be saved
@ -2829,12 +2827,12 @@ int Python::top(Node *n) {
Using this to process a file will generate a wrapper file, however the Using this to process a file will generate a wrapper file, however the
wrapper will only consist of the common SWIG code as well as any inline wrapper will only consist of the common SWIG code as well as any inline
code which was written in the .i file. It does not contain any wrappers for code which was written in the .i file. It does not contain any wrappers for
any of the functions of classes. any of the functions or classes.
</p> </p>
<p> <p>
The code to generate the wrappers are the various member functions, which The code to generate the wrappers are the various member functions, which
currently have not been touched. We will look at functionWrapper() as this currently have not been touched. We will look at <tt>functionWrapper()</tt> as this
is the most commonly used function. In fact many of the other wrapper routines is the most commonly used function. In fact many of the other wrapper routines
will call this to do their work. will call this to do their work.
</p> </p>
@ -2883,6 +2881,7 @@ functionWrapper : void Shape_y_set(Shape *self,double y)
<H3><a name="Extending_nn38"></a>32.10.7 Low-level code generators</H3> <H3><a name="Extending_nn38"></a>32.10.7 Low-level code generators</H3>
<!-- please report bugs in this section to mgossage --> <!-- please report bugs in this section to mgossage -->
<p> <p>
@ -2894,10 +2893,10 @@ understanding of how to manually write an interface to your chosen
language, so make sure you have your documentation handy. language, so make sure you have your documentation handy.
</p> </p>
<p> <p>
At this point is also probably a good idea to take a very simple file At this point it is also probably a good idea to take a very simple file
(just one function), and try letting SWIG generate up wrappers for many (just one function), and try letting SWIG generate wrappers for many
different languages. Take a look at all of the wrappers generated, and decide different languages. Take a look at all of the wrappers generated, and decide
which one looks closest to the language you are trying to wrapper. which one looks closest to the language you are trying to wrap.
This may help you to decide which code to look at. This may help you to decide which code to look at.
</p> </p>
<p> <p>
@ -2936,18 +2935,18 @@ Yes, it is rather vague and not very clear. But each language works differently
so this will have to do for now. so this will have to do for now.
</p> </p>
<p> <p>
To tackle this problem will be done in two stages: Tackling this problem will be done in two stages:
</p>
<ul> <ul>
<li>The skeleton: the function wrapper, and call, but without the conversion <li>The skeleton: the function wrapper, and call, but without the conversion
<li>The conversion: converting the arguments to-from what the language wants <li>The conversion: converting the arguments to-from what the language wants
</ul> </ul>
</p>
<p> <p>
The first step will be done in the code, the second will be done in typemaps. The first step will be done in the code, the second will be done in typemaps.
</p> </p>
<p> <p>
Our first step will be to write the code for functionWrapper(). What is Our first step will be to write the code for <tt>functionWrapper()</tt>. What is
shown below is _NOT_ the solution, merely a step in the right direction. shown below is <b>NOT</b> the solution, merely a step in the right direction.
There are a lot of issues to address. There are a lot of issues to address.
</p> </p>
<ul> <ul>
@ -3030,7 +3029,7 @@ virtual int functionWrapper(Node *n) {
<p> <p>
Executing this code will produce wrappers which have our basic skeleton Executing this code will produce wrappers which have our basic skeleton
but without the typemaps, there are still work to do. but without the typemaps, there is still work to do.
</p> </p>
@ -3172,22 +3171,17 @@ subdirectory of <TT>Lib</TT>. Use (optional) file
<TT>extra-install.list</TT> in that directory to name <TT>extra-install.list</TT> in that directory to name
additional files to install (see ruby for example). additional files to install (see ruby for example).
<dt> <b>Runtime/Makefile.in</b> <dt> <b>Source/Modules/Makefile.am</b>
<dd> Add another <TT>make</TT> invocation to <TT>all</TT>, and <dd> Add appropriate files to this Automake file. That's it!
a section for your language module.
<dt> <b>Source/Modules1.1/Makefile.in</b> <p>
<dd> Add appropriate entries for vars <TT>OBJS</TT> and <TT>SRCS</TT>. When you have modified these files, please make sure that the new language module is completely
That's it! ignored if it is not installed and detected on a box, that is, <tt>make check-examples</tt> and <tt>make check-test-suite</tt>
politely displays the ignoring language message.
</p>
</dl> </dl>
<p>
At some point it would be a good idea to use
<A HREF="http://www.gnu.org/software/automake/">automake</A>
to handle some of these configuration tasks, but that point is now
long past. If you are interested in working on that, feel free to
raise the issue in the context of a next-generation clean-slate SWIG.
<H3><a name="Extending_nn40"></a>32.10.9 Runtime support</H3> <H3><a name="Extending_nn40"></a>32.10.9 Runtime support</H3>
@ -3202,7 +3196,8 @@ the SWIG files that implement those functions.
<p> <p>
Discuss the standard library files that most language modules provide, e.g. The standard library files that most languages supply keeps growing as SWIG matures.
The following are the minimum that are usually supported:
</p> </p>
<ul> <ul>
@ -3212,6 +3207,10 @@ Discuss the standard library files that most language modules provide, e.g.
<li> stl.i </li> <li> stl.i </li>
</ul> </ul>
<p>
Please copy these and modify for any new language.
</p>
<H3><a name="Extending_nn42"></a>32.10.11 Examples and test cases</H3> <H3><a name="Extending_nn42"></a>32.10.11 Examples and test cases</H3>
@ -3228,8 +3227,10 @@ Each example is self-contained and consists of (at least) a <tt>Makefile</tt>,
a SWIG interface file for the example module, and a script that demonstrates a SWIG interface file for the example module, and a script that demonstrates
the functionality for that module. All of these files are stored in the same the functionality for that module. All of these files are stored in the same
subdirectory, and that directory should be nested under <tt>Examples/python</tt>. subdirectory, and that directory should be nested under <tt>Examples/python</tt>.
For example, the files for the Python "simple" example are found in There are two classic examples which should be the first to convert to a new
<tt>Examples/python/simple</tt>. language module. These are the "simple" C example and the "class" C++ example.
These can be found, for example for Python, in
<tt>Examples/python/simple</tt> and <tt>Examples/python/class</tt>.
</p> </p>
<p> <p>
@ -3244,8 +3245,8 @@ files</a>.
<p> <p>
Don't forget to write end-user documentation for your language module. Currently, Don't forget to write end-user documentation for your language module. Currently,
each language module has a dedicated chapter (although this structure may change each language module has a dedicated chapter
in the future). You shouldn't rehash things that are already covered in sufficient You shouldn't rehash things that are already covered in sufficient
detail in the <a href="SWIG.html#SWIG">SWIG Basics</a> and <a href="SWIGPlus.html#SWIGPlus">SWIG detail in the <a href="SWIG.html#SWIG">SWIG Basics</a> and <a href="SWIGPlus.html#SWIGPlus">SWIG
and C++</a> chapters. There is no fixed format for <em>what</em>, exactly, you should and C++</a> chapters. There is no fixed format for <em>what</em>, exactly, you should
document about your language module, but you'll obviously want to cover issues that document about your language module, but you'll obviously want to cover issues that
@ -3258,11 +3259,11 @@ Some topics that you'll want to be sure to address include:
<ul> <ul>
<li> Command line options unique to your language module. <li> Command line options unique to your language module.
<li> Non-obvious mappings between C/C++ and scripting language concepts. <li> Non-obvious mappings between C/C++ and target language concepts.
For example, if your scripting language provides a single floating For example, if your target language provides a single floating
point type, it should be no big surprise to find that C/C++ point type, it should be no big surprise to find that C/C++
<tt>float</tt> and <tt>double</tt> types are mapped to it. On the other <tt>float</tt> and <tt>double</tt> types are mapped to it. On the other
hand, if your scripting language doesn't provide support for "classes" hand, if your target language doesn't provide support for "classes"
or something similar, you'd want to discuss how C++ classes are handled. or something similar, you'd want to discuss how C++ classes are handled.
<li> How to compile the SWIG-generated wrapper code into shared libraries <li> How to compile the SWIG-generated wrapper code into shared libraries
that can actually be used. For some languages, there are well-defined that can actually be used. For some languages, there are well-defined
@ -3271,6 +3272,58 @@ Some topics that you'll want to be sure to address include:
if available. if available.
</ul> </ul>
<H3><a name="Extending_prerequisites"></a>32.10.13 Prerequisites for adding a new language module to the SWIG distribution</H3>
<p>
If you wish for a new language module to be distributed with SWIG,
which we encourage for all popular languages, there are a few requirements.
While we appreciate that getting all aspects of a new language working
won't happen at the outset, there are a set of minimum requirements before
a module can be committed into the cvs repository for distribution with future
versions of SWIG. The following are really a summary of this whole section with
details being outlined earlier on.
</p>
<ol>
<li>
Demonstrate basic C code working by porting the "simple" example, see
for example <tt>Examples/python/simple</tt>.
</li>
<li>
Demonstrate basic C++ code working by porting the "class" example,
see for example <tt>Examples/python/simple</tt>.
</li>
<li>
Modify <tt>configure.in</tt>, <tt>Makefile.in</tt> and <tt>Examples/Makefile.in</tt> to run
these examples. Please make sure that if the new language is not
installed properly on a box, <tt>make -k check</tt> should still work by
skipping the tests and examples for the new language module.
</li>
<li>
Get the test-suite running for the new language (<tt>make check-[lang]-test-suite</tt>).
While the test-suite tests many corner cases,
we'd expect the majority of it to work by compiling the generated code
correctly as most of the corner cases are covered in the SWIG core. Get
at least one C and one C++ runtime test running in the test-suite.
</li>
<li>
Provide a chapter in the html documentation on the basics of using
the language module.
</li>
<li>
Finally, email the SWIG developers with a patch and a demonstration of
commitment to maintaining the language module,
certainly in the short term and ideally long term.
</li>
</ol>
<p>
Once accepted into CVS, development efforts should concentrate on
getting the entire test-suite to work with plenty of runtime tests.
</p>
<H2><a name="Extending_nn44"></a>32.11 Typemaps</H2> <H2><a name="Extending_nn44"></a>32.11 Typemaps</H2>