SWIG (Simplified Wrapper and Interface Generator)

Dave Beazley
August 28, 1996

Version 1.0 Final (August 31, 1996)
===================================
1. Fixed minor bug in C++ module

2. Fixed minor bug in pointer type-checker when using
   -DALLOW_NULL.

3. Fixed configure script to work with Python 1.4beta3

4. Changed configure script to allow compilation without
   yacc or bison.

Version 1.0 Final (August 28, 1996)
===================================

1.  Changed parser to support more C/C++ datatypes (well,
    more variants).   Types like "unsigned", "short int",
    "long int", etc... now work.

2.  "unions" added to parser.

3.  Use of "typedef" as in :

	typedef struct {
	     double x,y,z;
	} Vector;

    Now works correctly.   The name of the typedef is used as
    the structure name.

4.  Conditional compilation with #ifdef, #else, #endif, etc...
    added.

5.  New %disabledoc, %enabledoc directives allow documentation
    to selectively be disabled for certain parts of a wrapper
    file.

6.  New Python module supports better variable linking, constants,
    and shadow classes.

7.  Perl5 module improved with better compatibility with XS
    and xsubpp.   SWIG pointers and now created so that they
    are compatible with xsubpp pointers.

8.  Support for [incr Tcl] namespaces added to Tcl module.

9.  %pragma directive added.

10. %addmethods directive added.

11. %native directive added to allow pre-existing wrapper functions
    to be used.

12. Wrote configure script for SWIG installation.

13. Function pointers now allowed with typedef statements.

14. %typedef modified to insert a corresponding C typedef into
    the output file.

15. Fixed some problems related to C++ references.

16. New String and WrapperFunction classes add to make generating
    wrapper code easier.

17. Fixed command line option processing to eliminate core dumps
    and to allow help messages.

18. Lot's of minor bug fixes to almost all code modules


Version 1.0 Beta 3 (Patch 1) July 17, 1996
==========================================

1.0 Final is not quite ready yet, but this release fixes a
number of immediate problems :

1.  Compiler errors when using -strict 1 type checking have been fixed.

2.  Pointer type checker now recognizes pointers of the form
    _0_Type correctly.

3.  A few minor fixes were made in the Makefile

Version 1.0 Beta 3 (June 14, 1996)
===================================


There are lots of changes in this release :

1.  SWIG is now invoked using the "swig" command instead of "wrap".
    Hey, swig sounds cooler.

2.  The SWIG_LIB environment variable can be set to change the
    location where SWIG looks for library files.

3.  C++ support has been added.   You should use the -c++ option
    to enable it.

4.  The %init directive has been replaced by the %module directive.
    %module constructs a valid name for the initialization function
    for whatever target language you're using (actually this makes
    SWIG files a little cleaner).  The old %init directive still works.

5.  The syntax of the %name directive has been changed.   Use of the
    old one should generate a warning message, but may still work.
    
6.  To support Tcl/Tk on non-unix platforms, SWIG imports a file called
    swigtcl.cfg from the $(SWIG_LIB)/tcl directory.   I don't have access
    to an NT machine, but this file is supposedly allows SWIG to
    produce wrapper code that compiles on both UNIX and non UNIX machines.
    If this doesn't work, you'll have to edit the file swigtcl.cfg. Please
    let me know if this doesn't work so I can update the file as
    necessary.

7.  The SWIG run-time typechecker has been improved.    You can also
    now redefine how it works by supplying a file called "swigptr.cfg"
    in the same directory as your SWIG interface files.   By default,
    SWIG reads this file from $(SWIG_LIB)/config.

8.  The documentation system has been changed to support the following :

	-  Documentation order is printed in interface file order by
           default.   This can be overridden by putting an %alpha
           directive in the beginning of the interface file.
   
        -  You can supply additional documentation text using

           %text %{ put your text here %}

        -  A few minor bugs were fixed.

9.  A few improvements have been made to the handling of command line
    options (but it's still not finished).

10.  Lots of minor bug fixes in most of the language modules have been
     made.

11. Filenames have been changed to 8.3 for compatibility with a SWIG
    port to non-unix platforms (work in progress).

12. C++ file suffix is now .cxx (for same reason).

13. The documentation has been upgraded significantly and is now
    around 100 pages.    I added new examples and a section on
    C++.  The documentation now includes a Table of Contents.

14. The SWIG Examples directory is still woefully sparse, but is
    getting better.

Special notice about C++
------------------------
This is the first version of SWIG to support C++ parsing.  Currently
the C++ is far from complete, but seems to work for simple cases.
No work has been done to add special C++ processing to any of
the target languages.   See the user manual for details about how
C++ is handled.   If you find problems with the C++ implementation,
please let me know.  Expect major improvements in this area.

Note : I have only successfully used SWIG and C++ with Tcl and
Python.

Notice about Version 1.0Final
-----------------------------

Version 1.0B3 is the last Beta release before version 1.0 Final is
released.  I have frozen the list of features supported in version 1.0
and will only fix bugs as they show up.  Work on SWIG version 2.0 is
already in progress, but is going to result in rather significant
changes to SWIG's internal structure (hopefully for the better).  No
anticipated date for version 2.0 is set, but if you've got an idea,
let me know.

Version 1.0 Beta 2 (April 26, 1996)
===================================
This release is identical to Beta1 except a few minor bugs are
fixed and the SWIG library has been updated to work with Tcl 7.5/Tk 4.1.
A tcl7.5 examples directory is now included.

- Fixed a bug in the Makefile that didn't install the libraries
  correctly.

- SWIG Library files are now updated to work with Tcl 7.5 and Tk 4.1.

- Minor bug fixes in other modules.


Version 1.0 Beta 1  (April 10, 1996).
=====================================
This is the first "semi-official" release of SWIG.    It has a
number of substantial improvements over the Alpha release.   These
notes are in no particular order--hope I remembered everything....

1.  Tcl/Tk

SWIG is known to work with Tcl7.3, Tk3.6 and later versions.
I've also tested SWIG with expect-5.19.      

Normally SWIG expects to use the header files "tcl.h" and "tk.h".  
Newer versions of Tcl/Tk use version numbers.   You can specify these
in SWIG as follows :

        % wrap -htcl tcl7.4.h -htk tk4.0.h example.i

Of course, I prefer to simply set up symbolic links between "tcl.h" and
the most recent stable version on the machine.

2.  Perl4

This implementation has been based on Perl-4.035.  SWIG's interface to
Perl4 is based on the documentation provided in the "Programming Perl"
book by Larry Wall, and files located in the "usub" directory of the
Perl4 distribution.

In order to compile with Perl4, you'll need to link with the uperl.o
file found in the Perl4 source directory.  You may want to move this
file to a more convenient location.

3.  Perl5

This is a somewhat experimental implementation, but is alot less
buggy than the alpha release.     SWIG operates independently of
the XS language and xsubpp supplied with Perl5.  Currently SWIG
produces the necessary C code and .pm file needed to dynamically
load a module into Perl5.    

To support Perl5's notion of modules and packages (as with xsubpp),
you can use the following command line options :

        % wrap -perl5 -module MyModule -package MyPackage example.i

Note : In order for dynamic loading to be effective, you need to be
careful about naming.    For a module named "MyModule", you'll need to
create a shared object file called "MyModule.so" using something like

        % ld -shared my_obj.o -o MyModule.so

The use of the %init directive must match the module name since Perl5
calls a function "boot_ModuleName" in order to initialize things.
See the Examples directory for some examples of how to get things
to work.

4.  Python1.3

This is the first release supporting Python.    The Python port is
experimental and may be rewritten.   Variable linkage is done through
functions which is sort of a kludge.  I also think it would be nice
to import SWIG pointers into Python as a new object (instead of strings).
Of course, this needs a little more work.

5.  Guile3

If you really want to live on the edge, pick up a copy of Guile-iii and
play around with this.      This is highly experimental---especially since
I'm not sure what the official state of Guile is these days.  This
implementation may change at any time should I suddenly figure out better
ways to do things. 

6.  Extending SWIG

SWIG is written in C++ although I tend to think of the code as mostly 
being ANSI C with a little inheritance thrown in.   Each target language
is implemented as a C++ class that can be plugged into the system.
If you want to add your own modifications, see Appendix C of the user
manual.   Then take a look at the "user" directory which contains some
code for building your own extenions.

7. The SWIG library 

The SWIG library is still incomplete.  Some of the files mentioned in
the user manual are unavailable.    These files will be made available
when they are ready.   Subscribe to the SWIG mailing list for announcements
and updates.

8. SWIG Documentation

I have sometimes experienced problems viewing the SWIG documentation in
some postscript viewers.   However, the documentation seems to print
normally.    I'm working on making much of the documentation online,
but this takes time.

Version 0.1 Alpha (February 9, 1996)
====================================

1.  Run-time type-checking of SWIG pointers.   Pointers are now represented
    as strings with both numeric and encoded type information.    This makes
    it a little harder to shoot yourself in the foot (and it eliminates 
    some segmentation faults and other oddities).

2.  Python 1.3 now supported.

3.  #define and enum can be used to install constants.

4.  Completely rewrote the %include directive and made it alot more powerful.
    
5.  Restructured the SWIG library to make it work better.

6.  Various bug fixes to Tcl, Perl4, Perl5, and Guile implementations.

7.  Better implementation of %typedef directive.

8.  Made some changes to SWIG's class structure to make it easier to expand.
    SWIG is now built into a library file that you can use to make your
    own extenions.   

9.  Made extensive changes to the documentation.

10. Minor changes to the SWIG parser to make it use less memory.
    Also took out some extraneous rules that were undocumented and
    didn't work in the first place.

11. The SWIG library files "tclsh", "wish", "expect", etc... in the first
    release have been restructured and renamed to "tclsh.i", "wish.i",
    and so on.




 











