Executive Summary

<p>
<img src="images/exec.png" alt="Executive Summary">

<p>
SWIG is an interface compiler that connects programs written in C,
C++, and Objective-C with scripting languages including <a href="http://www.perl.org">Perl</a>,
<a href="http://www.python.org">Python</a>, and 
<a href="http://www.scriptics.com">Tcl/Tk</a>.  It works by taking the declarations commonly found in C/C++ header
files and using them to generate the glue code (wrappers) that scripting
languages need to access the underlying C/C++ code.

<p>
John Ousterhout has written a
<a href="http://www.scriptics.com/people/john.ousterhout/scripting.html">paper</a>
that describes the
benefits of scripting languages.   SWIG makes it fairly easy to connect scripting
languages with C/C++ code.

<p>You might use SWIG in a number of ways:

<ul>
<li><b>Building more interesting C/C++ programs</b>.   Using SWIG, you can replace the main()
function of a C program with a scripting interpreter from which you can control your
application.  This adds quite a lot of flexibility and makes it easier to build
extensible programs. When combined with Tk, you can also build graphical user interfaces.

<p>
<li><b>Rapid prototyping and debugging</b>.  SWIG allows C/C++ programs to be placed in
a scripting environment that can be used for testing and debugging.
For example, you might test a library with a collection of scripts or use the scripting
interpreter as an interactive debugger.   Since SWIG requires no modifications to the
underlying C code, it can be used even if the final product does not rely upon scripting.

<p>
<li><b>Systems integration</b>.  Scripting languages work fairly well for controlling and gluing
software components together.  With SWIG, different C/C++ programs can be turned into
scripting language extension modules.   These modules can then be combined together
to create new and interesting applications.
</ul>

SWIG is sometimes compared to interface definition language (IDL)
compilers such as those you would find with systems such as CORBA and
COM.  Although there are a few similarities, the whole point of SWIG
is to make it so you don't have to screw around with that stuff.  If
anything, it's much more of a rapid application development and
prototyping tool.   Specifically:

<p>
<ul>
<li><b>ANSI C/C++ syntax</b>.  SWIG parses a form of ANSI C 
syntax that has been extended with a number of special directives.
As a result, interfaces are usually built by grabbing a header file
and tweaking it a little bit.

<p>
<li><b>SWIG is not a stub generator</b>.  SWIG produces code that you
simply compile and run.  You don't have to fill in any stubs or write
special code as you do with RPC-like systems.

<p>
<li><b>Designed to work with existing C/C++ code</b>.  SWIG requires little, if any, modifications
to existing code.  For the most part, it encourages you to keep a clean separation between
C/C++ and its scripting interface.

<p>
<li><b>Extensibility</b>.  SWIG provides a variety of customization options that
allow you to blow your whole leg off.  SWIG does not enforce any rules related to programming
morality.
</ul>

A number of <a href="doc.html">papers and tutorials</a> describing SWIG are available.
You can also view a simple <a href="tutorial.html">tutorial</a> to see an
example of SWIG in action.