From e35de3c8ed7cc984e343137aac04efe04532cf7b Mon Sep 17 00:00:00 2001 From: William S Fulton Date: Wed, 1 Aug 2001 16:08:34 +0000 Subject: [PATCH] Updated with files from release 1.3.6 git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk@1397 626c5289-ae23-0410-ae9c-e8d60b6d4f22 --- SWIG/CHANGES | 526 +++++++++++++++++++++++++++++++++------------------ SWIG/NEW | 2 +- SWIG/README | 191 +++++++++---------- SWIG/TODO | 77 +++++++- 4 files changed, 493 insertions(+), 303 deletions(-) diff --git a/SWIG/CHANGES b/SWIG/CHANGES index f922f706a..b2724a193 100644 --- a/SWIG/CHANGES +++ b/SWIG/CHANGES @@ -1,241 +1,395 @@ SWIG (Simplified Wrapper and Interface Generator) -:::: NOTE :::: The CVS head works towards release 1.4; it is currently - unstable. The CVS branch "mkoeppe-1-3-a5-patches" - starting from release 1.3a5 works towards the next - stable release (1.3.6). +The Stable Development Branch +============================= -Work in progress -================ +In this CVS branch "mkoeppe-1-3-a5-patches", fixes in the SWIG core +and improvements to the language modules take place, starting from the +relatively stable release 1.3a5. It works towards the new stable +release 1.3.6. -06/14/2001: mkoeppe - Use %%except instead of %except in some format - strings. Reported by Ovidiu Toader, SF Bug #231923. +This branch is also the basis for the "swig1.3" Debian package +(currently unofficial, available from +http://www.math.uni-magdeburg.de/~mkoeppe/imo-debian). -02/03/01: beazley - Fixed some bugs related to typedef and typemaps. The following - declarations are now legal: +Eventually this branch will be merged with the development on the +trunk of the CVS tree. - typedef type (f)(parms); +Version 1.3.6 (July 9, 2001) +============================= - %typemap(method) type (*f)(parms) { - ... - } +7/09/2001: cheetah (william fulton) + * GIFPlot examples: FOREGROUND and BACKGROUND definition missing + after TRANSPARENT #define fix in GIFPlot -01/16/01: ttn - Integrated XML output code contributed by Klaus Wiederaenders. - This includes new directories Examples/xml and Lib/xml, and - new files Source/Modules1.1/xml.*. Usage: swig -xml OUT foo.i - which writes the foo.i parse tree to xml file OUT. +7/03/2001: beazley + Fixed up the version numbers so that the release is known + as 1.3.6. All future releases should have a similar + version format. -01/16/01: ttn - Wrote table of contents for Doc/engineering.html. Added section - on CVS tagging conventions. Added copyright to other docs. +7/02/2001: mkoeppe + * [Python]: Prevent the problem of self.thisown not being + defined if the C++ class constructor raised an exception. + Thanks to Luigi Ballabio . -12/23/00: beazley - C++ wrappers now always include default constructors and destructors. - Most people want these anyways. In addition, this solves some - problems related to virtual destructors and derived classes - originally reported by Roy LeCates. Note: constructor wrappers - are never generated for abstract classes. - *** NEW FEATURE *** +6/29/2001: mkoeppe + * More portability fixes; fixed "gcc -Wall" warnings. -12/23/00: beazley - Changes to class wrappers. When SWIG sees two classes like this, +6/29/2001: cheetah (william fulton) + * GIFPlot examples: TRANSPARENT #define multiple times on Solaris + (clashes with stream.h). + * Multiple definition bug fix for shadow classes. The perl and python + modules had workarounds which have been replaced with fixes in + the core. Many of the Language::cpp_xxxx functions now set a + flag which the derived classes can access through + is_multiple_definition() to see whether or not code should be + generated. The code below would have produced varying degrees + of incorrect shadow class code for the various modules: + class TestClass + { + public: + TestClass() {}; + TestClass(int a) {}; + ~TestClass() {}; + unsigned long xyz(short k) {}; + unsigned long xyz(int n) {}; + static void static_func() {}; + static void static_func(int a) {}; + }; + void delete_TestClass(int a); - class X { - public: - void foo(); - ... - } +6/27/2001: mkoeppe + * [Perl] Another const-related portability fix. - class Y : public X { - public: - void bar(); - ... - } +6/26/2001: cheetah (william fulton) + * [Java] Added in cpp_pragma() support with a host of new pragmas - see + jswig.html. These are designed for better mixing of Java and c++. It + enables the user to specify pure Java classes as bases and/or interfaces + for the wrapped c/c++. + * [Java] Old pragmas renamed. Warning given for the moment if used. + *** POTENTIAL INCOMPATIBILITY FOR JAVA MODULE *** - it now generates two wrapper functions: +6/25/2001: mkoeppe + * Incorporated more build changes contributed by Wyss Clemens + for swig/ruby on cygwin. - X_foo(X *x) { x->foo(); } - Y_bar(Y *y) { y->bar(); } +6/20/2001: cheetah (william fulton) + * Makefile mods so that 'make check' uses the swig options in the makefiles + * [Java] Removed Generating wrappers message + * [Java] NULL pointer bug fix + * [Java] Bug fix for Kaffe JVM - Unlike SWIG1.15, the foo() method does *not* result in a wrapper - function Y_foo(). Instead, the base class method X_foo() must be - used. - *** POTENTIAL INCOMPATIBILITY *** +6/20/2001: mkoeppe + * SWIG_TypeQuery from common.swg now returns a + swig_type_info* rather than a void*. This fixes a problem + when using pointer.i and C++, as illustrated by the new + test-suite example perl5/pointer-cxx. + * Portability fixes (const char *). + * Incorporated build changes contributed by Wyss Clemens + , which make swig runnable on cygwin. -12/23/00: beazley - Typemaps can now be placed inside class definitions. For example: +6/19/2001: cheetah (william fulton) + * [Java] Bug fix for SF bug #211144. This fix is a workaround + until fixed in the core. - class Foo { - public: - %typemap(in) double { - // Whatever - ... - } - ... - }; +6/19/2001: mkoeppe + * [Guile]: Portability fixes for use with the Sun Forte + compilers. + * [Tcl]: Portability fix (const char *). + * [Tcl]: Configure now first tries to find a tclConfig.sh + file in order to find the Tcl include directory, library + location and library name. + * [Python]: Added a few possible library locations. - When used in this manner, the typemap is applied to all class - members that follow. In addition, the typemap is inherited - and will be applied in any derived classes. On the other - hand, class typemaps are *not* applied to any declarations - appearing outside of the class (i.e., the scope of the typemap - is the class and any derived classes). - *** NEW FEATURE *** +6/18/2001: mkoeppe + * [Guile]: Don't call scm_c_export if nothing is to be + exported. Don't warn on %module if module has been set + already (this frequently occurs when %import is used). -12/21/00: beazley - The %readonly directive is now defined as a scope. For example: +6/16/2001: mkoeppe + * [Guile]: New "passive" linkage, which is appropriate for + multi-module extensions without Guile module magic. - %readonly { - int foo; - int bar; - } +6/15/2001: mkoeppe + * [Guile]: Fixed printing of smobs (space and angle were + missing). + * Properly generate type information for base classes + imported with the %import directive. Thanks to Marcelo + Matus for the report and the + patch; this closes SF bug #231619; see also + Examples/guile/test-suite/import*. + * [Guile]: Fix casting between class and base class; the + runtime type system had it the wrong way around; see + Examples/guile/test-suite/casts.i + * Make typemaps for SWIGPOINTER * with arg name take + precedence over those without arg name, to match normal + typemap precedence rules. + * Fixed the random-line-numbers problem reported as SF bug + #217310; thanks to Michael Scharf . + * [Guile]: Handle the %name and %rename directives. + * New syntax: %name and %rename now optionally take double + quotes around the scripting name. This is to allow scripting + names that aren't valid C identifiers. - *** INCOMPATIBILITY *** +6/14/2001: beazley + Made a minor change to the way files are loaded in + order to get file/line number reporting correct in + the preprocessor. -12/21/00: beazley - The %native directive is now a scope. It works as follows: +6/14/2001: mkoeppe + * The parser now understands the (non-standard) "long long" + types. It is up to the individual language modules to + provide typemaps if needed. Reported by Sam Steingold, SF + bug #429176. + * The parser now understands arguments like "const int * + const i". This fixes SF bug #215649. + * Fixed the Guile test-suite. - %native { - /* List functions with native prototypes */ - PyObject *blah(PyObject *args, PyObject *self); - %name(foo) PyObject *wrap_foo(PyObject *args, PyObject *self); - ... - } +6/13/2001: mkoeppe + Partial merge from the CVS trunk at tag + "mkoeppe-merge-1". This covers the following changes: - See note from 9/30/00 below. In addition, native function wrapping - has been enhanced in the Python/Tcl modules. For example, the - Python module can automatically distinguish between keyword and - non-keyword wrappers. Similarly, the Tcl module can distinguish - between Tcl7 and Tcl8 style wrappers. - *** POTENTIAL INCOMPATIBILITY *** +| 01/16/01: ttn +| Wrote table of contents for Doc/engineering.html. Added section +| on CVS tagging conventions. Added copyright to other docs. +| 9/25/00 : beazley +| Modified the preprocessor so that macro names can start with a '%'. +| This may allow new SWIG "directives" to be defined as macros instead +| of having to be hard-coded into the parser. +| +| *** Also a yet-to-be-documented quoting mechanism with backquotes +| *** has been implemented? -12/15/00: beazley - SWIG now builds a complete parse tree before generating any wrapper - code. Wrappers now appear in the same order as they appear - in the interface file. In SWIG1.1, wrapping of classes was - deferred until everything else had been handled. +6/13/2001: mkoeppe + * When configure does not find a language, don't use default + paths like /usr/local/include; this only causes build + problems. + * New directory: Examples/Guile/test-suite, where a few + bugs in 1.3a5 are demonstrated. + * Handle C++ methods that have both a "const" and a "throw" + directive (see Examples/Guile/test-suite/cplusplus-throw.i); + thanks to Scott B. Drummonds for the report and the fix. + * Handle C++ pointer-reference arguments (like "int *& arg") + (see Examples/Guile/test-suite/pointer-reference.i, + reported as SF bug #432224). + * [Ruby] Fixed typo in rubydec.swg; thanks to Lyle Johnson! + * Don't stop testing when one test fails. + * [Guile, MzScheme] Don't print "Generating wrappers...". -12/15/00: beazley - New %scope directive defines a SWIG scope. Basically, a scope - is a way of enclosing a collection of declarations that might - share a common property. For example: +6/12/2001: mkoeppe + [Guile] VECTORLENINPUT and LISTLENINPUT now have separate + list length variables. TYPEMAP_POINTER_INPUT_OUTPUT + attaches argument documentation involving SCM_TYPE to the + standard pointer typemaps. INOUT is now an alias for BOTH. - %scope("native") { - /* Native wrappers */ - PyObject *blah(PyObject *args, PyObject *self); - ... - } +6/12/2001: cheetah (william fulton) + Some Java documentation added. + [Java] Fixed bugs in import pragma and shadow pragma. - or +6/12/2001: mkoeppe + Fix declarations of SWIG_define_class + (Lib/ruby/rubydec.swg) and SWIG_TypeQuery + (Lib/common.swg). Thanks to Lyle Johnson + for the patches. - %scope("readonly") { - /* Readonly variables */ - int x; - ... - } +6/11/2001: mkoeppe + [Guile] Use long instead of scm_bits_t; this makes the + generated wrapper code compatible with Guile 1.3.4 + again. Thanks to Masaki Fukushima for pointing this out. - An unnamed scope can also be used: +6/11/2001: cheetah (william fulton) + The generic INSTALL file from autoconf added. Few changes to README file. - %scope { - ... declarations ... - } +6/11/2001: mkoeppe + Fixed typo in Makefile.in; thanks to Greg Troxel + . - In addition to collecting objects, typemaps and other customization - features defined within a scope only get applied to those objects. - That is, a typemap defined in a scope will disappear at the end of - the scope. - *** NEW FEATURE *** +6/08/2001: cheetah (william fulton) + make check works again. Examples/GIFPlot configure generated by + top level autoconf now. -10/14/00: beazley - Fixed some problems in output file handling and shadow classes. - Problem reported by Luigi Ballabio. +6/08/2001: mkoeppe + Another build change: The new script autogen.sh runs + autoconf in the appropriate directories. The top-level + configure also configures in Examples/GIFPlot. -10/14/00: beazley - Incorporated new set of patches for Macintosh support. Contributed - by Luigi Ballabio. +6/07/2001: mkoeppe + Made the Makefile work with non-GNU make again. -9/30/00 : beazley - %except and %typemap directives no longer take a language specifier. - For example: +6/07/2001: cheetah (william fulton) + [Java] Class/struct members that are arrays of pointers to classes/structs - + Shadow class's get/set accessors now use Java classes instead of longs (pointers). + [Java] Shadow classes will now clean up memory if function return type + is a class/struct. + [Java] New example called reference based on the same example from other modules. - %typemap(python,in) type { ... } +6/06/2001: mkoeppe + New configure option --with-release-suffix allows for + attaching a suffix to the swig binary and the swig runtime + libraries. Minor changes to the build system. "swig + -swiglib" works again. If invoked with the new option + "-ldflags", SWIG prints a line of linker flags needed to + link with the runtime library of the selected language + module. - should be changed to +6/06/2001: mkoeppe + [Guile] gswig_list_p is an int, not a SCM. This typo + caused warnings when compiling with a Guile configured with + strict C type checking. In INPUT and BOTH typemaps + generated by the SIMPLE_MAP macro, use the SCM_TO_C + function to convert from Guile to C (rather than C_TO_SCM). + Use scm_intprint to print pointers (rather than + sprintf). Allow using "-linkage" instead of "-Linkage". - %typemap(in) type { ... } +6/05/2001: cheetah (william fulton) + [Java] Mods for using inherited c++ classes from Java + [Java] New example called class based on the same example from other modules - If it is ever necessary to include typemaps for multiple languages, - use conditional compilation instead: +6/05/2001: cheetah (william fulton) + [Java] destructor (_delete()) was not aware of %name renaming + [Java] extends baseclass did not know about %name renaming + [Java] extends baseclass did extend even when the baseclass was not known to swig + [Java] sometimes enum-declarations occured before the Java class declaration + [Java] unrelated enum initialisations no longer appear in Java class + [Java] if module ends in '_' correct JNI names are now produced - #ifdef SWIGPYTHON - %typemap(in) type { ... } - #endif - *** POTENTIAL INCOMPATIBILITY *** +6/04/2001: cheetah (william fulton) + [Java] Shadow class mods - Modified constructor replaces + newInstance(). _delete() now thread safe. getCPtr() replaces + _self. _selfClass() removed as now redundant. + *** POTENTIAL INCOMPATIBILITY FOR JAVA MODULE *** -9/30/00 : beazley - %native directive no longer applies to a single entry, but rather - defines a new scope. For example: + [Java] Not all output java files had SWIG banner. New banner. - %native { - ... bunch of native declarations ... - } - *** POTENTIAL INCOMPATIBILITY *** + [Java] Shadow class finalizers are output by default: Command + line option -finalize deprecated and replaced with -nofinalize. + *** POTENTIAL INCOMPATIBILITY FOR JAVA MODULE *** -9/30/00 : beazley - Most SWIG directives are now defined in terms of pragmas and - preprocessor macros. For example: +6/ 1/2001: mkoeppe + [Guile] Cast SCM_CAR() to scm_bits_t before shifting it. + This is required for compiling with a Guile configured with + strict C type checking. - %readonly +6/ 1/2001: mkoeppe + Added configure option "--with-swiglibdir". - is now really parsed as +5/31/2001: mkoeppe + [Guile] Support multiple parallel lists or vectors in + the typemaps provided by list-vector.i. New typemaps file, + pointer-in-out.i. - %pragma "readonly"; +5/25/2001: cheetah (william fulton) + [Java] HTML update for examples. - This scheme has been included to make the SWIG parser smaller - and more configurable. +5/28/2001: mkoeppe + Minor changes to the build system. Added subdirectory for + Debian package control files. -9/29/00 : beazley - %pragma directive syntax changed to the following: +5/28/2001: mkoeppe + [Guile] Build a runtime library, libswigguile. - %pragma(lang) name value; +5/28/2001: mkoeppe + [Guile] New typemap substitution $*descriptor. Use the {} + syntax, rather than the "" syntax for the standard + typemaps, in order to work around strange macro-expansion + behavior of the SWIG preprocessor. This introduces some + extra braces. - (The "=" is gone and it must be terminated by a semicolon). - *** POTENTIAL INCOMPATIBILITY *** +5/27/2001: mkoeppe + [Guile] Handle pointer types with typemaps, rather than + hard-coded. New typemap substitutions $descriptor, + $basedescriptor; see documentation. Some clean-up in the + variable/constants wrapper generator code. New convenience + macro SWIG_Guile_MustGetPtr, which allows getting pointers + from smobs in a functional style. New typemap file + "list-vector.i", providing macros that define typemaps for + converting between C arrays and Scheme lists and vectors. -9/29/00 : beazley - All of the old code inclusion directives %init %{ ... %}, %wrapper %{ ... %}, - %runtime %{ ... %} and so forth have been consolidated into a single SWIG - directive: +5/25/2001: cheetah (william fulton) + [Java] STL string moved into its own typemap as it is c++ code and + it break any c code using the typemaps.i file. + - Fixes for wrappers around global variables - applies to primitive + types and user types (class/struct) and pointers to these. + - Structure member variables and class public member variables getters + and setters pass a pointer to the member as was in 1.3a3 and 1.1 + (1.3a5 was passing by value) + - Parameters that were arrays and return types were incorrectly + being passed to create_function() as pointers. + - Fix for arrays of enums. + [Java] Updated java examples and added two more. + [Java] Java module updated from SWIG1.3a3 including code cleanup etc. + [Java] enum support added. + [Java] Array support implemented + [Java] Shadow classes improved - Java objects used rather than + longs holding the c pointer to the wrapped structure/c++class - %insert("section") %{ code %} +5/22/2001: mkoeppe + [Guile] Fixed extern "C" declarations in C++ mode. Thanks + to Greg Troxel . - or +5/21/2001: mkoeppe + [Guile] New linkage "module" for creating Guile modules for + Guile versions >= 1.5.0. - %insert("section") "filename" +4/18/2001: mkoeppe + [MzScheme] Added typemaps for passing through Scheme_Object + pointers. - Motivation: this design is simpler (the parser is smaller) and it is - extensible--language modules can define their own code sections for - shadow classes or whatever. +4/9/2001 : mkoeppe + [MzScheme] Added typemaps for `bool'. Inclusion of headers + and support routines is now data-driven via mzscheme.i. + Headers come from the new file mzschemdec.swg. Don't abort + immediately when a type-handling error is reported. When + searching for typemaps for enums, fall back to using int, + like the Guile backend does. Support char constants. Emit + correct wrapper code for variables. - The old SWIG directives such as %wrapper %{ ... %} are now really - defined as preprocessor macros. For example: +3/12/2001: mkoeppe + [Guile] Fixed typemaps for char **OUTPUT, char **BOTH. - #define %wrapper %insert("wrapper") +3/2/2001 : mkoeppe + [Guile] Every wrapper function now gets a boolean variable + gswig_list_p which indicates whether multiple values are + present. The macros GUILE_APPEND_RESULT, GUILE_MAYBE_VALUES + and GUILE_MAYBE_VECTOR use this variable, rather than + checking whether the current return value is a list. This + allows for typemaps returning a list as a single value (a + list was erroneously converted into a vector or a + multiple-value object in this case). -9/25/00 : beazley - Modified the preprocessor so that macro names can start with a '%'. - This may allow new SWIG "directives" to be defined as macros instead - of having to be hard-coded into the parser. More details later. - *** EXPERIMENTAL FEATURE *** +3/1/2001 : mkoeppe + [Guile] Added support for returning multiple values as + vectors, or passing them to a muliple-value + continuation. By default, multiple values still get + returned as a list. -:::: NOTE :::: All CHANGES entries newer than the 1.3a5 release refer to the new -core, new parser, and redesigned module system. +3/1/2001 : mkoeppe + [Guile] Added a "beforereturn" pragma. The value of this + pragma is inserted just before every return statement. -Version 1.3 Alpha 5 (September 22, 2000) -======================================== +3/1/2001 : mkoeppe + [Guile] Added support for Guile 1.4.1 procedure + documentation formats, see internals.html. + +2/26/2001: mkoeppe + [Guile] Made the wrapper code compile with C++ if the + "-c++" command-line switch is given. Thanks to + . + +2/26/2001: mkoeppe + [Guile] Now two type tables, swig_types and + swig_types_initial, are used, as all other SWIG language + modules do. This removes the need for the tricky + construction used before that the broken Redhat 7.0 gcc + doesn't parse. Reported by . + +2/26/2001: mkoeppe + [Guile] Fixed typemaps for char *OUTPUT, char *BOTH; a bad + free() would be emitted. Added typemap for SCM. + + +Version 1.3 Alpha 5 +=================== 9/19/00 : beazley [Python] Python module generates more efficient code for @@ -248,7 +402,7 @@ Version 1.3 Alpha 5 (September 22, 2000) 9/19/00 : beazley Fixed some problems with enum handling. enums are now manipulated as - 'int', but cast into the enum type when values are passed to the + 'int', but cast into the enum type when values are passed to the corresponding C function. 9/19/00 : mkoeppe @@ -258,11 +412,11 @@ Version 1.3 Alpha 5 (September 22, 2000) internals.html. 9/18/00 : mkoeppe - Incorporated patch #101430, fixing bugs in the Guile module: + Incorporated patch #101430, fixing bugs in the Guile module: 1. Some arguments were erroneously taken as *optional* arguments when - ignored arguments were present. + ignored arguments were present. 2. Guile 1.3.4 was not supported since functions introduced in Guile - 1.4 were used. + 1.4 were used. 3. Added handling of `const char *'. 9/17/00 : beazley @@ -273,7 +427,7 @@ Version 1.3 Alpha 5 (September 22, 2000) and function bodies. Preprocessor bug. Version 1.3 Alpha 4 (September 4, 2000) -======================================= +====================================== 9/3/00 : ttn Added instructions for maintainers in Examples/README on how @@ -572,14 +726,14 @@ Version 1.3 Alpha 4 (September 4, 2000) *** POTENTIAL INCOMPATIBILITY *** 8/15/00 : beazley - Secret developer feature. Since datatypes are now represented as + Secret developer feature. Since datatypes are now represented as strings internally, you can bypass limitations of the parser and create a wild datatype by simply enclosing the raw string encoding in backticks (``) and sticking it in the interface file anywhere a - type is expected. For example, `a(20).a(10).p.f(int,int)`. This + type is expected. For example, `a(20).a(10).p.f(int,int)`. This feature is only intended for testing (i.e., you want to see what happens to your language module if it gets a reference to a pointer - to an array of pointers to functions or something). + to an array of pointers to functions or something). *** SICK HACK *** 8/14/00 : beazley @@ -951,7 +1105,7 @@ Version 1.3 Alpha 1 (February 11, 2000) 4. Use CObjects instead of strings for pointers. - Dave: These enhancements result in speedups of up to 50% in some + Dave: This enhancements result in speedups of up to 50% in some of the preliminary tests I ran. 2/1/00 : Upgraded the Python module to use a new type-checking scheme that diff --git a/SWIG/NEW b/SWIG/NEW index 2fb195d18..760c61387 100644 --- a/SWIG/NEW +++ b/SWIG/NEW @@ -187,7 +187,7 @@ and it is simpler to implement than the old string based approach. 6. New Features --------------- -6.1 Java module added (although broken in SWIG1.3a4) +6.1 Java module added 6.2 Ruby module added diff --git a/SWIG/README b/SWIG/README index b80682b52..8f1340f70 100644 --- a/SWIG/README +++ b/SWIG/README @@ -1,53 +1,72 @@ SWIG (Simplified Wrapper and Interface Generator) -Version: 1.3 (alpha) +Version: 1.3.6 (July 9, 2001) $Header$ -Tagline: SWIG is a compiler that integrates C and C++ with scripting +Tagline: SWIG is a compiler that integrates C and C++ with languages including Perl, Python, Tcl, Guile, Mzscheme, - and Ruby. + Java and Ruby. -This distribution represents work in progress towards building a new -SWIG release. The guilty parties working on this are: +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 +replace versions 1.1p5 and 1.1-883. The guilty parties working on this +are: Dave Beazley (beazley@cs.uchicago.edu) (SWIG core) Loic Dachary (loic@ceic.com) (Perl5) - Harco de Hilster (Harco.de.Hilster@ATComputing.nl) (Java) + William Fulton (wfulton1@motorola.com) (Java) Thien-Thi Nguyen (ttn@glug.org) (Testing/Misc) Masaki Fukushima (fukusima@goto.info.waseda.ac.jp) (Ruby) Matthias Köppe (mkoeppe@mail.math.uni-magdeburg.de) (Guile/MzScheme) -Past contributors (currently incomplete): +Past contributors (see the CHANGES file for a complete list): -Dustin Mitchell, Ian Cooke, Catalin Dumitrescu, Baran Kovuk, Gary Holt, -David Fletcher, Oleg Tolmatcev. +Clark McGrew, Dustin Mitchell, Ian Cooke, Catalin Dumitrescu, Baran +Kovuk, Gary Holt, David Fletcher, Oleg Tolmatcev, Harco de Hilster. -*********************************************************************** -***** IMPORTANT NOTICE -- READ THIS NOW (OR ELSE) ***** -*********************************************************************** +Up-to-date SWIG related information can be found at -If you downloaded SWIG as a prepackaged release such as SWIG1.3a5, be -advised that this distribution represents a snapshot of the most -"stable" part of the SWIG CVS repository. As this is an unstable -release, there is a pretty good chance that a number of features are -broken or under repair. Currently, SWIG is undergoing a large -redevelopment effort in which it is being converted from C++ to ANSI C -and restructured to be more extensible. As a result, the source code -is very disorganized at the moment. The SWIG1.3 series of releases -should be viewed as transitional releases leading to the eventual -release of SWIG2.0. First-time users should probably start with -SWIG1.1p5 which is significantly more stable (and includes a wider -range of documentation and examples). + http://www.swig.org -*** WE NEED YOUR HELP! *** +What's New? +=========== +Here are the most notable changes (so far): -Please report any errors and submit patches (if possible)! Not only -are we making radical changes to the system, we only have access to a -limited variety of hardware (Linux, Solaris, and Windows). All -contributions help. + - SWIG now has a full C preprocessor. -*** Backwards Compatibility *** + - Code generation for the Tcl and Python modules has been + substantially improved both in terms of size and runtime + efficiency (Perl5 is coming along too). + + - 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. + + - Testing framework part of the distribution ("make check" support). + + - A lot of minor bug fixes and cleanup. + + - SWIG requires an ANSI C compiler. + +Here are a few missing features: + + - The SWIG1.1 documentation system is gone and hasn't been + replaced yet. This is on the long-term to-do list. + + - The Tcl7.x and Perl4 modules are deprecated and no longer + included. + + - A wide variety of old SWIG command-line options and + obscure features are gone. + + - 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 with interfaces written for SWIG1.1, SWIG1.3 incorporates a number of @@ -62,56 +81,9 @@ 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 definitely not work with this release. -What's New? -=========== -Here are the most notable changes (so far): - - - SWIG now has a full C preprocessor. - - - Code generation for the Tcl and Python modules has been - substantially improved both in terms of size and runtime - efficiency (Perl5 is coming along too). - - - Java module is now included. - - - The Guile module is stable. It represents C pointers as smobs and - supports the Guile module system and exceptions. - - - Ruby and mzscheme modules added. - - - Testing framework part of the distribution ("make check" support). - - - A lot of minor bug fixes and cleanup. - -Here are a few missing features - - - The SWIG1.1 documentation system is gone and hasn't been - replaced yet. This is on the long-term to-do list. - - - The Tcl7.x and Perl4 modules are deprecated and no longer - included. - - - A wide variety of old SWIG command-line options and - obscure features are gone. - -What's Broken? -============== - - - The Java module is broken and temporarily unavailable (SWIG1.3a4). - - - Objective C support doesn't work right now. No ETA as to - when it will return. - - - SWIG requires an ANSI C compiler. - - - A number of low-level data structures have been converted - to C. Since things haven't yet been fully tested, there's - a chance that unusual corner cases might cause SWIG to crash. - If so, please send us a debugger traceback if possible. - - - The CHANGES file describes in some detail all of the important - changes that have been made to the system. Experienced - users would be advised to read this. +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 +advised to read this. Installation ============ @@ -130,12 +102,21 @@ the following before doing the 'make install' step above. If you don't know what the runtime libraries are, don't worry about this step. -The Examples directory contains a few examples of using SWIG. +The file INSTALL details more about using configure. Also try + + % ./configure --help. + +The configure script will attempt to locate various packages on your +machine, including Tcl, Perl5, Python and other target languages that SWIG +uses. Don't panic if you get 'not found' messages--SWIG does not need these +packages to compile or run. The configure script is actually looking for +these packages so that you can try out the SWIG examples contained +in the 'Examples' directory without having to hack Makefiles. Notes: -(1) If you checked the code out via CVS, you will have to run autoconf - before typing 'configure.' In addition, a full build of SWIG requires +(1) If you checked the code out via CVS, you will have to run ./autogen.sh + before typing 'configure'. In addition, a full build of SWIG requires the use of bison. (2) If you are using Windows, the easiest way to install and build @@ -145,38 +126,36 @@ Notes: The SWIG1.1p5 distribution also contains a number of examples configured to work with Visual C++ (most of which should also work with SWIG1.3). -(3) 'make check' is a new feature that requires all 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 - incorrectly configured. It may also fail due to compiler issues - such as broken C++ compiler. Even if 'make check' fails, there is a - pretty good chance SWIG still works correctly---you will just have - to mess around with one of the examples and some makefiles first. +(3) 'make 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 + incorrectly configured. It may also fail due to compiler issues + such as broken C++ compiler. Even if 'make check' fails, there is a + pretty good chance SWIG still works correctly---you will just have + to mess around with one of the examples and some makefiles first. Examples ======== -The Examples directory contains a variety of new examples and it has some -browsable documentation. Simply point your browser to the file -"Example/index.html". +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". Documentation ============= -No documentation is currently included in this release. However, most -of the documentation for SWIG1.1 still applies. This can be obtained -on http://www.swig.org. +No user documentation is currently included in this release. However, +most of the documentation for SWIG1.1 still applies. This can be +obtained on http://www.swig.org. + +There is some technical documentation available in the Doc subdirectory. Participate! ============ -We are looking for people who want to join the effort of getting this -next release off the ground. Please send me email for details. --- Dave (beazley@cs.uchicago.edu) +Please report any errors and submit patches (if possible)! We only +have access to a limited variety of hardware (Linux, Solaris, and +Windows). All contributions help. +Contributions of new language modules will also be accepted. -Developer Information -===================== -The primary goal of future development is to make SWIG more modular, -extensible, and easier to maintain. To this end, the source code has -been consolidated and reorganized with the Source directory. For more -information, please see Doc/internals.html. + -- The SWIG Maintainers diff --git a/SWIG/TODO b/SWIG/TODO index 4f2f36932..d18bb9baf 100644 --- a/SWIG/TODO +++ b/SWIG/TODO @@ -1,27 +1,84 @@ -*- outline -*- -* for 1.3a4 release +* for release 1.3.6 -** [ttn] add test-suite based on Examples +** Testing -[open] The behavior of SWIG with respect to call/return-by-value needs - to be verified for all language modules. Previously, the +* for release 1.3.7 + +** Discuss the %pragma directive syntax change 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 changes from CVS head + +** Fix all the bugs on SourceForge + +** Incorporate all the patches on SourceForge + +** Make a proper test suite with both language-independent and language-dependent tests. + The directories Examples/guile/test-suite, Examples/perl5/pointer-cxx, Examples/C++ + contain some material that can be used. + +* eventually + +** Revive the documentation + +** Maybe use libtool rather than all the home-grown compile/link stuff + +** The behavior of SWIG with respect to call/return-by-value needs + to be verified for all language modules. Previously, the parser automatically performed the conversion of pass-by-value to pass-by-reference. Unfortunately, this confused typemap handling and other aspects of the system. I have removed this behavior. However, in doing so, the handling of user defined types is passed on to the language modules. -[open] All of the SWIG 1.1p5 examples need to be verified. Changes +** All of the SWIG 1.1p5 examples need to be verified. Changes in type handling and internal data structures may have broken a variety of things. -* for 1.3a6 release +** [Guile] New %pragma "documentation", which allows to attach documentation + strings to a procedure. -** [mkoeppe] Merge Guile and MzScheme from the "mkoeppe-1-3-a5-patches" branch +** [Guile] Maybe support keyword args -* for 1.3b1 release +** [Guile] Maybe support GOOPS shadow classes -* for 1.3b2 release +** [Guile] Support garbage collection. + +*** %new annotation decides whether a pointer smob can be gc'ed. + +*** New smob type `swig-gc'; instances created with + SWIG_Guile_MakeCollectablePtr. %new versions of the pointer + typemaps use this function rather than SWIG_Guile_MakePtr. + +*** New typemaps "destructor", "gcmarker". Their values are taken as + identifiers for functions taking one argument: a pointer to the + object to be destroyed, or whose SCM-valued subobjects are to be + marked. After creating the pointer equivalence table, we iterate + again over the remembered pointer types, emitting code that puts + the functions into our type table. No additional functions are + generated. + +*** The default for all pointer types would be: + %typemap(destructor) SWIGPOINTER * "free"; + +*** A special annotation, e.g. FREED, can be attached to the arguments + of destructor functions, so that explicitly freed structs won't be + collected by the GC again. Like this: + + %typemap(argout) SWIGPOINTER *FREED { + smob-tag($source) = swig; /* non-gc */ + smob-data($source) = NULL; + } + void free_foo(struct foo *FREED); + +** Make a tricky header file defining annotations invisible to the C compiler. + The idea is to prepare one file that serves both as a C header file + and a SWIG interface file. + + void add(SWIG_OUTPUT(int) *z, int x, int y) -* for 2.x release