jyapayne/swig
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Updated with files from release 1.3.6

Browse source 
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk@1397 626c5289-ae23-0410-ae9c-e8d60b6d4f22
This commit is contained in:
William S Fulton 2001-08-01 16:08:34 +00:00
commit e35de3c8ed
4 changed files with 493 additions and 303 deletions
Download patch file Download diff file Expand all files Collapse all files

522
SWIG/CHANGES
View file

@ -1,241 +1,395 @@
SWIG (Simplified Wrapper and Interface Generator) SWIG (Simplified Wrapper and Interface Generator)
:::: NOTE :::: The CVS head works towards release 1.4; it is currently The Stable Development Branch
unstable. The CVS branch "mkoeppe-1-3-a5-patches" =============================
starting from release 1.3a5 works towards the next
stable release (1.3.6).
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 This branch is also the basis for the "swig1.3" Debian package
Use %%except instead of %except in some format (currently unofficial, available from
strings. Reported by Ovidiu Toader, SF Bug #231923. http://www.math.uni-magdeburg.de/~mkoeppe/imo-debian).
02/03/01: beazley Eventually this branch will be merged with the development on the
Fixed some bugs related to typedef and typemaps. The following trunk of the CVS tree.
declarations are now legal:
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 7/03/2001: beazley
Integrated XML output code contributed by Klaus Wiederaenders. Fixed up the version numbers so that the release is known
This includes new directories Examples/xml and Lib/xml, and as 1.3.6. All future releases should have a similar
new files Source/Modules1.1/xml.*. Usage: swig -xml OUT foo.i version format.
which writes the foo.i parse tree to xml file OUT.
01/16/01: ttn 7/02/2001: mkoeppe
Wrote table of contents for Doc/engineering.html. Added section * [Python]: Prevent the problem of self.thisown not being
on CVS tagging conventions. Added copyright to other docs. defined if the C++ class constructor raised an exception.
Thanks to Luigi Ballabio <ballabio@mac.com>.
12/23/00: beazley 6/29/2001: mkoeppe
C++ wrappers now always include default constructors and destructors. * More portability fixes; fixed "gcc -Wall" warnings.
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 ***
12/23/00: beazley 6/29/2001: cheetah (william fulton)
Changes to class wrappers. When SWIG sees two classes like this, * GIFPlot examples: TRANSPARENT #define multiple times on Solaris
(clashes with stream.h).
class X { * 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: public:
void foo(); TestClass() {};
... TestClass(int a) {};
} ~TestClass() {};
unsigned long xyz(short k) {};
class Y : public X { unsigned long xyz(int n) {};
public: static void static_func() {};
void bar(); static void static_func(int a) {};
...
}
it now generates two wrapper functions:
X_foo(X *x) { x->foo(); }
Y_bar(Y *y) { y->bar(); }
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 ***
12/23/00: beazley
Typemaps can now be placed inside class definitions. For example:
class Foo {
public:
%typemap(in) double {
// Whatever
...
}
...
}; };
void delete_TestClass(int a);
When used in this manner, the typemap is applied to all class 6/27/2001: mkoeppe
members that follow. In addition, the typemap is inherited * [Perl] Another const-related portability fix.
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 ***
12/21/00: beazley 6/26/2001: cheetah (william fulton)
The %readonly directive is now defined as a scope. For example: * [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 ***
%readonly { 6/25/2001: mkoeppe
int foo; * Incorporated more build changes contributed by Wyss Clemens
int bar; <WYS@helbling.ch> for swig/ruby on cygwin.
}
*** INCOMPATIBILITY *** 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
12/21/00: beazley 6/20/2001: mkoeppe
The %native directive is now a scope. It works as follows: * 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
<WYS@helbling.ch>, which make swig runnable on cygwin.
%native { 6/19/2001: cheetah (william fulton)
/* List functions with native prototypes */ * [Java] Bug fix for SF bug #211144. This fix is a workaround
PyObject *blah(PyObject *args, PyObject *self); until fixed in the core.
%name(foo) PyObject *wrap_foo(PyObject *args, PyObject *self);
...
}
See note from 9/30/00 below. In addition, native function wrapping 6/19/2001: mkoeppe
has been enhanced in the Python/Tcl modules. For example, the * [Guile]: Portability fixes for use with the Sun Forte
Python module can automatically distinguish between keyword and compilers.
non-keyword wrappers. Similarly, the Tcl module can distinguish * [Tcl]: Portability fix (const char *).
between Tcl7 and Tcl8 style wrappers. * [Tcl]: Configure now first tries to find a tclConfig.sh
*** POTENTIAL INCOMPATIBILITY *** file in order to find the Tcl include directory, library
location and library name.
* [Python]: Added a few possible library locations.
12/15/00: beazley 6/18/2001: mkoeppe
SWIG now builds a complete parse tree before generating any wrapper * [Guile]: Don't call scm_c_export if nothing is to be
code. Wrappers now appear in the same order as they appear exported. Don't warn on %module if module has been set
in the interface file. In SWIG1.1, wrapping of classes was already (this frequently occurs when %import is used).
deferred until everything else had been handled.
12/15/00: beazley 6/16/2001: mkoeppe
New %scope directive defines a SWIG scope. Basically, a scope * [Guile]: New "passive" linkage, which is appropriate for
is a way of enclosing a collection of declarations that might multi-module extensions without Guile module magic.
share a common property. For example:
%scope("native") { 6/15/2001: mkoeppe
/* Native wrappers */ * [Guile]: Fixed printing of smobs (space and angle were
PyObject *blah(PyObject *args, PyObject *self); missing).
... * Properly generate type information for base classes
} imported with the %import directive. Thanks to Marcelo
Matus <mmatus@acms.arizona.edu> 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 <scharf@users.sf.net>.
* [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.
or 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.
%scope("readonly") { 6/14/2001: mkoeppe
/* Readonly variables */ * The parser now understands the (non-standard) "long long"
int x; 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.
An unnamed scope can also be used: 6/13/2001: mkoeppe
Partial merge from the CVS trunk at tag
"mkoeppe-merge-1". This covers the following changes:
%scope { | 01/16/01: ttn
... declarations ... | 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?
In addition to collecting objects, typemaps and other customization 6/13/2001: mkoeppe
features defined within a scope only get applied to those objects. * When configure does not find a language, don't use default
That is, a typemap defined in a scope will disappear at the end of paths like /usr/local/include; this only causes build
the scope. problems.
*** NEW FEATURE *** * 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...".
10/14/00: beazley 6/12/2001: mkoeppe
Fixed some problems in output file handling and shadow classes. [Guile] VECTORLENINPUT and LISTLENINPUT now have separate
Problem reported by Luigi Ballabio. 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.
10/14/00: beazley 6/12/2001: cheetah (william fulton)
Incorporated new set of patches for Macintosh support. Contributed Some Java documentation added.
by Luigi Ballabio. [Java] Fixed bugs in import pragma and shadow pragma.
9/30/00 : beazley 6/12/2001: mkoeppe
%except and %typemap directives no longer take a language specifier. Fix declarations of SWIG_define_class
For example: (Lib/ruby/rubydec.swg) and SWIG_TypeQuery
(Lib/common.swg). Thanks to Lyle Johnson
<ljohnson@resgen.com> for the patches.
%typemap(python,in) type { ... } 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.
should be changed to 6/11/2001: cheetah (william fulton)
The generic INSTALL file from autoconf added. Few changes to README file.
%typemap(in) type { ... } 6/11/2001: mkoeppe
Fixed typo in Makefile.in; thanks to Greg Troxel
<gdt@ir.bbn.com>.
If it is ever necessary to include typemaps for multiple languages, 6/08/2001: cheetah (william fulton)
use conditional compilation instead: make check works again. Examples/GIFPlot configure generated by
top level autoconf now.
#ifdef SWIGPYTHON 6/08/2001: mkoeppe
%typemap(in) type { ... } Another build change: The new script autogen.sh runs
#endif autoconf in the appropriate directories. The top-level
*** POTENTIAL INCOMPATIBILITY *** configure also configures in Examples/GIFPlot.
9/30/00 : beazley 6/07/2001: mkoeppe
%native directive no longer applies to a single entry, but rather Made the Makefile work with non-GNU make again.
defines a new scope. For example:
%native { 6/07/2001: cheetah (william fulton)
... bunch of native declarations ... [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).
*** POTENTIAL INCOMPATIBILITY *** [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.
9/30/00 : beazley 6/06/2001: mkoeppe
Most SWIG directives are now defined in terms of pragmas and New configure option --with-release-suffix allows for
preprocessor macros. For example: 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.
%readonly 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".
is now really parsed as 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
%pragma "readonly"; 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
This scheme has been included to make the SWIG parser smaller 6/04/2001: cheetah (william fulton)
and more configurable. [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/29/00 : beazley [Java] Not all output java files had SWIG banner. New banner.
%pragma directive syntax changed to the following:
%pragma(lang) name value; [Java] Shadow class finalizers are output by default: Command
line option -finalize deprecated and replaced with -nofinalize.
*** POTENTIAL INCOMPATIBILITY FOR JAVA MODULE ***
(The "=" is gone and it must be terminated by a semicolon). 6/ 1/2001: mkoeppe
*** POTENTIAL INCOMPATIBILITY *** [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.
9/29/00 : beazley 6/ 1/2001: mkoeppe
All of the old code inclusion directives %init %{ ... %}, %wrapper %{ ... %}, Added configure option "--with-swiglibdir".
%runtime %{ ... %} and so forth have been consolidated into a single SWIG
directive:
%insert("section") %{ code %} 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.
or 5/25/2001: cheetah (william fulton)
[Java] HTML update for examples.
%insert("section") "filename" 5/28/2001: mkoeppe
Minor changes to the build system. Added subdirectory for
Debian package control files.
Motivation: this design is simpler (the parser is smaller) and it is 5/28/2001: mkoeppe
extensible--language modules can define their own code sections for [Guile] Build a runtime library, libswigguile.
shadow classes or whatever.
The old SWIG directives such as %wrapper %{ ... %} are now really 5/28/2001: mkoeppe
defined as preprocessor macros. For example: [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.
#define %wrapper %insert("wrapper") 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/25/00 : beazley 5/25/2001: cheetah (william fulton)
Modified the preprocessor so that macro names can start with a '%'. [Java] STL string moved into its own typemap as it is c++ code and
This may allow new SWIG "directives" to be defined as macros instead it break any c code using the typemaps.i file.
of having to be hard-coded into the parser. More details later. - Fixes for wrappers around global variables - applies to primitive
*** EXPERIMENTAL FEATURE *** 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
:::: NOTE :::: All CHANGES entries newer than the 1.3a5 release refer to the new 5/22/2001: mkoeppe
core, new parser, and redesigned module system. [Guile] Fixed extern "C" declarations in C++ mode. Thanks
to Greg Troxel <gdt@ir.bbn.com>.
Version 1.3 Alpha 5 (September 22, 2000) 5/21/2001: mkoeppe
======================================== [Guile] New linkage "module" for creating Guile modules for
Guile versions >= 1.5.0.
4/18/2001: mkoeppe
[MzScheme] Added typemaps for passing through Scheme_Object
pointers.
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.
3/12/2001: mkoeppe
[Guile] Fixed typemaps for char **OUTPUT, char **BOTH.
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).
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.
3/1/2001 : mkoeppe
[Guile] Added a "beforereturn" pragma. The value of this
pragma is inserted just before every return statement.
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
<monkeyiq@dingoblue.net.au>.
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 <monkeyiq@dingoblue.net.au>.
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 9/19/00 : beazley
[Python] Python module generates more efficient code for [Python] Python module generates more efficient code for
@ -273,7 +427,7 @@ Version 1.3 Alpha 5 (September 22, 2000)
and function bodies. Preprocessor bug. and function bodies. Preprocessor bug.
Version 1.3 Alpha 4 (September 4, 2000) Version 1.3 Alpha 4 (September 4, 2000)
======================================= ======================================
9/3/00 : ttn 9/3/00 : ttn
Added instructions for maintainers in Examples/README on how Added instructions for maintainers in Examples/README on how
@ -951,7 +1105,7 @@ Version 1.3 Alpha 1 (February 11, 2000)
4. Use CObjects instead of strings for pointers. 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. of the preliminary tests I ran.
2/1/00 : Upgraded the Python module to use a new type-checking scheme that 2/1/00 : Upgraded the Python module to use a new type-checking scheme that

2
SWIG/NEW
View file

@ -187,7 +187,7 @@ and it is simpler to implement than the old string based approach.
6. New Features 6. New Features
--------------- ---------------
6.1 Java module added (although broken in SWIG1.3a4) 6.1 Java module added
6.2 Ruby module added 6.2 Ruby module added

179
SWIG/README
View file

@ -1,53 +1,72 @@
SWIG (Simplified Wrapper and Interface Generator) SWIG (Simplified Wrapper and Interface Generator)
Version: 1.3 (alpha) Version: 1.3.6 (July 9, 2001)
$Header$ $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, languages including Perl, Python, Tcl, Guile, Mzscheme,
and Ruby. Java and Ruby.
This distribution represents work in progress towards building a new SWIG reads annotated C/C++ header files and creates wrapper code (glue
SWIG release. The guilty parties working on this are: 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) Dave Beazley (beazley@cs.uchicago.edu) (SWIG core)
Loic Dachary (loic@ceic.com) (Perl5) 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) Thien-Thi Nguyen (ttn@glug.org) (Testing/Misc)
Masaki Fukushima (fukusima@goto.info.waseda.ac.jp) (Ruby) Masaki Fukushima (fukusima@goto.info.waseda.ac.jp) (Ruby)
Matthias Köppe (mkoeppe@mail.math.uni-magdeburg.de) (Guile/MzScheme) 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, Clark McGrew, Dustin Mitchell, Ian Cooke, Catalin Dumitrescu, Baran
David Fletcher, Oleg Tolmatcev. Kovuk, Gary Holt, David Fletcher, Oleg Tolmatcev, Harco de Hilster.
*********************************************************************** Up-to-date SWIG related information can be found at
***** IMPORTANT NOTICE -- READ THIS NOW (OR ELSE) *****
***********************************************************************
If you downloaded SWIG as a prepackaged release such as SWIG1.3a5, be http://www.swig.org
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).
*** 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 - SWIG now has a full C preprocessor.
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.
*** 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 Although we are making every attempt preserve backwards compatibility
with interfaces written for SWIG1.1, SWIG1.3 incorporates a number of 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 the C++ API level so language modules written for SWIG1.1 will most
definitely not work with this release. definitely not work with this release.
What's New? 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
Here are the most notable changes (so far): advised to read this.
- 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.
Installation 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 If you don't know what the runtime libraries are, don't worry
about this step. 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: Notes:
(1) If you checked the code out via CVS, you will have to run autoconf (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 before typing 'configure'. In addition, a full build of SWIG requires
the use of bison. the use of bison.
(2) If you are using Windows, the easiest way to install and build (2) If you are using Windows, the easiest way to install and build
@ -145,8 +126,8 @@ Notes:
The SWIG1.1p5 distribution also contains a number of examples configured 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). 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 (3) 'make check' is a new feature that requires at least one of the target
to be installed and which performs compile/link level testing 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 of the examples. If it fails, it may mean that you have an uninstalled
language module or that the file 'Examples/Makefile' has been language module or that the file 'Examples/Makefile' has been
incorrectly configured. It may also fail due to compiler issues incorrectly configured. It may also fail due to compiler issues
@ -156,27 +137,25 @@ Notes:
Examples Examples
======== ========
The Examples directory contains a variety of new examples and it has some The Examples directory contains a variety of examples of using SWIG
browsable documentation. Simply point your browser to the file and it has some browsable documentation. Simply point your browser to
"Example/index.html". the file "Example/index.html".
Documentation Documentation
============= =============
No documentation is currently included in this release. However, most No user documentation is currently included in this release. However,
of the documentation for SWIG1.1 still applies. This can be obtained most of the documentation for SWIG1.1 still applies. This can be
on http://www.swig.org. obtained on http://www.swig.org.
There is some technical documentation available in the Doc subdirectory.
Participate! 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 SWIG Maintainers
=====================
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.

75
SWIG/TODO
View file

@ -1,10 +1,34 @@
-*- outline -*- -*- 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 * 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 to be verified for all language modules. Previously, the
parser automatically performed the conversion of pass-by-value parser automatically performed the conversion of pass-by-value
to pass-by-reference. Unfortunately, this confused typemap to pass-by-reference. Unfortunately, this confused typemap
@ -12,16 +36,49 @@
this behavior. However, in doing so, the handling of user this behavior. However, in doing so, the handling of user
defined types is passed on to the language modules. 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 in type handling and internal data structures may have broken
a variety of things. 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