OOF2: The Manual

7.6. Writing SWIG input files
	Chapter 7. Extending OOF2

7.6. Writing SWIG input files

OOF2 uses an old (but stable) version of swig, version 1.1 build 883. These instructions will have to be modified when we move to a later version. There's no fundamental reason that an OOF2 extension can't use a different version of swig, but it'll probably make things a lot harder.

The following sample swig file contains examples of most of the useful constructs. The annotations explain which lines are necessary, and when.

#ifndef EXTENSION_SWG 
#define EXTENSION_SWG 

%module extension 
%{ 
#include "myextension.h" 
%}
%include "common/typemaps.swg" 
%pragma(python) include="myextension.spy" 

%pragma(python) code="from SWIGdir.othermodule import MyBasePtr" 
%extern "othermodule.swg" 

class MyExtension : public MyBase { 
public:
   MyExtension(); 
};

#endif // EXTENSION_SWG

	Defining and checking `EXTENSION_SWG` prevents this file from being included twice in another swig file. Doing this is good idea, even if you're absolutely sure that this file won't ever be included elsewhere. Replace `EXTENSION_SWG` with another name, unique to your swig file.
	This line is recommended, but not required. Replace `extension` with the name of your extension.
	Any code within `%{` and `%}` will be included verbatim in the C++ file that swig generates. It's important to include your extension's header files here.
	This line must be included in every OOF2 swig file to ensure that exceptions are handled correctly. `SRC/common/typemaps.swg` also contains other swig typemaps that you may find useful. They typemaps are listed in the comments at the start of the file.
	This line appends the given file to swig's Python output. The file can contain Python code that modifies the classes produced by swig, or performs other initialization tasks. This is just a convenient place to perform such tasks — if there are no tasks, then this line (and the file) can be omitted. The `.spy` suffix is standard, but only within the OOF2 development team.
	If the swigged class is derived from a base class that was swigged elsewhere, then two things are necessary: the Python code that swig generates must import the base class, and swig must be told about the base class.^[46] This line imports the base class into the swig python output. `SWIGdir` is the directory containing the swig output, specified by `destdir` argument to `get_swig_ext`. Note that the imported name has `Ptr` appended to it!
	An `%extern` line tells swig to load another file but not build any code from it. In this case, the file containing the swig definition of `MyBase` is being loaded. This allows swig to treat the base class properly.
	All swigged base classes of the swigged class need to appear here. Base classes that are not swigged should not be listed.
	All member functions that will be used in Python need to be listed here. Swig typemaps, such as those in `SRC/common/typemaps.swg` or `SRC/engine/typemaps.swg` can be used to process arguments and return values if necessary. See the swig documentation for more information on typemaps.

^[46] Note that when swigging a new OOF2 Property, both of these tasks are handled by engine/propertyhdr.swg.


oof2setuputils.pkg_check		Chapter 8. Writing OOF2 Extensions