The great merge

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

.cvsignore

@@ -3,3 +3,6 @@ Makefile
 swig
 *.tar.gz
 configure
+swig.spec
+autom4te.cache
+.gdbinit

ANNOUNCE

@@ -1,73 +1,74 @@
+*** ANNOUNCE: SWIG 1.3.16 ***
 
-*** ANNOUNCE : SWIG1.3 (Alpha 5) ***
+http://www.swig.org
 
-September 22, 2000
+October 14, 2002
 
-Overview
---------
-We're pleased to announce the next installment of the SWIG1.3
-redevelopment effort.  This release represents a reasonably stable
-snapshot of the CVS repository that has undergone extensive testing
-and debugging.  However, this release also represents work in progress
-so there may be obscure bugs and problems that we haven't found yet.
-Please send us your feedback.
+We're pleased to announce SWIG 1.3.16, the latest installment in the
+SWIG development effort.  SWIG-1.3.16 is mostly a bug-fix release to
+SWIG-1.3.15. 
+
+What is SWIG?
+-------------
+SWIG is a software development tool that reads C/C++ header files and
+generates the wrapper code needed to make C and C++ code accessible
+from other languages including Perl, Python, Tcl, Ruby, PHP, Java,
+Guile, Mzscheme, and Ocaml.  Major applications of SWIG include
+generation of scripting language extension modules, rapid prototyping,
+testing, and user interface development for large C/C++ systems. 
 
 Availability:
 -------------
 The release is available for download on Sourceforge at
 
-     http://download.sourceforge.net/swig/swig1.3a5.tar.gz
-
-What's new?
------------
-On the surface, this release still looks a lot like SWIG1.1p5 except
-that a lot of bugs have been fixed and the language modules tend to
-generate smaller and more efficient wrappers. New modules have also
-been added to support Ruby and Mzscheme. In addition, Python, Perl,
-and Guile support has been enhanced to support new releases such as
-Python1.6 and Perl5.6.
-
-Under the hood, you will find that this release is an almost complete
-reimplementation of SWIG's internals.  In fact the only code that
-still remains from SWIG1.1 is the C/C++ parser and the language
-modules (all of which have undergone significant changes as well).  As
-a result, a lot of minor improvements can be found throughout the
-system and things that used to cause problems may now work (for
-instance, pointers to functions are now supported).  In addition, this
-release incorporates a number of feature requests that have been made
-on the mailing list.
-
-What's broken?
---------------
-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.  The Java module is also temporarily out
-of service for this release.  In addition, C++ programmers who make
-extensive use of typemaps may encounter a few strange problems
-(although SWIG will generate warning messages).
+     http://prdownloads.sourceforge.net/swig/swig-1.3.16.tar.gz
+
+Within the next day, a Windows version will also be made available at
+
+     http://prdownloads.sourceforge.net/swig/swigwin-1.3.16.zip
+
+Release numbers
+---------------
+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 development releases.  Even numbers (1.4,1.6,1.8) are stable
+releases.  The current 1.3 effort is working to produce a stable 2.0
+release.  A stable 2.0 release will not be made until it can
+accompanied by fully updated documentation.  In the meantime, we will
+continue to make periodic 1.3.x releases.
 
 We need your help!
 ------------------
-Even if you are perfectly happy with SWIG1.1, we can use your
+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.
-Finally, we are still looking for volunteers to work on aspects of
-SWIG development.  Please send email to [email protected] for
-details.
+
+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-CVS access.  We are also more than willing
+to help port your module from SWIG1.1 to SWIG1.3.  Please send email
+to [email protected] for further information.
 
 Please report problems with this release to [email protected].
 
 --- The SWIG Developers
 
-David Beazley 
-Thien-Thi Nguyen
-Matthias K�ppe
-Masaki Fukushima
-Harco de Hilster
-Loic Dachary
-Oleg Tolmatcev
+
+
+
+
+
+
+
+
+
+
+

CHANGES.current

@@ -0,0 +1,232 @@
+Version 1.3.17 (November 22, 2002)
+==================================
+11/19/2002: beazley
+            Fixed [ 613922 ] preprocessor errors with HAVE_LONG_LONG.
+
+11/19/2002: beazley
+            Fixed [ 615480 ] mzscheme SWIG_MustGetPtr_.
+
+11/19/2002: beazley
+            Fixed [ 635119 ] SWIG_croak causes compiler warning.
+
+11/16/2002: cheetah (William Fulton)
+            [Java] Added typemaps for pointers to class members.
+
+11/15/2002: cheetah (William Fulton)
+            [Java] Bug fix: Overloaded C++ functions which cannot be overloaded in Java 
+            once again issue a warning.
+
+11/14/2002: cheetah (William Fulton)
+            [Java] Handling of NULL pointers is improved. A java null object will now
+            be translated to and from a NULL C/C++ pointer by default. Previously when 
+            wrapping:
+
+                class SomeClass {...};
+                void foo(SomeClass *s);
+
+            and it was called from Java with null:
+
+                modulename.foo(null)
+
+            a Java NullPointerException was thrown. Extra typemaps had to be written in
+            order to obtain a NULL pointer to pass to functions like this one. Now the 
+            default wrapping will detect 'null' and translate it into a NULL pointer.
+            Also if a function returns a NULL pointer, eg:
+
+                SomeClass *bar() { return NULL; }
+
+            Then this used to be wrapped with a SomeClass proxy class holding a NULL
+            pointer. Now null is returned instead. These changes are subtle but useful.
+            The original behaviour can be obtained by using the original typemaps:
+
+                %typemap(javaout) SWIGTYPE {
+                    return new $&javaclassname($jnicall, true);
+                  }
+                %typemap(javaout) SWIGTYPE *, SWIGTYPE &, SWIGTYPE [] {
+                    return new $javaclassname($jnicall, $owner);
+                  }
+                %typemap(javagetcptr) SWIGTYPE, SWIGTYPE *, SWIGTYPE &, SWIGTYPE [] %{
+                  protected static long getCPtr($javaclassname obj) {
+                    return obj.swigCPtr;
+                  }
+                %}
+
+            *** POTENTIAL INCOMPATIBILITY FOR JAVA MODULE ***
+
+
+11/12/2002: beazley
+            Fixed problem with abstract methods and signatures.  For example:
+
+            class abstract_foo { 
+            public: 
+                virtual int   meth(int meth_param) = 0; 
+            }; 
+
+
+            class abstract_bar : public abstract_foo { 
+            public: 
+                int meth(int meth_param_1, int meth_param_2) { return 0; }
+            };
+
+            In this case, abstract_bar is still abstract.
+
+            Fixes [ 628438 ] Derived abstract class not abstract.
+            Reported and patched by Scott Michel.
+
+11/11/2002: beazley
+            Fixed a matching problem with typemaps and array dimensions.  For example, if you
+            had this:
+
+               typedef char blah[20];
+
+            and a typemap:
+
+               %typemap() char [ANY] {
+                   ... $1_dim0 ...
+               }
+
+            then $1_dim* variables weren't be expanded properly.  It should work now.
+            Problem reported by Pankaj Kumar Goel.
+
+11/07/2002: mkoeppe
+	    Added an experimental new module that dumps SWIG's parse
+	    tree as (Common) Lisp s-expressions.  The module is
+	    invoked with SWIG's -sexp command-line switch.  The output
+	    can be read into Common Lisp.  There is (prototype)
+	    example Lisp code that generates Foreign Function Interface
+	    definitions for use with Kevin Rosenberg's UFFI.
+
+	    *** EXPERIMENTAL NEW FEATURE ***
+
+11/07/2002: mkoeppe
+	    Removed duplicate declaration of "cpp_template_decl" in
+	    parser.y; bison 1.75 complained.
+
+11/06/2002: cheetah (William Fulton)
+            [Java] Default primitive array handling has changed like arrays of classes. 
+            C primitive arrays are no longer wrapped by a Java array but with a pointer 
+            (type wrapper class). Again the changes have been made for efficiency reasons. 
+            The original typemaps have been moved into arrays_java.i, so the original 
+            behaviour can be obtained merely including this file:
+
+                %include "arrays_java.i"
+
+            The array support functions are no longer generated by default. They are only
+            generated when including this file, thus this often unused code is only
+            generated when specifically requiring this type of array support.
+
+            *** POTENTIAL INCOMPATIBILITY FOR JAVA MODULE ***
+
+11/05/2002: ljohnson (Lyle Johnson)
+            [Ruby] Added support for nested module declarations (as was
+            previously added for the Perl module). So a %module directive
+            of the form:
+
+                %module "Outer::Inner::Foo"
+
+            will nest everything as (in Ruby code):
+
+                module Outer
+                  module Inner
+                    module Foo
+                      # stuff goes here
+                    end
+                  end
+                end
+
+11/05/2002: mkoeppe 
+	    [MzScheme] Add an argument (-declaremodule) that generates
+	    code to correctly declare a primitive module extension.
+	    Patch submitted by Bruce Butterfield.
+
+11/02/2002: cheetah (William Fulton)
+            [Java] Added patch submitted by Michael Cahill to remove unused parameter
+            warnings for the jenv and cls parameters. This patch also also allows one
+            to use "void" in the jni typemap for any type without code being generated
+            attempting to return a value.
+
+10/29/2002: cheetah (William Fulton)
+            [Java] Array handling is different. Arrays of classes are no longer wrapped
+            with proxy arrays, eg wrapping
+
+                class X {...};
+                X foo[10];
+
+            used to be wrapped with these Java getters and setters:
+
+                public static void setFoo(X[] value) {...}
+                public static X[] getFoo() {...}
+
+            This approach is very inefficient as the entire array is copied numerous
+            times on each invocation of the getter or setter. These arrays are now
+            wrapped with a pointer so it is only possible to access the first array element 
+            using a proxy class:
+
+                public static void setFoo(X value) {...}
+                public static X getFoo() {...}
+
+            Arrays of enums have also been similarly changed. This behaviour is now like the 
+            other SWIG language's implementation and the array library should be used to 
+            access the other elements. The original behaviour can be achieved using the 
+            macros and typemaps in arrays_java.i, for example:
+
+                %include "arrays_java.i"
+                JAVA_ARRAYSOFCLASSES(X)
+                class X {...};
+                X foo[10];
+
+            *** POTENTIAL INCOMPATIBILITY FOR JAVA MODULE ***
+
+10/29/2002: cheetah (William Fulton)
+            [Java] Two new typemaps javain and javaout for generating the proxy class 
+            and type wrapper class method calls to the JNI class. The new typemaps are 
+            really used for transforming the jstype (used in proxy class and type wrapper
+            classes) to the jtype (used in the JNI class) and visa versa. A javain typemap
+            is required whenever an in typemap is written and similarly javaout for an out
+            typemap. An example is probably best to show them working:
+
+                %typemap(javain) Class "Class.getCPtr($javainput)"
+                %typemap(javain) unsigned short "$javainput"
+                %typemap(javaout) Class * {
+                    return new Class($jnicall, $owner);
+                  }
+
+                %inline %{
+                    class Class {};
+                    Class * bar(Class cls, unsigned short ush) { return new Class(); };
+                %}
+
+            The generated proxy code is then:
+
+                public static Class bar(Class cls, int ush) {
+                  return new Class(exampleJNI.bar(Class.getCPtr(cls), ush), false);
+                }
+
+
+            Some new special variables have been introduced in order to use these typemaps.
+            Here $javainput has been replaced by 'cls' and 'ush'. $jnicall has been replaced by 
+            the native method call, 'exampleJNI.bar(...)' and $owner has been replaced by 'false'.
+            $javainput is analogous to the $input special variable. It is replaced by the parameter name.
+            $jnicall is analogous to $action in %exception. It is replaced by the call to the native
+            method in the JNI class.
+            $owner is replaced by either true if %newobject has been used otherwise false.
+
+            The java.swg file contains default javain and javout typemaps which will produce the same code
+            as previously. This change is only of concern to those who have written their own typemaps as
+            you will then most likely have to write your own javain and javaout typemaps.
+
+            The javaout typemap also makes it possible to use a Java downcast to be used on abstract 
+            proxy base classes. See the Java documentation on dynamic_cast.
+
+            *** POTENTIAL INCOMPATIBILITY FOR JAVA MODULE ***
+
+10/24/2002: ttn
+	    [Methodology] Upgaded to libtool 1.4.3, presumably w/ better
+	    support for newish platforms (like MacOS X).
+
+10/21/2002: ttn
+	    Fixed Runtime/Makefile.in bug -- thanks to Richard Calmbach.
+
+10/18/2002: ttn
+	    Fixed typo in doh.h -- thanks to Max Horn.
+

Doc/engineering.html → Doc/Devel/engineering.html

@@ -81,15 +81,10 @@ <h2>2. Programming Languages and Libraries </h2>
 
 All SWIG modules must be written in either ANSI C or one of the
 scripting languages for which SWIG can generate an interface (e.g.,
-Perl, Python, or Tcl).  <B>C++ is NOT an acceptable alternative and
-will not be utilized for any future development due to the fact that
-it is too complicated, too dogmatic, too problematic, and that Dave
-would rather take a bullet to the head than write one more line of
-code in this most decidedly unpleasant language. </B> Rare exceptions
-to this rule may be made if there is a justifiable need to interface
-an existing piece of software written in C++ into the SWIG module
-system.  Anyone who finds this rule to be unreasonable is more than
-welcome to go write their own wrapper generator--so there.
+Perl, Python, or Tcl).  C++ is currently being used to write
+SWIG modules, but it is only being utilized to avoid working with 
+a lot of pointers to functions.  <b>Advanced C++ features like namespaces, templates,
+and overloading should not be used.</b>.
 
 <p>
 Module writers should make every attempt to use only those functions

Doc/index.html → Doc/Devel/index.html

@@ -7,7 +7,6 @@
 This directory contains SWIG documentation:
 
 <ul>
-<li><a href="whitepaper.html">Project Overview Whitepaper</a>
 <li><a href="engineering.html">Engineering Manual</a>
 <li><a href="internals.html">Internals Manual</a>
 <li><a href="migrate.txt">SWIG1.3 Migration Guide</a>