Home › So You Want to Embed a Scripting Language in Your Application?

SWIG Overview

Thu, 2005-12-08 13:33 — jason

SWIG is your best friend when it comes to using your application's API from within a scripting language. SWIG stands for "Simplified Wrapper and Interface Generator." With SWIG, you can automatically generate wrapper code to allow you to use your C or C++ library from within a scripting language. The latest "stable" release of SWIG is 1.1p5 which was released in 1998, the latest "development" release is 1.3.27, released in June, 2005.

The 1.3.27 release is known to have some backward compatibility issues and is blocked in Gentoo Linux. However, it is the release that we will be focusing on because it has a wider range of language support.

This release has varying levels of support for the following lanuages:

  • C#
  • Chicken
  • Guile
  • Java
  • Lua
  • Modula-3
  • MzScheme
  • Ocaml
  • Perl5
  • PHP4
  • Pike
  • Python
  • Ruby
  • Tcl

The general usage of SWIG is:

swig -<sourcelanguage> -<targetlanguage> <Interface file>


Specifically, in the case of generating Lua wrapper code for the Crate Game Engine, we would call:

swig -c++ -lua CrateGameEngine.i


Our case is very simple because we have made a point of designing the API to be SWIG friendly. Specifically, that means using datatypes that SWIG knows about. There are three main catagories of types that SWIG knows about.



  1. Built In Types

    2. Built in types are POD types: char, int, long, bool, etc. Also, pointers to these types.

  2. STL Types

    3. STL types that are supported vary from widely from language to language. Currently, Python has very robust support with all major container classes and stream templates supported (e.g. std::vector, std::map, std::iostream, std::string, etc). Other languages, such as Lua, only support vector and string. Note, SWIG does not handle non-const pointers to strings very well. One reason given for this is that some scripting languages consider strings to be immutable.

  3. User Defined Types

    4. User defined types include classes, structs, enums and typedefs. Herein lies one of the main points of SWIG, to be able to generate language specific wrappers for user defined types. It is very well supported

Therefore, to design with SWIG in mind, we have avoided using pointers to strings, and have limited public interfaces involving std classes to std::vector and std::string. Although std::map is supported by most languages in SWIG, it is mostly unusable for the case of:

std::map<string, string>

because the normal behavior of an STL container class is to return a reference to the object that it contains. This allows the user of the container to perform an operation such as:

std::map<string, string> mymap
mymap["test"] = "test1";
mymap.front().second = "test2";


After that code has executed the key "test" is equal to "test2". Remember, SWIG cannot work with non-const pointers to strings very well, so a map that is set up to contain strings is very difficult to work with in the scripting language. Some of the other container classes, namely std::vector, consider std::string as a special case and work with it quite well, however.

That said, our input to SWIG is very simple, the file that we use follows:

%module(directors="1") CrateGameEngine
 
%include "LanguageSpecific.i"
 
%{
#include "CGE/PropertyBag.h"
#include "CGE/Renderer.h"
#include "CGE/Action.h"
#include "CGE/Object.h"
#include "CGE/Player.h"
#include "CGE/Conversation.h"
#include "CGE/Character.h"
#include "CGE/Map.h"
#include "CGE/RenderingEngine.h"
#include "CGE/ScriptingEngine.h"
#include "CGE/System.h"
#include "CGE/World.h"
#include "CGE/WorldLoader.h"
%}
 
%ignore logger(LogType logtype);
 
%include "../include/CGE/PropertyBag.h"
%include "../include/CGE/Renderer.h"
%include "../include/CGE/Action.h"
%include "../include/CGE/Object.h"
%include "../include/CGE/Player.h"
%include "../include/CGE/Conversation.h"
%include "../include/CGE/Character.h"
%include "../include/CGE/Map.h"
%include "../include/CGE/RenderingEngine.h"
%include "../include/CGE/ScriptingEngine.h"
%include "../include/CGE/System.h"
%include "../include/CGE/World.h"
%include "../include/CGE/WorldLoader.h"

Lines that are inside the %{} blocks are inserted verbatim into the resulting CPP which will be compliled to generate the language specific module.