-Caution: This chapter is being rewritten! (11/25/01) -
-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 -has been undergoing a massive redevelopment effort that has focused extensively -on its internal organization. The information in this chapter is mostly up to +is continually evolving. +The information in this chapter is mostly up to date, but changes are ongoing. Expect a few inconsistencies.
@@ -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 compilers course) to better understand certain parts of the system. A number of books will also be useful. For example, "The C Programming -Language" by Kernighan and Ritchie (a.k.a, "K&R") and the "C++ -Annotated Reference Manual" by Stroustrup (a.k.a, the "ARM") will be of great use. +Language" by Kernighan and Ritchie (a.k.a, "K&R") and the C++ standard, +"ISO/IEC 14882 Programming Languages - C++" will be of great use.@@ -195,7 +192,7 @@ would determine whether or not a class allows a default constructor.
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 -the parse-tree structure can be obtained using swig -dump_tree. For example: +the entire parse-tree structure can be obtained using swig -dump_tree. +There are a number of other parse tree display options, for example, swig -dump_module will +avoid displaying system parse information and only display the parse tree pertaining to the user's module.
-$ swig -c++ -python -dump_tree example.i
-...
+$ swig -c++ -python -dump_module example.i
+++ include ----------------------------------------
| name - "example.i"
@@ -793,8 +791,8 @@ You can see this when running with the -dump_tree option. For example
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
-data stored in a feature attribute is usually just a raw unparsed string.
+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.
For example, the exception code above is simply
stored without any modifications.
@@ -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
of node tags, attributes, and attribute namespaces are all influenced
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.
@@ -2444,9 +2442,13 @@ Returns the number of required (non-optional) arguments in p.
-This section briefly outlines the steps needed to create a bare-bones
-language module. For more advanced techniques, you should look at the implementation
-of existing modules. Since the code is relatively easy to read, this section
+One of the easiest routes to supporting a new language module is to copy an already
+supported language module implementation and modify it.
+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
this to other languages.
@@ -2456,7 +2458,7 @@ this to other languages.
Code generation modules are defined by inheriting from the Language class,
-currently defined in the Source/Modules1.1 directory of SWIG. Starting from
+currently defined in the Source/Modules directory of SWIG. Starting from
the parsing of command line options, all aspects of code generation are controlled by
different methods of the Language that must be defined by your module.
@@ -2473,10 +2475,6 @@ this example as a guide:
#include "swigmod.h"
-#ifndef MACSWIG
-#include "swigconfig.h"
-#endif
-
class PYTHON : public Language {
public:
@@ -2529,11 +2527,10 @@ also return a pointer to the base class (Language) so that only the int
Save the code for your language module in a file named "python.cxx" and.
-place this file in the Source/Modules1.1 directory of the SWIG distribution.
+place this file in the Source/Modules directory of the SWIG distribution.
To ensure that your module is compiled into SWIG along with the other language modules,
-modify the file Source/Modules1.1/Makefile.in to include the additional source
-files. Look for the lines that define the SRCS and OBJS variables and
-add entries for your language. In addition, modify the file Source/Modules1.1/swigmain.cxx
+modify the file Source/Modules/Makefile.am to include the additional source
+files. In addition, modify the file Source/Modules/swigmain.cxx
with an additional command line option that activates the module. Read the source---it's straightforward.
@@ -2544,7 +2541,7 @@ to regenerate the various build files:
-$ sh autogen.sh
+$ ./autogen.sh
@@ -2742,11 +2739,13 @@ int Python::top(Node *n) {
32.10.6 Module I/O and wrapper skeleton
+
Within SWIG wrappers, there are four main sections. These are (in order)
+
Different parts of the SWIG code will fill different sections, 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 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 -any of the functions of classes. +any of the functions or classes.
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 functionWrapper() as this is the most commonly used function. In fact many of the other wrapper routines will call this to do their work.
@@ -2883,6 +2881,7 @@ functionWrapper : void Shape_y_set(Shape *self,double y)@@ -2894,10 +2893,10 @@ understanding of how to manually write an interface to your chosen language, so make sure you have your documentation handy.
-At this point is also probably a good idea to take a very simple file -(just one function), and try letting SWIG generate up wrappers for many +At this point it is also probably a good idea to take a very simple file +(just one function), and try letting SWIG generate wrappers for many 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.
@@ -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.
-To tackle this problem will be done in two stages: +Tackling this problem will be done in two stages: +
The first step will be done in the code, the second will be done in typemaps.
-Our first step will be to write the code for functionWrapper(). What is -shown below is _NOT_ the solution, merely a step in the right direction. +Our first step will be to write the code for functionWrapper(). What is +shown below is NOT the solution, merely a step in the right direction. There are a lot of issues to address.
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.
@@ -3172,22 +3171,17 @@ subdirectory of Lib. Use (optional) file extra-install.list in that directory to name additional files to install (see ruby for example). -+When you have modified these files, please make sure that the new language module is completely +ignored if it is not installed and detected on a box, that is, make check-examples and make check-test-suite +politely displays the ignoring language message. +
--At some point it would be a good idea to use -automake -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.
-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:
+Please copy these and modify for any new language. +
+@@ -3244,8 +3245,8 @@ files.
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 -in the future). You shouldn't rehash things that are already covered in sufficient +each language module has a dedicated chapter +You shouldn't rehash things that are already covered in sufficient detail in the SWIG Basics and SWIG and C++ chapters. There is no fixed format for what, exactly, you should 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:
+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. +
+ ++Once accepted into CVS, development efforts should concentrate on +getting the entire test-suite to work with plenty of runtime tests. +
+ +