Path: usenet.cis.ufl.edu!usenet.eel.ufl.edu!news.mathworks.com!news.kei.com!news.texas.net!news1.best.com!sgigate.sgi.com!news.msfc.nasa.gov!news.larc.nasa.gov!lerc.nasa.gov!magnus.acs.ohio-state.edu!math.ohio-state.edu!uwm.edu!spool.mu.edu!news.sol.net!uniserve!van-bc!unixg.ubc.ca!nntp.cs.ubc.ca!psgrain!nntp.teleport.com!usenet
From: [email protected] (David Beazley)
Newsgroups: comp.lang.perl.announce,comp.lang.perl.misc
Subject: ANNOUNCE : SWIG 1.0 Beta
Followup-To: comp.lang.perl.misc
Date: 11 Apr 1996 03:37:35 GMT
Organization: University of Utah Computer Science Department
Lines: 426
Approved: [email protected] (comp.lang.perl.announce)
Message-ID: <[email protected]>
NNTP-Posting-Host: julie.teleport.com
X-Disclaimer: The "Approved" header verifies header information for article transmission and does not imply approval of content.
Xref: usenet.cis.ufl.edu comp.lang.perl.announce:316 comp.lang.perl.misc:26631


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 protected].

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 protected].

Cheers,

Dave

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

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.