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

526
SWIG/CHANGES
View file

@ -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 <ballabio@mac.com>.
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
<WYS@helbling.ch> 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
<WYS@helbling.ch>, 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 <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.
*** 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
<ljohnson@resgen.com> 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
<gdt@ir.bbn.com>.
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 <gdt@ir.bbn.com>.
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
<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
[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

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.1 Java module added (although broken in SWIG1.3a4)
6.1 Java module added
6.2 Ruby module added

191
SWIG/README
View file

@ -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

77
SWIG/TODO
View file

@ -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