Updated for SWIG-1.3.10

git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk@2099 626c5289-ae23-0410-ae9c-e8d60b6d4f22

SWIG/NEW

@@ -2,13 +2,13 @@ New Features and Important Changes, v1.3
 
 Author(s) :  David Beazley
 
-September 3, 2000
+December 9, 2001
 
 1. Introduction
 ---------------
-This document explains some of the most important changes made since
+This document briefly explains some of the most important changes made
-the release of SWIG1.1.  The goal is to provide information for people
+since the release of SWIG1.1.  The goal is to provide information for
-who want to upgrade an older SWIG interface to the new version.
+people who want to upgrade an older SWIG interface to the new version.
 
 Most changes pertain to the internal implementation of SWIG and the
 organization of the core, parser, and language modules.  As a SWIG
@@ -50,9 +50,9 @@ altered SWIG's old behavior.
      In SWIG1.1, this typemap would get applied to 'foo *',
      'foo &', 'const foo *', 'foo []', 'foo[][]', and so forth.
 
-     In SWIG1.3, this typemap *only* gets applied to 'foo *'.
+     In SWIG1.3, this typemap *only* gets applied to 'foo *' and
-     It does *NOT* get mapped to the other variants listed
+     'const foo *'. It does *NOT* get mapped to the other 
-     above.
+     variants listed above.
 
 2.4  Bug fix.  SWIG now correctly handles typemaps of the form
 
@@ -68,6 +68,37 @@ altered SWIG's old behavior.
      wrapper code.  This provides access to scripting-specific
      variables in the wrapper function.
 
+2.7  SWIG-1.3.10 features a total rewrite of the typemap system.
+     Typemaps now use a different variable naming scheme.  Typemaps
+     for arguments look like this:
+
+       %typemap(in) sometype {
+           $1 = convert value ($input);
+       }
+
+     The variable $1 replaces $target and the variable $input replaces
+     $source.
+
+     For output values, typemaps look like this:
+
+       %typemap(out) sometype {
+          $result = create result ($1);
+       }
+
+     The variable $1 replaces $source and the variable $result replaces
+     $target.
+
+     See Doc/Manual/Typemaps.html for a full description of the new
+     typemap system.
+
+2.8  Multi-argument typemaps are now supported.   This solves a common
+     problem that occurs with functions like this
+
+        void foo(char *buffer, int len);
+
+     where you would like to make the two arguments operate as a single
+     object in the target language.
+
 3. Type checking
 ----------------
 
@@ -165,6 +196,8 @@ and it is simpler to implement than the old string based approach.
 
 4.5 %checkout directive removed.
 
+4.6 %except and %new are deprecated.
+
 5. Language specific changes
 ----------------------------
 
@@ -184,6 +217,10 @@ and it is simpler to implement than the old string based approach.
     system has been added (requires Guile 1.4).  Procedures-with-setters
     can be generated.
 
+5.6 The Python module now automatically creates shadow class objects from the
+    C wrappers.  This fixes a bunch of hard problems related to typemaps,
+    exception handling, and more.
+
 6. New Features
 ---------------
 
@@ -195,6 +232,17 @@ and it is simpler to implement than the old string based approach.
 
 6.4 Integrated preprocessor.  You can now use C macros in SWIG interface files.
 
+6.5 PHP module added.
+
+6.6 %rename directive is greatly enhanced to deal with overloaded functions.
+
+6.7 Support for simple templates
+
+6.8 Support for overloaded operators.
+
+6.9 %feature directive.
+
+
 
 
 

SWIG/README

@@ -1,38 +1,46 @@
 SWIG (Simplified Wrapper and Interface Generator)
 
-Version: 1.3.7 (September 3, 2001)
+Version: 1.3.10 (December 10, 2001)
 
 $Header$
 
 Tagline: SWIG is a compiler that integrates C and C++ with
          languages including Perl, Python, Tcl, Guile, Mzscheme,
-         Java and Ruby.
+         Java, Ruby, and PHP.
 
 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.
 
-This distribution represents the new stable release of SWIG, aiming to
+This distribution represents the latest development release of SWIG,
-replace versions 1.1p5 and 1.1-883. The guilty parties working on this
+aiming to replace versions 1.1p5 and 1.1-883. The guilty parties
-are:
+working on this are:
 
  Dave Beazley (beazley@cs.uchicago.edu)                 (SWIG core)
  William Fulton (wsf@fultondesigns.co.uk)               (Java)
  Matthias Köppe (mkoeppe@mail.math.uni-magdeburg.de)    (Guile/MzScheme)
  Loic Dachary (loic@ceic.com)                           (Perl5)
+ Jason Stewart (jason@openinformatics.com)              (Perl5)
  Thien-Thi Nguyen (ttn@glug.org)                        (Testing/Misc)
+ Lyle Johnson (ljohnson@resgen.com)                     (Ruby)
  Masaki Fukushima (fukusima@goto.info.waseda.ac.jp)     (Ruby)
+ Richard Palmer (richard@magicality.org)                (PHP)
 
-Past contributors (see the CHANGES file for a complete list):
+Past contributors include:
 
 Clark McGrew, Dustin Mitchell, Ian Cooke, Catalin Dumitrescu, Baran
 Kovuk, Gary Holt, David Fletcher, Oleg Tolmatcev, Harco de Hilster.
+(See CHANGES for a more complete list).
 
 Up-to-date SWIG related information can be found at
 
         http://www.swig.org
 
+A SWIG FAQ and other hints can be found on the SWIG Wiki:
+
+       http://swig.cs.uchicago.edu/cgi-bin/wiki.pl
+ 
 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 !!!!!!!                      IMPORTANT                         !!!!!!!
 !!!!!!!                                                        !!!!!!!
@@ -45,13 +53,15 @@ Up-to-date SWIG related information can be found at
 
 What's New?
 ===========
-Here are the most notable changes (so far):
+The most notable changes since SWIG1.1 include the following:
+
+   - Support for C++ overloaded operators.
 
    - Support for C++ templates.
 
-   - Improvement support for overloaded functions/methods.
+   - Improved support for overloaded functions/methods.
 
-   - Parsing support for virtually all C/C++ datatypes.
+   - Parsing support for almost all C/C++ datatypes.
 
    - Pointers to members are now supported in the parser
      and by the Python module.
@@ -67,14 +77,19 @@ Here are the most notable changes (so far):
    - The Guile module is stable. It represents C pointers as smobs and
      supports the Guile module system and exceptions.
 
-   - Java, Ruby, and MzScheme modules added.
+   - Java, Ruby, MzScheme, PHP4 modules added.
+
+   - Redesigned implementation of typemaps.  Typemaps can now be defined
+     for groups of consecutive function arguments.  This has been a long
+     requested feature that now works.
+
+   - Better code generation.   SWIG is better able to make optimizations
+     in order to generate less code.
 
    - Testing framework part of the distribution ("make -k check" support).
 
    - A lot of minor bug fixes and cleanup.
 
-   - SWIG requires an ANSI C compiler.
-
    - Better Windows support.
 
 Here are a few missing features:
@@ -85,23 +100,30 @@ Here are a few missing features:
    - The Tcl7.x and Perl4 modules are deprecated and no longer
      included.
 
-   - The Perl5 module is need in some repair.  We are looking for
+   - The Perl5 module is need in some repair and may not work
-     a maintainer to help us with this.
+     with ActivePerl.  We are looking for volunteers to help us
+     with this.
 
    - A wide variety of old SWIG command-line options and
      obscure features are gone.
 
+   - A lot of old %pragma directives and obscure undocumented
+     customization features have been eliminated.  The same
+     functionality is now available through other means.
+
    - Objective C support doesn't work right now.  No ETA as to
      when it will return.
 
-Although we are making every attempt preserve backwards compatibility
+Although we are making some attempt to preserve backwards
-with interfaces written for SWIG1.1, SWIG1.3 incorporates a number of
+compatibility with interfaces written for SWIG1.1, SWIG1.3
-very substantial modifications to things such as type handling,
+incorporates a number of very substantial modifications to things such
-typemaps, and wrapper code generation.  Therefore, if you are making
+as type handling, typemaps, and wrapper code generation.  Therefore,
-extensive use of advanced SWIG features, interfaces written for
+if you are making extensive use of advanced SWIG features, interfaces
-SWIG1.1 may not work.  We apologize for the inconvenience, but these
+written for SWIG1.1 may not work.  We apologize for the inconvenience,
-changes are needed in order to fix a number of annoying "features"
+but these changes are needed in order to fix a number of annoying
-in SWIG1.1.
+"features" in SWIG1.1.  Hopefully the list of new features will
+provide enough incentive for you to upgrade (and that the modifications
+to your interfaces will only be minor).
 
 In addition, SWIG1.3 makes no attempt to be compatible with SWIG1.1 at
 the C++ API level so language modules written for SWIG1.1 will most
@@ -111,10 +133,13 @@ The files NEW and CHANGES describe in some detail all of the important
 changes that have been made to the system.  Experienced users would be
 well advised to read this.
 
-Windows
+Windows Installation
-=======
+====================
-Please see the Win/Windows.html file for instructions on obtaining 
+Please see the Doc/Manual/Windows.html file for instructions on installing 
-and using SWIG on Windows.
+SWIG on Windows and running the examples. The Windows distribution is 
+called swigwin and includes a prebuilt SWIG executable, swig.exe, included in
+the same directory as this README file. Otherwise it is exactly the same as 
+the main SWIG distribution. There is no need to download anything else.
 
 Unix Installation
 =================
@@ -125,6 +150,19 @@ To build and install SWIG, simply type the following:
      % make -k check	# this step is optional (see note below)
      % make install
 
+By default SWIG installs itself in /usr/local.  If you need to install SWIG in
+a different location or in your home directory, use the --prefix option
+to ./configure.  For example:
+
+     % ./configure --prefix=/home/yourname/projects
+     % make
+     % make -k check
+     % make install
+
+Note: the directory given to --prefix must be an absolute pathname.  Do *NOT* use
+the ~ shell-escape to refer to your home directory.  SWIG won't work properly
+if you do this.
+
 The file INSTALL details more about using configure. Also try
 
      % ./configure --help. 
@@ -142,7 +180,7 @@ Notes:
     before typing 'configure'.    In addition, a full build of SWIG requires
     the use of bison.
 
-(3) 'make -k check' is a new feature that requires at least one of the target
+(2) 'make -k check' is a new feature that requires at least one of the target
     languages to be installed and which performs compile/link level testing
     of the examples.  If it fails, it may mean that you have an uninstalled
     language module or that the file 'Examples/Makefile' has been
@@ -157,19 +195,51 @@ The Examples directory contains a variety of examples of using SWIG
 and it has some browsable documentation.  Simply point your browser to
 the file "Example/index.html".
 
-The Examples directory now includes Visual C++ project files for
+The Examples directory now includes Visual C++ project (.dsp) files for
 building some of the examples on Windows (new in SWIG1.3.7).
 
+Troubleshooting
+===============
+In order to operate correctly, SWIG relies upon a set of library
+files.  If after building SWIG, you get error messages like this,
+
+    % swig foo.i
+    :1. Unable to find 'swig.swg'
+    :3. Unable to find 'tcl8.swg'
+
+it means that SWIG has either been incorrectly configured or
+installed.  To fix this:
+
+    1.  Make sure you remembed to do a 'make install' and that
+        the installation actually worked.  Make sure you have
+        write permission on the install directory.
+
+    2.  If that doesn't work, type 'swig -swiglib' to find out
+        where SWIG thinks its library is located.
+
+    3.  If the location is not where you expect, perhaps
+        you supplied a bad option to configure.  Use
+        ./configure --prefix=pathname to set the SWIG install
+        location.   Also, make sure you don't include a shell
+        escape character such as ~ when you specify the path.
+
+    4.  The SWIG library can be changed by setting the SWIG_LIB
+        environment variable.  However, you really shouldn't
+        have to do this.
+
+If you are having other troubles, you might look at the SWIG Wiki at
+http://swig.cs.uchicago.edu/cgi-bin/wiki.pl.
+
 Documentation
 =============
 The Doc/Manual directory contains the most recent set of updated
 documentation for this release.  As this is an unstable development
-release, the documentation is not quite up to date and is being worked
+release, the documentation is not entirely up to date and is being worked
 on.  We are working on it, but there is a lot of documentation and it
 is going to take time to complete. Please be patient.
 
-! The most up-to-date information concerning new features in SWIG1.3 is the
+!! The most up-to-date information concerning new features in SWIG1.3 is the
-! file Doc/Manual/SWIG.html.
+!! file Doc/Manual/SWIG.html.
 
 There is some technical documentation available in the Doc/Devel 
 subdirectory.  This is not necessarily up-to-date, but it has some

SWIG/TODO

@@ -1,20 +1,19 @@
 						-*- outline -*-
 
-* for release 1.3.7 (or 1.4.0?)
+* for release 1.3.8 (or 1.4.0?)
 
 ** Revive the documentation
 
-** Discuss the %pragma directive syntax change from CVS head.  
+** Maybe port Wrapper DOH-ification from CVS head
-   Why is the syntax changing all the time?  Can't we just stick to
-   the syntax in 1.3a5? 
-
-** Maybe port other parser-related stuff from CVS head
-
-** Maybe get the 10/14/00 ("output file handling and shadow classes") change from CVS head 
 
 ** Fix all the bugs on SourceForge
 
-** Incorporate all the patches on SourceForge
+** Add facilities to attach documentation strings to procedures.
+   There is a patch by twburton on SF for the Python language module,
+   but it needs to be done for all language modules.
+
+** Add support for type annotations, see mkoeppe's message:
+   http://mailman.cs.uchicago.edu/pipermail/swig/2001-June/002652.html
 
 * for the unstable 1.5 series
 
@@ -32,9 +31,6 @@
        in type handling and internal data structures may have broken
        a variety of things.
 
-** [Guile] New %pragma "documentation", which allows to attach documentation
-   strings to a procedure.
-
 ** [Guile] Maybe support keyword args
 
 ** [Guile] Maybe support GOOPS shadow classes
@@ -74,3 +70,5 @@
 
    void add(SWIG_OUTPUT(int) *z, int x, int y)
 
+** Unify Guile and MzScheme support, add support for more Scheme systems.
+