Subject: ANNOUNCE : SWIG 1.0 Beta
From: [email-masked] (David Beazley)
Date: 11 Apr 1996 03:37:35 GMT
Newsgroups: comp.lang.perl.announce,comp.lang.perl.misc

April 9, 1996

Announcing SWIG 1.0 Beta
========================

I am pleased to announce the beta release of SWIG (Simplified Wrapper
and Interface Generator) for Tcl/Tk, Perl, Python, and Guile.

What is SWIG?
-------------

SWIG is an easy-to-use tool that lets you add scripting language
interfaces to programs written in C and C++.  Most scripting languages
can be extended with C and C++ functions.  Unfortunately, doing so
requires one to write special "wrapper" functions--a process that is
usually tedious, error prone, and poorly documented. SWIG automates
this process and frees you to work on the problem at hand instead of
the grungy details of extending your favorite scripting language.
Unlike many other approaches, SWIG is language independent and requires
*little or no* modification to your existing C code.   

What does SWIG provide?
-----------------------

SWIG provides the following functionality for Tcl, Perl4, Perl5,
Python, and Guile:

    1.  Direct access to C/C++ functions.  

    2.  Variable linkage (access to C/C++ global variables)

    3.  Constant creation.

    4.  Support for most of C's basic datatypes.

    5.  Type-checked manipulation of C/C++ pointers, including
        pointers to structs, classes and arrays.

    6.  Automatic documentation generation in ASCII, LaTeX, and HTML.

*** You already know how to use SWIG ***
----------------------------------------

You can learn how to use SWIG in about 5 minutes because everything is
done using ANSI C syntax.

     -  Wrapper functions are created from ANSI C function prototypes.

     -  Link to C variables by simply declaring them.
  
     -  Create constants with #define and enum.

SWIG also adds a small number of specialized directives to do things like
include files, rename functions, etc...

A simple example:
----------------

How hard is it to use SWIG?   It's easy.   Suppose you wanted to add
the following variable and function to the "tclsh" shell :

        /* File : example.c */
        
        double  My_variable = 3.7;
        
        int fact(int n) {
           if (n <= 1) return 1;
           else return n*fact(n-1);
        }

You would write a SWIG interface file that looks like the following
(by convention these have a .i suffix):

        // File : example.i 
        %{
        /* Put header files and support code here */
        %}
        
        %include tclsh.i
        
        extern  double My_variable;
        extern  int   fact(int);

SWIG is invoked with the "wrap" command.   This produces a new
file with a "_wrap.c" suffix.  For our example, we can build a
new version of tclsh and run it as follows :       

        unix > wrap -tcl example.i
        unix > gcc example.c example_wrap.c -ltcl -lm -o my_tclsh
        unix > my_tclsh
        % fact 4
        24
        % puts $My_variable + 4
        7.7
        %

You're done.    You've just extended tclsh with a new function
and variable.    While we're at it, we can also build a Perl5 module :

        unix > wrap -perl5 -module Example example.i
        unix > gcc -c example.c example_wrap.c -I/usr/local/src/perl5.001m
        unix > ld -shared example.o example_wrap.o -o Example.so

Since SWIG interface files are language independent, switching
languages is trivial.  Usually you can just change a few command line
options and recompile the wrapper code.

Type-checked pointers
---------------------

One of SWIG's most powerful features is its support for type-checked C
pointers.  SWIG allows you to wrap almost any C function, even if it
involves pointers to complex objects such as structs and classes.  For
example, we could wrap some of Tcl's C API with the following SWIG
file :

        // tcl.i
        // Wrap Tcl's C interface
        %{
        #include <tcl.h>
        %}

        Tcl_Interp *Tcl_CreateInterp(void);
        void        Tcl_DeleteInterp(Tcl_Interp *interp);
        int         Tcl_Eval(Tcl_Interp *interp, char *script);
        int         Tcl_EvalFile(Tcl_Interp *interp, char *file);

This could, in turn be used to add Tcl support to other scripting
languages.  For example, we might turn this into a Python module
as follows :

        unix > wrap -python -module tcl tcl.i
        unix > gcc -c tcl_wrap.c -I/usr/local/include/Py
        unix > ld -shared tcl_wrap.c -ltcl -lm -o tclmodule.so
        
Our commands could then be used normally within a Python
program as follows :

   unix > python
   Python 1.3 (Mar 26 1996)  [GCC 2.7.0]
   Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam
   >>> import tcl
   >>> interp = tcl.Tcl_CreateInterp();
   >>> tcl.Tcl_Eval(interp,"for {set i 0} {$i < 5} {incr i 1} {puts $i}");
   0
   1
   2
   3
   4
   0
   >>>

SWIG pointers are type-checked at run-time.  Violations result in a
type-error exception in whatever scripting language is being
used.  Like C, functions accepting void* can accept any kind of
pointer.

The SWIG library and multiple files
-----------------------------------

SWIG lets you build libraries and break interfaces into multiple
files.     Suppose that you have written a collection of independent
SWIG interface files for various pieces of an application. You
can easily combine all of these into a single file as follows :

        // File : package.i
        // Build a package out of multiple files
        %{
        %}

        %include graphics.i
        %include network.i
        %include simulate.i
        %include files.i

This file would combine all of the functions from graphics.i,
network.i, simulate.i, and files.i into a single extension.  

SWIG comes with it's own library of useful functions and language
specific extensions.  For example, "%include wish.i" includes code to
build a new wish application while "%include expect.i" would insert
code needed to build an enhanced version of expect.  The SWIG library
is entirely composed of SWIG interface files that can be inserted into
other interface files as needed.  SWIG library files can be both
language specific or language independent as appropriate.  You can
also build your own libraries for use in particular applications.

Real applications involving SWIG
--------------------------------

SWIG is primarily designed for researchers who would like to build
interesting interfaces for their codes, but with minimal effort
and hassle.    Here are some current projects using SWIG :

1.  The SPaSM molecular dynamics code at Los Alamos National
    Laboratory.   SWIG is used to wrap about 250 functions
    and variables into a user-interface for use on the
    Connection Machine 5 and Cray T3D.   

2.  Defibrillation research at the University of Utah.
    John Schmidt has used SWIG to glue together a finite
    element solver, mesh generator, and visualization
    module into a single package controlled via a Tcl/Tk
    interface.   Believe me, if John uses SWIG, you can too.

3.  Peter-Pike Sloan at the University of Utah used SWIG
    to wrap the entire contents of the Open-GL library
    into Tcl---creating an interpreted Open-GL environment
    for use with an Open-GL Tk widget.   This required
    about 5 minutes of work since SWIG was able to parse
    almost all of the Open-GL gl.h header file without
    modification.   SWIG was also used to wrap most of the
    glu.h header file.   The final package contained more
    than 650 constants and 380 C functions.

    ... and more users are starting to discover how easy
        it is to use SWIG their own applications.

What else can you do with SWIG?
-------------------------------

SWIG has a number of uses--some of which you might not expect.

1.      Building interesting interfaces for existing applications.
        Since SWIG works with most C functions, you can usually
        build an interface without changing your code.   If changes
        are required, it usually only involves main() (which 
        sometimes needs to be renamed or removed).

2.      Extremely rapid prototyping.   Wrapping code is fast
        and easy.    Adding functions and variables to your
        scripting language often only takes a matter of minutes
        and can usually be done by copying header files and making
        a few minor modifications.

3.      Debugging.   Have you ever considered using Tcl or Perl
        as a debugger?   With SWIG you can build interfaces
        for code that might not even have an "interface" when
        finished.  For example, I recently had to write a simple
        network server.   To test it out, I wrapped all of its
        functions in Tcl and wrote scripts to create clients and
        test out various operations.   When finished, I took away
        the SWIG interface and was left with standard C code that
        linked with other programs.

4.      Providing an easy-to-use user-extension mechanism.   Suppose
        you've got a big 100,000 line program involving a bunch of 
        C++,C and Tcl/Tk and you'd like the user to be able to 
        extend it with their own customizations.    Why not use
        SWIG?  A SWIG interface file could be used to add user
        extensions as needed and the user doesn't need to worry
        about all of the nasty underlying details of how you've
        actually built the interface.

5.      Building modules.    SWIG can certainly be used to build
        Tcl, Perl, and Python modules.    This wasn't my original
        intent, but there's nothing stopping you from using
        SWIG as a module builder.   Can't find a module with the
        functionality you want?  Build it yourself with SWIG.

6.      Developing language-independent applications.   Each
        scripting language is better at different things.  With
        SWIG you can choose the language most appropriate for
        the job.    Since SWIG doesn't require code modifications,
        you can even use it to evaluate different interface languages
        without risk.   You could even let the end-user choose the
        one they want to use.

7.      Combining applications.  With SWIG you can glue together
        different programs to form interesting applications. For
        example, you could wrap a simulation package and the C API
        to Matlab and use the two together to make an interactive
        data-analysis and visualization tool.

Does SWIG work with other extensions?
-------------------------------------

SWIG is not a language extension.  It works all of its magic through
the standard C API of the target scripting language.  Therefore, you
should be able to use SWIG with other extentions as needed.  Usually
this can be done by inserting a call to SWIG's initialization
function inside the initialization function used by the third party
extention.  With dynamic loading, it is even easier.

Extending SWIG
--------------

SWIG is implemented as a collection of C++ classes.   You can
support a new target language by making a new class.   Or if
you desire, you can make customizations one of the existing
language classes.   The SWIG distribution comes with a template
file containing everything you need to customize SWIG to
your liking.  

Other Features of SWIG
----------------------

     -   Automatic documentation generation in ASCII, LaTeX, HTML.
         SWIG can turn C/C++ comments into documentation describing
         your interface.

     -   Error messages.   SWIG generates sensible error messages
         (including line numbers and files).   Mistakes in SWIG
         interface files are pretty easy to track down.

     -   Performance.    SWIG is written entirely in C++ and is fast.
         Wrapping the Open-GL library takes about 1 second on an
         SGI Indy.

Installation Requirements
-------------------------

        1. A C++ compiler 
        2. bison or yacc
        3. Tcl/Tk, Perl, Python, or Guile (otherwise SWIG is pretty
           useless).     

Supported Systems
-----------------

SWIG works on virtually all Unix systems.  I've tested it on the
following systems :

        SunOS 4.1.3
        Solaris
        Irix 5.x,6.x
        HPUX
        Linux
        MachTen

Target Languages
----------------

The following target languages are supported :

        Tcl 7.3, Tk 3.6 (and all newer versions).
        Perl4
        Perl5
        Guile-iii
        Python 1.3

Where can I get SWIG?
---------------------

SWIG is available at the following locations :

        http://www.cs.utah.edu/~beazley/SWIG

or anonymous-ftp at
        
        ftp://ftp.cs.utah.edu/pub/beazley/SWIG

The distribution includes a user manual and some examples.  SWIG is
free software.  You may use it in any manner provided you retain its
original copyright notices.

SWIG Resources (and mailing list)
---------------------------------

If you would like to learn more about SWIG, you can check out the SWIG
homepage listed above.  You can also subscribe to the SWIG mailing
list by sending a message "subscribe swig" to [email-masked].

Changes since the last release
------------------------------

SWIG 1.0b1 represents a significant upgrade of SWIG 0.1a.  New
features include :

        - Type-checked pointers
        - Python 1.3 support
        - #define and enums create constants.
        - Support for const and struct keywords
        - Better multiple file support
        - Small bugs fixes to many parts of the code
        - Improved portability of SWIG source

Try SWIG risk free!
-------------------

Again, SWIG requires virtually no modifications to your C programs.
You can start using it immediately.  If you don't like it, just
blow away the SWIG interface file and go back to your original C
program.   It's that easy.

Questions about SWIG may be addressed to myself at the address below
or to the swig mailing list at [email-masked].

Cheers,

Dave

----------------------------------------------------------------
Dave Beazley
Department of Computer Science
University of Utah
Salt Lake City, Utah  84112
[email-masked]              http://www.cs.utah.edu/~beazley
----------------------------------------------------------------