swig/swigweb/exec.ht

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://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 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.  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.  In particular,
SWIG tends to provide much greater support for C/C++ while
deemphasizing most of the low-level details related to the internal
operation of the target language.  In contrast, tools specialized to a
particular language allow for a greater degree of customization
(although they are often much more difficult to use).

<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 700 people subscribe
to the SWIG mailing list (swig@cs.uchicago.edu) and a public CVS
repository is available at the University of Chicago.