Executive Summary

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

<p>
SWIG is an interface compiler that connects programs written in C and
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://home.pacbell.net/ouster/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 powerful 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.

<p>
<li><b>Construction of scripting language extension modules</b>.  SWIG can
be used to turn common C/C++ libraries into components for use in
popular scripting languages.   However, before doing this, you might
want to do a search to see if someone else has already made 
such a module.
</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 add an extra layer of IDL specifications
to your application.  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.  This particular approach is especially
useful when the underlying C/C++ program undergoes frequent
modification.

<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 client/server code as you do with RPC-like systems.

<p>
<li><b>SWIG does not define a protocol nor is it a component
framework.</b> SWIG does not define mechanisms or enforce rules
regarding the way in which software components are supposed to
interact with each other.  Nor is it a specialized runtime library
or alternative scripting language API.  SWIG is merely a code generator
that provides the glue necessary to hook C/C++ to other languages.

<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>

It is also worth noting that even though SWIG is occasionally compared
to other more specialized scripting language extension building tools
(e.g., Perl XS, Python bgen, etc.), its primary audience is C/C++
programmers who want to add a scripting language component to their
applications.  Because of this, SWIG tends to have a slightly
different focus than tools designed to build small modules for
widespread use in a scripting language distribution.  By far, the most
significant difference between SWIG and similar tools is that SWIG
implements the full C++ type system--with support for all C datatypes,
C++ classes, namespaces, and templates.  By focusing on types, SWIG is
able to provide a high degree of reliability and it is able to handle
the wrapping of large-scale C/C++ code that appears in real
applications.

<p>
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, or check out how other people are using SWIG
in their <a href="projects.html">projects</a>.

<p>
SWIG has been freely available in various forms since February, 1996
and a large number of developers have made contributions.  Today, SWIG
remains an all-volunteer effort.  Approximately 750 people subscribe
to the SWIG mailing list (swig@cs.uchicago.edu) and a public CVS
repository is available at the University of Chicago.  Over 12000 people
downloaded the last SWIG release (SWIG-1.3.11).