Announce: SWIG 1.3.7

[Matthias Koeppe]

This is to announce release 1.3.7 of SWIG (Simplified Wrapper and
Interface Generator).  SWIG is a compiler that integrates C and C++
with languages including Perl, Python, Tcl, Guile, Mzscheme, Java and
Ruby.  SWIG reads annotated C/C++ header files and creates wrapper
code (glue code) in order to make the corresponding C/C++ libraries
available to the listed languages, or to extend C/C++ programs with a
scripting language.

Here is a summary of the Guile-specific changes for those who know the
old version SWIG 1.1p5:  The Guile module represents pointers as smobs.
(They used to be mangled into strings.)  Memory leaks and type
conversion bugs have been fixed.  The Guile module system, including
dynamic loading, and exceptions are supported.  A typemap-driven
procedure-documentation system has been added (requires Guile 1.4).
Procedures-with-setters can be generated.

SWIG is compatible with Guile 1.3.4 and newer.

The official announcement follows.

*** ANNOUNCE: SWIG 1.3.7 ***

September 3, 2001

Overview
--------
We're pleased to announce the next installment of the SWIG1.3
redevelopment effort.  This release includes more enhancements to
SWIG than have appeared in any prior release. Some of these changes
include the following:

* Type system and parsing *

SWIG can now parse and handle almost any C/C++ datatype including
declarations involving const and volatile, pointers to functions,
pointers to arrays, references, and pointers to C++ members.
This change means that SWIG can parse virtually any C or C++ header
file without reporting parse errors due to types and declarations.

* C++ Templates *

SWIG now provides full support for wrapping C++ template
instantiations.  The only thing you need to do is supply a valid class
name in the target language using a special %template directive.
For example:

    template<class T> class List {
    ... whatever ...
    };

    %template(intList) List<int>;
    %template(doubleList) List<double>;

This approach works equally well for both template classes and template
functions.

* Function and method overloading *

SWIG-1.3.7 does not provide automatic resolution of overloaded functions.
However, the problem is now extremely easy to solve with a
parameterized extension of the %rename directive.  For example:

    %rename(foo_i) Spam::foo(int);    // Rename foo(int) to foo_i(int)
    %rename(foo_d) Spam::foo(double); // Rename foo(double) to foo_d(double)
    ...
    %include "someheader.h"

When applied to a class, the renaming propagates to all derived
classes.  Therefore, applying a few name resolution rules to a base
class will apply those changes across a whole class
hierarchy. Parameterization also works globally. For example:

    %rename(foo_i) foo(int);    // Rename foo(int) to foo_i(int) everywhere

* Pointers to functions *

There is improved support for pointers to functions and callback
functions written in C/C++.    Here is a simple example:

   %module example
   %{
   #include "example.h"
   %}

   // Function with a callback 
   int do_op(int x, int y, int (*op)(int,int));

   // Install some callbacks as "name_op" constants
   %callback("%s_op")
   int add(int, int);
   int sub(int, int);
   int mul(int, int);
   int div(int, int);
   %nocallback

Now in Python,

  >>> import example
  >>> example.do_op(3,4,example.add_op)   # Use callback
  7
  >>> add(3,4)                            # Call function normally
  7

* Improved %import *

The %import directive has been improved to simplify cross-module
linking.  The whole import mechanism was redesigned to make it
easier for language modules to keep track of how modules are
organized and related to each other.

* Better code generation *

SWIG now generates a little less code than before--especially for C++.
Most language modules have a variety of other improvements.

* Improved internals *

This is the first release of SWIG that builds a complete parse tree
before generating code (effectively becoming a 2-pass compiler.  This
has allowed us to implement some subtle semantic improvements that
were not really possible in the earlier release (e.g., not generating
default constructors for classes private constructors).  Future
releases are going to make the parse tree fully available to language
modules as well as the ability to externally export the parse tree to
other applications. Stay tuned.

* Partially updated documentation *

The first part of the SWIG manual has been updated to reflect new
features.  This is the first documentation update in 4 years.
However, updating the entire manual is an ongoing process and is not
yet finished in the 1.3.7 release.  Most new changes and
incompatibilities are documented however.

Availability:
-------------
The release is available for download on Sourceforge at

     http://download.sourceforge.net/swig/swig-1.3.7.tar.gz

Within the next day, a Windows version will also be made available at

     http://download.sourceforge.net/swig/swigwin-1.3.7.zip

What's broken?
--------------
This is the first release of SWIG that breaks backwards compatibility
with SWIG1.1 in a substantial manner.  Although we realize that this
may be painful, these incompatibilities are unavoidable due to 
corrections that needed to be made in order to fix semantic errors
in the SWIG1.1 implementation.   However, we hope that these
changes are a small price to pay for some of SWIG's new features including
support for C++ templates, overloading, and improved parsing.

As this is a work in progress, a number of features are still missing
or incomplete.  The documentation system is still missing and won't be
reimplemented for some time. C++ programmers who make extensive use of
typemaps may encounter a few strange problems (although SWIG will
generate warning messages).

The Perl5 module is also in some need of some repair and may not work
with all Perl configurations such as ActivePerl (It seems to work with
a standard Perl5.6.1 distribution however).  We are looking for a
fearless volunteer to help us with future Perl5 support (please skip
to the end for details).

Documentation
-------------
This release contains partially updated documentation.  Almost all new
SWIG features are described in the updated documentation.  The CHANGES
file contains a detailed log of changes and the README file contains
some additional information.  This is the first SWIG-1.3 release to
include the standard documentation in HTML format (now found in the
Doc directory).

New Development Process
-----------------------
Starting with SWIG1.3, we are adopting an odd/even version numbering
scheme for SWIG.  Odd version numbers (1.3, 1.5, 1.7, etc...) are
considered to be unstable development releases.  Even numbers
(1.4,1.6,1.8) are stable releases.  The current 1.3 effort is working
to produce a stable 1.4 release.  This will not happen until we can
get all of the documentation updated.  In the meantime, occasional
1.3.x releases will be made.

We need your help!
------------------
Even if you are perfectly happy with SWIG1.1, we can still use your
feedback.  First, we like to know about compilation problems and other
issues concerning the building of SWIG.  Second, if SWIG1.3 is unable
to compile your old interface files, we would like to get information
about the features you are using.  This information will help us find
bugs in the SWIG1.3 release, develop techniques for supporting
backwards compatibility, and write documentation that addresses
specific issues related to migrating from SWIG1.1 to SWIG1.3.

We are also looking for volunteers who would like to work on various
aspects of SWIG development.  SWIG is an unfunded project that would
not exist without volunteers.  We are also looking for the developers
of other SWIG language modules.  If you have developed a SWIG module
and would like to see it incorporated into the new release, please
contact us to obtain SWIG developer access.  We are also more than
willing to help port your module from SWIG1.1 to SWIG1.3.
Please send email to address@hidden for further information.

Please report problems with this release to address@hidden

--- The SWIG Developers

David Beazley 
William Fulton
Matthias Köppe
Masaki Fukushima

-- 
Matthias Köppe -- http://www.math.uni-magdeburg.de/~mkoeppe