merge revisions 11243-11872 from trunk to gsoc2009-matevz
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/branches/gsoc2009-matevz@12162 626c5289-ae23-0410-ae9c-e8d60b6d4f22
This commit is contained in:
William S Fulton
commit
ab1cd03979
387 changed files with 12359 additions and 4388 deletions
|
|
@ -37,7 +37,6 @@ $(PACKAGE_NAME).1: ccache.yo
|
|||
-yodl2man -o $(PACKAGE_NAME).1 ccache.yo
|
||||
|
||||
web/ccache-man.html: ccache.yo
|
||||
mkdir -p man
|
||||
yodl2html -o web/ccache-man.html ccache.yo
|
||||
|
||||
install: $(PACKAGE_NAME)$(EXEEXT) $(PACKAGE_NAME).1
|
||||
|
|
@ -53,7 +52,7 @@ uninstall: $(PACKAGE_NAME)$(EXEEXT) $(PACKAGE_NAME).1
|
|||
clean:
|
||||
/bin/rm -f $(OBJS) *~ $(PACKAGE_NAME)$(EXEEXT)
|
||||
|
||||
clean-docs:
|
||||
distclean-docs:
|
||||
rm -f $(PACKAGE_NAME).1 web/ccache-man.html
|
||||
|
||||
check : test
|
||||
|
|
@ -63,9 +62,12 @@ test: test.sh
|
|||
|
||||
check: test
|
||||
|
||||
distclean: clean
|
||||
/bin/rm -f Makefile config.h config.sub config.log build-stamp config.status configure config.h
|
||||
distclean: clean distclean-docs
|
||||
/bin/rm -f Makefile config.h config.sub config.log build-stamp config.status config.h.in ccache_swig_config.h
|
||||
|
||||
maintainer-clean: distclean
|
||||
/bin/rm -f configure
|
||||
|
||||
# FIXME: To fix this, test.sh needs to be able to take ccache from the
|
||||
# installed prefix, not from the source dir.
|
||||
installcheck:
|
||||
|
|
|
|||
258
CHANGES
258
CHANGES
|
|
@ -2,6 +2,264 @@ SWIG (Simplified Wrapper and Interface Generator)
|
|||
|
||||
See CHANGES.current for current version.
|
||||
|
||||
Version 1.3.40 (18 August 2009)
|
||||
===============================
|
||||
|
||||
2009-08-17: olly
|
||||
[Perl] Add "#undef do_exec" to our clean up of Perl global
|
||||
namespace pollution.
|
||||
|
||||
2009-08-17: olly
|
||||
[PHP] Fix to wrap a resource returned by __get() in a PHP object (SF#2549217).
|
||||
|
||||
2009-08-17: wsfulton
|
||||
Fix #2797485 After doing a 'make clean', install fails if yodl2man or yodl2html
|
||||
is not available.
|
||||
|
||||
2009-08-16: wsfulton
|
||||
[Octave] Caught exceptions display the type of the C++ exception instead of the
|
||||
generic "c++-side threw an exception" message.
|
||||
|
||||
2009-08-16: wsfulton
|
||||
[Java] When %catches is used, fix so that any classes specified in the "throws"
|
||||
attribute of the "throws" typemap are generated into the Java method's throws clause.
|
||||
|
||||
2009-08-16: wsfulton
|
||||
[C#] Fix exception handling when %catches is used, reported by Juan Manuel Alvarez.
|
||||
|
||||
2009-08-15: wsfulton
|
||||
Fix %template seg fault on some cases of overloading the templated method.
|
||||
Bug reported by Jan Kupec.
|
||||
|
||||
2009-08-15: wsfulton
|
||||
[Ruby] Add numerous missing wrapped methods for std::vector<bool> specialization
|
||||
as reported by Youssef Jones.
|
||||
|
||||
2009-08-14: wsfulton
|
||||
[Perl] Add SWIG_ConvertPtrAndOwn() method into the runtime for smart pointer
|
||||
memory ownership control. shared_ptr support still to be added. Patch from
|
||||
David Fletcher.
|
||||
|
||||
2009-08-14: olly
|
||||
[PHP] PHP5 now wraps static member variables as documented.
|
||||
|
||||
2009-08-14: olly
|
||||
[PHP] Update the PHP "class" example to work with PHP5 and use
|
||||
modern wrapping features.
|
||||
|
||||
2009-08-13: wsfulton
|
||||
[PHP] std::vector wrappers overhaul. They no longer require the
|
||||
specialize_std_vector() macro. Added wrappers for capacity() and reserve().
|
||||
|
||||
2009-08-13: wsfulton
|
||||
[PHP] Add const reference typemaps. const reference primitive types are
|
||||
now passed by value rather than pointer like the other target languages.
|
||||
Fixes SF#2524029.
|
||||
|
||||
2009-08-08: wsfulton
|
||||
[Python] More user friendly AttributeError is raised when there are
|
||||
no constructors generated for the proxy class in the event that the
|
||||
class is abstract - the error message is now
|
||||
"No constructor defined - class is abstract" whereas if there are no
|
||||
public constructors for any other reason and the class is not abstract,
|
||||
the message remains
|
||||
"No constructor defined".
|
||||
[tcl] Similarly for tcl when using -itcl.
|
||||
|
||||
2009-08-04: olly
|
||||
[PHP] Fix generated code to work with PHP 5.3.
|
||||
|
||||
2009-08-04: vmiklos
|
||||
[PHP] Various mathematical functions (which would conflict
|
||||
with the built-in PHP ones) are now automatically handled by
|
||||
adding a 'c_' prefix.
|
||||
|
||||
2009-08-03: wsfulton
|
||||
[C#] The std::vector<T> implementation is improved and now uses $typemap such
|
||||
that the proxy class for T no longer has to be specified in some macros
|
||||
for correct C# compilation; the following macros are deprecated, where
|
||||
CSTYPE was the C# type for the C++ class CTYPE:
|
||||
|
||||
SWIG_STD_VECTOR_SPECIALIZE_MINIMUM(CSTYPE, CTYPE)
|
||||
usage should be removed altogether
|
||||
|
||||
SWIG_STD_VECTOR_SPECIALIZE(CSTYPE, CTYPE)
|
||||
should be replaced with:
|
||||
SWIG_STD_VECTOR_ENHANCED(CTYPE)
|
||||
|
||||
Some more details in csharp/std_vector.i
|
||||
|
||||
*** POTENTIAL INCOMPATIBILITY ***
|
||||
|
||||
2009-07-31: olly
|
||||
[Python] Fix indentation so that we give a useful error if the
|
||||
module can't be loaded. Patch from Gaetan Lehmann in SF#2829853.
|
||||
|
||||
2009-07-29: wsfulton
|
||||
Add $typemap(method, typelist) special variable macro. This allows
|
||||
the contents of a typemap to be inserted within another typemap.
|
||||
Fully documented in Typemaps.html.
|
||||
|
||||
2009-07-29: vmiklos
|
||||
[PHP] Static member variables are now prefixed with the
|
||||
class name. This allows static member variables with the
|
||||
same name in different classes.
|
||||
|
||||
2009-07-29: olly
|
||||
[Python] Add missing locks to std::map wrappers. Patch from
|
||||
Paul Hampson in SF#2813836.
|
||||
|
||||
2009-07-29: olly
|
||||
[PHP] Fix memory leak in PHP OUTPUT typemaps. Reported by Hitoshi
|
||||
Amano in SF#2826322.
|
||||
|
||||
2009-07-29: olly
|
||||
[PHP] Fix memory leak in PHP resource destructor for classes
|
||||
without a destructor and non-class types. Patch from Hitoshi Amano
|
||||
in SF#2825303.
|
||||
|
||||
2009-07-28: olly
|
||||
[PHP] Update warnings about clashes between identifiers and PHP
|
||||
keywords and automatic renaming to work with the PHP5 class
|
||||
wrappers. Fixes SF#1613679.
|
||||
|
||||
2009-07-28: vmiklos
|
||||
[PHP] If a member function is not public but it has a base
|
||||
which is public, then now a warning is issued and the member
|
||||
function will be public, as PHP requires this.
|
||||
|
||||
2009-07-21: vmiklos
|
||||
[PHP] Director support added.
|
||||
|
||||
2009-07-15: olly
|
||||
[Perl] Don't specify Perl prototype "()" for a constructor with a
|
||||
different name to the class, as such constructors can still take
|
||||
parameters.
|
||||
|
||||
2009-07-12: xavier98
|
||||
[Octave] Add support for Octave 3.2 API
|
||||
|
||||
2009-07-05: olly
|
||||
[PHP] Update the list of PHP keywords - "cfunction" is no longer a
|
||||
keyword in PHP5 and PHP 5.3 added "goto", "namespace", "__DIR__",
|
||||
and "__NAMESPACE__".
|
||||
|
||||
2009-07-03: olly
|
||||
[Tcl] To complement USE_TCL_STUBS, add support for USE_TK_STUBS
|
||||
and SWIG_TCL_STUBS_VERSION. Document all three in the Tcl chapter
|
||||
of the manual. Based on patch from SF#2810380 by Christian
|
||||
Gollwitzer.
|
||||
|
||||
2009-07-02: vmiklos
|
||||
[PHP] Added factory.i for PHP, see the li_factory testcase
|
||||
for more info on how to use it.
|
||||
|
||||
2009-07-02: wsfulton
|
||||
Fix -Wallkw option as reported by Solomon Gibbs.
|
||||
|
||||
2009-07-02: wsfulton
|
||||
Fix syntax error when a nested struct contains a comment containing a * followed
|
||||
eventually by a /. Regression from 1.3.37, reported by Solomon Gibbs.
|
||||
|
||||
2009-07-01: vmiklos
|
||||
[PHP] Unknown properties are no longer ignored in proxy
|
||||
classes.
|
||||
|
||||
2009-07-01: vmiklos
|
||||
[PHP] Fixed %newobject behaviour, previously any method
|
||||
marked with %newobject was handled as a constructor.
|
||||
|
||||
2009-06-30: olly
|
||||
[Ruby] Undefine close and connect macros defined by Ruby API
|
||||
headers as we don't need them and they can clash with C++ methods
|
||||
being wrapped. Patch from Vit Ondruch in SF#2814430.
|
||||
|
||||
2009-06-26: olly
|
||||
[Ruby] Fix to handle FIXNUM values greater than MAXINT passed for a
|
||||
double parameter.
|
||||
|
||||
2009-06-24: wsfulton
|
||||
Fix wrapping methods with default arguments and the compactdefaultargs feature
|
||||
where a class is passed by value and is assigned a default value. The SwigValueWrapper
|
||||
template workaround for a missing default constructor is no longer used as the code
|
||||
generated does not call the default constructor.
|
||||
|
||||
2009-06-16: wsfulton
|
||||
[Java,C#] Fix enum marshalling when %ignore is used on one of the enum items.
|
||||
Incorrect enum values were being passed to the C++ layer or compilation errors resulted.
|
||||
|
||||
2009-06-02: talby
|
||||
[Perl] Resolved reference.i overload support problem
|
||||
identified by John Potowsky.
|
||||
|
||||
2009-05-26: wsfulton
|
||||
[C#] Improved std::map wrappers based on patch from Yuval Baror. The C# proxy
|
||||
now implements System.Collections.Generic.IDictionary<>.
|
||||
|
||||
These std:map wrappers have a non-backwards compatible overhaul to make them
|
||||
like a .NET IDictionary. Some method names have changed as following:
|
||||
set -> setitem (use this[] property now)
|
||||
get -> getitem (use this[] property now)
|
||||
has_key -> ContainsKey
|
||||
del -> Remove
|
||||
clear -> Clear
|
||||
|
||||
The following macros used for std::map wrappers are deprecated and will no longer work:
|
||||
specialize_std_map_on_key
|
||||
specialize_std_map_on_value
|
||||
specialize_std_map_on_both
|
||||
|
||||
*** POTENTIAL INCOMPATIBILITY ***
|
||||
|
||||
2009-05-20: vmiklos
|
||||
[PHP] Add the 'thisown' member to classes. The usage of it
|
||||
is the same as the Python thisown one: it's 1 by default and
|
||||
you can set it to 0 if you want to prevent freeing it. (For
|
||||
example to prevent a double free.)
|
||||
|
||||
2009-05-14: bhy
|
||||
[Python] Fix the wrong pointer value returned by SwigPyObject_repr().
|
||||
|
||||
2009-05-13: mutandiz (Mikel Bancroft)
|
||||
[allegrocl] Minor tweak when wrapping in -nocwrap mode.
|
||||
|
||||
2009-05-11: wsfulton
|
||||
[C#] Improved std::vector wrappers on the C# proxy side from Yuval Baror. These
|
||||
implement IList<> instead of IEnumerable<> where possible.
|
||||
|
||||
2009-04-29: wsfulton
|
||||
[Java, C#] Add the 'notderived' attribute to the javabase and csbase typemaps.
|
||||
When this attribute is set, the typemap will not apply to classes that are derived
|
||||
from a C++ base class, eg
|
||||
%typemap(csbase, notderived="1") SWIGTYPE "CommonBase"
|
||||
|
||||
2009-04-29: olly
|
||||
[Python] Don't attempt to acquire the GIL in situations where we
|
||||
know that it will already be locked. This avoids some dead-locks
|
||||
with mod_python (due to mod_python bugs which are apparently
|
||||
unlikely to ever be fixed), and results in smaller wrappers which
|
||||
run a little faster (in tests with Xapian on x86-64 Ubuntu 9.04,
|
||||
the stripped wrapper library was 11% smaller and ran 2.7% faster).
|
||||
|
||||
2009-04-21: wsfulton
|
||||
[C#] Fix #2753469 - bool &OUTPUT and bool *OUTPUT typemaps initialisation.
|
||||
|
||||
2009-04-09: wsfulton
|
||||
Fix #2746858 - C macro expression using floating point numbers
|
||||
|
||||
2009-03-30: olly
|
||||
[PHP] The default out typemap for char[ANY] now returns the string up to a
|
||||
zero byte, or the end of the array if there is no zero byte. This
|
||||
is the same as Python does, and seems more generally useful than
|
||||
the previous behaviour of returning the whole contents of the array
|
||||
including any zero bytes. If you want the old behaviour, you can provide
|
||||
your own typemap to do this:
|
||||
|
||||
%typemap(out) char [ANY]
|
||||
%{
|
||||
RETVAL_STRINGL($1, $1_dim0, 1);
|
||||
%}
|
||||
|
||||
Version 1.3.39 (21 March 2009)
|
||||
==============================
|
||||
|
||||
|
|
|
|||
405
CHANGES.current
405
CHANGES.current
|
|
@ -1,64 +1,371 @@
|
|||
Version 1.3.40 (in progress)
|
||||
Version 1.3.41 (in progress)
|
||||
============================
|
||||
|
||||
2009-05-26: wsfulton
|
||||
[C#] Improved std::map wrappers based on patch from Yuval Baror. The C# proxy
|
||||
now implements System.Collections.Generic.IDictionary<>.
|
||||
2010-02-27: wsfulton
|
||||
[Python] Remove -dirvtable from the optimizations included by -O as it this option
|
||||
currently leads to memory leaks as reported by Johan Blake.
|
||||
|
||||
These std:map wrappers have a non-backwards compatible overhaul to make them
|
||||
like a .NET IDictionary. Some method names have changed as following:
|
||||
set -> setitem (use this[] property now)
|
||||
get -> getitem (use this[] property now)
|
||||
has_key -> ContainsKey
|
||||
del -> Remove
|
||||
clear -> Clear
|
||||
2010-02-13: wsfulton
|
||||
[Ruby] A few fixes for compiling under ruby-1.9.x including patch from 'Nibble'.
|
||||
|
||||
The following macros used for std::map wrappers are deprecated and will no longer work:
|
||||
specialize_std_map_on_key
|
||||
specialize_std_map_on_value
|
||||
specialize_std_map_on_both
|
||||
2010-02-13: wsfulton
|
||||
[Ruby] Apply patch from Patrick Bennett to fix RARRAY_LEN and RARRAY_PTR usage for Ruby 1.9.x
|
||||
used in various STL wrappers.
|
||||
|
||||
2010-02-13: wsfulton
|
||||
[C#, Java] Fix incorrect multiply defined symbol name error when an enum item
|
||||
and class name have the same name, as reported by Nathan Krieger. Example:
|
||||
|
||||
class Vector {};
|
||||
namespace Text {
|
||||
enum Preference { Vector };
|
||||
}
|
||||
|
||||
This also fixes other incorrect corner case target language symbol name clashes.
|
||||
|
||||
2010-02-11: wsfulton
|
||||
Add the -debug-lsymbols option for displaying the target language layer symbols.
|
||||
|
||||
2010-02-09: wsfulton
|
||||
Fix -MM and -MMD options on Windows. They were not omitting files in the SWIG library as
|
||||
they should be.
|
||||
|
||||
2010-02-08: wsfulton
|
||||
Fix #1807329 - When Makefile dependencies are being generated using the -M family of options
|
||||
on Windows, the file paths have been corrected to use single backslashes rather than double
|
||||
backslashes as path separators.
|
||||
|
||||
2010-02-06: wsfulton
|
||||
Fix #2918902 - language specific files not being generated in correct directory on
|
||||
Windows when using forward slashes for -o, for example:
|
||||
swig -python -c++ -o subdirectory/theinterface_wrap.cpp subdirectory/theinterface.i
|
||||
|
||||
2010-02-05: wsfulton
|
||||
Fix #2894405 - assertion when using -xmlout.
|
||||
|
||||
2010-01-28: wsfulton
|
||||
Fix typemap matching bug when a templated type has a typemap both specialized and not
|
||||
specialized. For example:
|
||||
|
||||
template<typename T> struct XX { ... };
|
||||
%typemap(in) const XX & "..."
|
||||
%typemap(in) const XX< int > & "..."
|
||||
|
||||
resulted in the 2nd typemap being applied for all T in XX< T >.
|
||||
|
||||
2010-01-22: wsfulton
|
||||
Fix #2933129 - typemaps not being found when the unary scope operator (::) is used to denote
|
||||
global scope, the typemap is now used in situations like this:
|
||||
|
||||
struct X {};
|
||||
%typemap(in) const X & "..."
|
||||
void m(const ::X &);
|
||||
|
||||
and this:
|
||||
|
||||
struct X {};
|
||||
%typemap(in) const ::X & "..."
|
||||
void m(const X &);
|
||||
|
||||
2010-01-20: wsfulton
|
||||
Fix some unary scope operator (::) denoting global scope problems in the types generated
|
||||
into the C++ layer. Previously the unary scope operator was dropped in the generated code
|
||||
if the type had any sort of qualifier, for example when using pointers, references, like
|
||||
::foo*, ::foo&, bar< ::foo* >.
|
||||
|
||||
2010-01-13: olly
|
||||
[PHP] Add datetime to the list of PHP predefined classes (patch
|
||||
from David Fletcher in SF#2931042).
|
||||
|
||||
2010-01-11: wsfulton
|
||||
Slight change to warning, error and diagnostic reporting. The warning number is no
|
||||
longer shown within brackets. This is to help default parsing of warning messages by
|
||||
other tools, vim on Unix in particular.
|
||||
|
||||
Example original display using -Fstandard:
|
||||
example.i:20: Warning(401): Nothing known about base class 'B'. Ignored.
|
||||
New display:
|
||||
example.i:20: Warning 401: Nothing known about base class 'B'. Ignored.
|
||||
|
||||
Also subtle fix to -Fmicrosoft format adding in missing space. Example original display:
|
||||
example.i(20): Warning(401): Nothing known about base class 'Base'. Ignored.
|
||||
New display:
|
||||
example.i(20) : Warning 401: Nothing known about base class 'Base'. Ignored.
|
||||
|
||||
2010-01-10: wsfulton
|
||||
Fix a few inconsistencies in reporting of file/line numberings including modifying
|
||||
the overload warnings 509, 512, 516, 474, 475 to now be two line warnings.
|
||||
|
||||
2010-01-10: wsfulton
|
||||
Modify -debug-tags output to use standard file name/line reporting so that editors
|
||||
can easily navigate to the appropriate lines.
|
||||
Was typically:
|
||||
. top . include . include (/usr/share/swig/temp/trunk/Lib/swig.swg:312)
|
||||
. top . include . include . include (/usr/share/swig/temp/trunk/Lib/swigwarnings.swg:39)
|
||||
now:
|
||||
/usr/share/swig/temp/trunk/Lib/swig.swg:312: . top . include . include
|
||||
/usr/share/swig/temp/trunk/Lib/swigwarnings.swg:39: . top . include . include . include
|
||||
|
||||
2010-01-03: wsfulton
|
||||
Fix missing file/line numbers for typemap warnings and in output from the
|
||||
-debug-tmsearch/-debug-tmused options.
|
||||
|
||||
2010-01-03: wsfulton
|
||||
Add typemaps used debugging option (-debug-tmused). When used each line displays
|
||||
the typemap used for each type for which code is being generated including the file
|
||||
and line number related to the type. This is effectively a condensed form of the
|
||||
-debug-tmsearch option. Documented in Typemaps.html.
|
||||
|
||||
2009-12-23: wsfulton
|
||||
Fix for %javaexception and directors so that all the appropriate throws clauses
|
||||
are generated. Problem reported by Peter Greenwood.
|
||||
|
||||
2009-12-20: wsfulton
|
||||
Add -debug-tmsearch option for debugging the typemap pattern matching rules.
|
||||
Documented in Typemaps.html.
|
||||
|
||||
2009-12-12: wsfulton
|
||||
[Octave] Remove the -api option and use the new OCTAVE_API_VERSION_NUMBER
|
||||
macro provided in the octave headers for determining the api version instead.
|
||||
|
||||
2009-12-04: olly
|
||||
[Ruby] Improve support for Ruby 1.9 under GCC. Addresses part of
|
||||
SF#2859614.
|
||||
|
||||
2009-12-04: olly
|
||||
Fix handling of modulo operator (%) in constant expressions
|
||||
(SF#2818562).
|
||||
|
||||
2009-12-04: olly
|
||||
[PHP] "empty" is a reserved word in PHP, so rename empty() method
|
||||
on STL classes to "is_empty()" (previously this was automatically
|
||||
renamed to "c_empty()").
|
||||
*** POTENTIAL INCOMPATIBILITY ***
|
||||
|
||||
2009-12-03: olly
|
||||
[PHP] Add typemaps for long long and unsigned long long, and for
|
||||
pointer to method.
|
||||
|
||||
2009-12-02: olly
|
||||
[PHP] Fix warning and rename of reserved class name to be case
|
||||
insensitive.
|
||||
|
||||
2009-12-01: wsfulton
|
||||
Revert support for %extend and memberin typemaps added in swig-1.3.39. The
|
||||
memberin typemaps are ignored again for member variables within a %extend block.
|
||||
Documentation inconsistency reported by Torsten Landschoff.
|
||||
|
||||
2009-11-29: wsfulton
|
||||
[Java, C#] Fix generated quoting when using %javaconst(1)/%csconst(1) for
|
||||
static const char member variables.
|
||||
|
||||
%javaconst(1) A;
|
||||
%csconst(1) A;
|
||||
struct X {
|
||||
static const char A = 'A';
|
||||
};
|
||||
|
||||
2009-11-26: wsfulton
|
||||
[Java, C#] Fix %javaconst(1)/%csconst(1) for static const member variables to
|
||||
use the actual constant value if it is specified, rather than the C++ code to
|
||||
access the member.
|
||||
|
||||
%javaconst(1) EN;
|
||||
%csconst(1) EN;
|
||||
struct X {
|
||||
static const int EN = 2;
|
||||
};
|
||||
|
||||
2009-11-23: wsfulton
|
||||
C++ nested typedef classes can now be handled too, for example:
|
||||
struct Outer {
|
||||
typedef Foo { } FooTypedef1, FooTypedef2;
|
||||
};
|
||||
|
||||
2009-11-18: wsfulton
|
||||
The wrappers for C nested structs are now generated in the same order as declared
|
||||
in the parsed code.
|
||||
|
||||
2009-11-18: wsfulton
|
||||
Fix #491476 - multiple declarations of nested structs, for example:
|
||||
struct Outer {
|
||||
struct {
|
||||
int val;
|
||||
} inner1, inner2, *inner3, inner4[1];
|
||||
} outer;
|
||||
|
||||
2009-11-17: wsfulton
|
||||
Fix parsing of enum declaration and initialization, for example:
|
||||
|
||||
enum ABC {
|
||||
a,
|
||||
b,
|
||||
c
|
||||
} A = a, *pC = &C, array[3] = {a, b, c};
|
||||
|
||||
2009-11-17: wsfulton
|
||||
Fix parsing of struct declaration and initialization, for example:
|
||||
|
||||
struct S {
|
||||
int x;
|
||||
} instance = { 10 };
|
||||
|
||||
2009-11-15: wsfulton
|
||||
Fix #1960977 - Syntax error parsing derived nested class declaration and member
|
||||
variable instance.
|
||||
|
||||
2009-11-14: wsfulton
|
||||
Fix #2310483 - function pointer typedef within extern "C" block.
|
||||
|
||||
2009-11-13: wsfulton
|
||||
Fix usage of nested template classes within templated classes so that compileable code
|
||||
is generated.
|
||||
|
||||
2009-11-13: olly
|
||||
[php] Fix place where class prefix (as specified with -prefix)
|
||||
wasn't being used. Patch from gverbruggen in SF#2892647.
|
||||
|
||||
2009-11-12: wsfulton
|
||||
Fix usage of nested template classes so that compileable code is generated - the nested
|
||||
template class is now treated like a normal nested classes, that is, as an opaque type
|
||||
unless the nestedworkaround feature is used.
|
||||
|
||||
2009-11-12: wsfulton
|
||||
Replace SWIGWARN_PARSE_NESTED_CLASS with SWIGWARN_PARSE_NAMED_NESTED_CLASS and
|
||||
SWIGWARN_PARSE_UNNAMED_NESTED_CLASS for named and unnamed nested classes respectively.
|
||||
|
||||
Named nested class ignored warnings can now be suppressed by name using %warnfilter, eg:
|
||||
|
||||
%warnfilter(SWIGWARN_PARSE_NAMED_NESTED_CLASS) Outer::Inner;
|
||||
|
||||
but clearly unnamed nested classes cannot and the global suppression is still required, eg:
|
||||
|
||||
#pragma SWIG nowarn=SWIGWARN_PARSE_UNNAMED_NESTED_CLASS
|
||||
|
||||
2009-11-11: wsfulton
|
||||
Added the nestedworkaround feature as a way to use the full functionality of a nested class
|
||||
(C++ mode only). It removes the nested class from SWIG's type information so it is as if SWIG
|
||||
had never parsed the nested class. The documented nested class workarounds using a global
|
||||
fake class stopped working when SWIG treated the nested class as an opaque pointer, and
|
||||
this feature reverts this behaviour. The documentation has been updated with details of how
|
||||
to use and implement it, see the "Nested classes" section in SWIGPlus.html.
|
||||
|
||||
2009-11-11: wsfulton
|
||||
There were a number of C++ cases where nested classes/structs/unions were being handled
|
||||
as if C code was being parsed which would oftentimes lead to uncompileable code as an
|
||||
attempt was made to wrap the nested structs like it is documented for C code. Now all
|
||||
nested structs/classes/unions are ignored in C++ mode, as was always documented. However,
|
||||
there is an improvement as usage of nested structs/classes/unions is now always treated
|
||||
as an opaque type by default, resulting in generated code that should always compile.
|
||||
|
||||
*** POTENTIAL INCOMPATIBILITY ***
|
||||
|
||||
2009-05-14: bhy
|
||||
[Python] Fix the wrong pointer value returned by SwigPyObject_repr().
|
||||
2009-11-09: drjoe
|
||||
Fix R for -fcompact and add std_map.i
|
||||
|
||||
2009-05-13: mutandiz (Mikel Bancroft)
|
||||
[allegrocl] Minor tweak when wrapping in -nocwrap mode.
|
||||
2009-11-08: wsfulton
|
||||
Fix inconsistency for nested structs/unions/classes. Uncompileable code was being
|
||||
generated when inner struct and union declarations were used as types within the
|
||||
inner struct. The inner struct/union is now treated as a forward declaration making the
|
||||
behaviour the same as an inner class. (C++ code), eg:
|
||||
|
||||
2009-05-11: wsfulton
|
||||
[C#] Improved std::vector wrappers on the C# proxy side from Yuval Baror. These
|
||||
implement IList<> instead of IEnumerable<> where possible.
|
||||
struct Outer {
|
||||
struct InnerStruct { int x; };
|
||||
InnerStruct* getInnerStruct();
|
||||
};
|
||||
|
||||
2009-04-29: wsfulton
|
||||
[Java, C#] Add the 'notderived' attribute to the javabase and csbase typemaps.
|
||||
When this attribute is set, the typemap will not apply to classes that are derived
|
||||
from a C++ base class, eg
|
||||
%typemap(csbase, notderived="1") SWIGTYPE "CommonBase"
|
||||
2009-11-08: wsfulton
|
||||
Ignored nested class/struct warnings now display the name of the ignored class/struct.
|
||||
|
||||
2009-04-29: olly
|
||||
[Python] Don't attempt to acquire the GIL in situations where we
|
||||
know that it will already be locked. This avoids some dead-locks
|
||||
with mod_python (due to mod_python bugs which are apparently
|
||||
unlikely to ever be fixed), and results in smaller wrappers which
|
||||
run a little faster (in tests with Xapian on x86-64 Ubuntu 9.04,
|
||||
the stripped wrapper library was 11% smaller and ran 2.7% faster).
|
||||
2009-11-07: wsfulton
|
||||
Bug #1514681 - Fix nested template classes within a namespace generated uncompileable
|
||||
code and introduced strange side effects to other wrapper code especially code
|
||||
after the nested template class. Note that nested template classes are still ignored.
|
||||
|
||||
2009-04-21: wsfulton
|
||||
[C#] Fix #2753469 - bool &OUTPUT and bool *OUTPUT typemaps initialisation.
|
||||
2009-11-07: wsfulton
|
||||
Add new debug options:
|
||||
-debug-symtabs - Display symbol tables information
|
||||
-debug-symbols - Display target language symbols in the symbol tables
|
||||
-debug-csymbols - Display C symbols in the symbol tables
|
||||
|
||||
2009-04-09: wsfulton
|
||||
Fix #2746858 - C macro expression using floating point numbers
|
||||
2009-11-03: wsfulton
|
||||
Fix some usage of unary scope operator (::) denoting global scope, for example:
|
||||
|
||||
2009-03-30: olly
|
||||
[PHP] The default out typemap for char[ANY] now returns the string up to a
|
||||
zero byte, or the end of the array if there is no zero byte. This
|
||||
is the same as Python does, and seems more generally useful than
|
||||
the previous behaviour of returning the whole contents of the array
|
||||
including any zero bytes. If you want the old behaviour, you can provide
|
||||
your own typemap to do this:
|
||||
namespace AA { /* ... */ }
|
||||
using namespace ::AA;
|
||||
|
||||
and bug #1816802 - SwigValueWrapper should be used:
|
||||
|
||||
struct CC {
|
||||
CC(int); // no default constructor
|
||||
};
|
||||
::CC x();
|
||||
|
||||
and in template parameter specializations:
|
||||
|
||||
struct S {};
|
||||
template <typename T> struct X { void a() {}; };
|
||||
template <> struct X<S> { void b() {}; };
|
||||
%template(MyTConcrete) X< ::S >;
|
||||
|
||||
plus probably some other corner case usage of ::.
|
||||
|
||||
2009-11-02: olly
|
||||
[Python] Fix potential memory leak in initialisation code for the
|
||||
generated module.
|
||||
|
||||
2009-10-23: wsfulton
|
||||
Fix seg fault when using a named nested template instantiation using %template(name)
|
||||
within a class. A warning that these are not supported is now issued plus processing
|
||||
continues as if no name was given.
|
||||
|
||||
2009-10-20: wsfulton
|
||||
[Python] Fix std::vector<const T*>. This would previously compile, but not run correctly.
|
||||
|
||||
2009-10-20: wsfulton
|
||||
Fixed previously fairly poor template partial specialization and explicit
|
||||
specialization support. Numerous bugs in this area have been fixed including:
|
||||
|
||||
- Template argument deduction implemented for template type arguments, eg this now
|
||||
works:
|
||||
template<typename T> class X {};
|
||||
template<typename T> class X<T *> {};
|
||||
%template(X1) X<const int *>; // Chooses T * specialization
|
||||
|
||||
and more complex cases with multiple parameters and a mix of template argument
|
||||
deduction and explicitly specialised parameters, eg:
|
||||
template <typename T1, typename T2> struct TwoParm { void a() {} };
|
||||
template <typename T1> struct TwoParm<T1 *, int *> { void e() {} };
|
||||
%template(E) TwoParm<int **, int *>;
|
||||
|
||||
Note that the primary template must now be in scope, like in C++, when
|
||||
an explicit or partial specialization is instantiated with %template.
|
||||
|
||||
*** POTENTIAL INCOMPATIBILITY ***
|
||||
|
||||
2009-09-14: wsfulton
|
||||
[C#] Add %csattributes for adding C# attributes to enum values, see docs for example.
|
||||
|
||||
2009-09-11: wsfulton
|
||||
Fix memmove regression in cdata.i as reported by Adriaan Renting.
|
||||
|
||||
2009-09-07: wsfulton
|
||||
Fix constant expressions containing <= or >=.
|
||||
|
||||
2009-09-02: wsfulton
|
||||
The following operators in constant expressions now result in type bool for C++
|
||||
wrappers and remain as type int for C wrappers, as per each standard:
|
||||
|
||||
&& || == != < > <= >= (Actually the last 4 are still broken). For example:
|
||||
|
||||
#define A 10
|
||||
#define B 10
|
||||
#define A_EQ_B A == B // now wrapped as type bool for C++
|
||||
#define A_AND_B A && B // now wrapped as type bool for C++
|
||||
|
||||
2009-09-02: wsfulton
|
||||
Fix #2845746. true and false are now recognised keywords (only when wrapping C++).
|
||||
Constants such as the following are now wrapped (as type bool):
|
||||
#define FOO true
|
||||
#define BAR FOO && false
|
||||
|
||||
%typemap(out) char [ANY]
|
||||
%{
|
||||
RETVAL_STRINGL($1, $1_dim0, 1);
|
||||
%}
|
||||
|
|
|
|||
|
|
@ -1070,31 +1070,35 @@ With each is the cast that can be used in the debugger to extract the underlying
|
|||
<p>
|
||||
<li>String *s;</li>
|
||||
<br>
|
||||
(String *)((DohBase *)s)->data
|
||||
(struct String *)((DohBase *)s)->data
|
||||
<br>
|
||||
The underlying char * string can be displayed with
|
||||
<br>
|
||||
((String *)((DohBase *)s)->data)->str
|
||||
(*(struct String *)(((DohBase *)s)->data)).str
|
||||
|
||||
<p>
|
||||
<li>SwigType *t;</li>
|
||||
<br>
|
||||
(String *)((DohBase *)t)->data
|
||||
(struct String *)((DohBase *)t)->data
|
||||
<br>
|
||||
The underlying char * string can be displayed with
|
||||
<br>
|
||||
((String *)((DohBase *)t)->data)->str
|
||||
(*(struct String *)(((DohBase *)t)->data)).str
|
||||
|
||||
<p>
|
||||
<li>String_or_char *sc;</li>
|
||||
<li>const_String_or_char_ptr sc;</li>
|
||||
Either <br>
|
||||
((String *)((DohBase *)sc)->data)->str
|
||||
(*(struct String *)(((DohBase *)sc)->data)).str
|
||||
<br> or <br>
|
||||
(char *)sc
|
||||
<br> will work depending on whether the underlying type is really a String * or char *.
|
||||
|
||||
</ul>
|
||||
|
||||
<p>
|
||||
Please also read the Debugging Functions section in <a href="tree.html">SWIG Parse Tree Handling</a> for the <tt>Swig_print_node()</tt>, <tt>Swig_print_tree()</tt> and <tt>Swig_print_tags()</tt> functions for displaying node contents. It is often easier to place a few calls to these functions in code of interest and recompile than use the debugger.
|
||||
</p>
|
||||
|
||||
<hr>
|
||||
Copyright (C) 1999-2004 SWIG Development Team.
|
||||
|
||||
|
|
|
|||
|
|
@ -218,10 +218,10 @@ The following functions are used to help debug SWIG parse trees.
|
|||
<blockquote>
|
||||
Prints the tag-structure of the parse tree to standard output. <tt>node</tt> is the top-level parse tree node. <tt>prefix</tt> is
|
||||
a string prefix thats added to the start of each line. Normally, you would specify the empty string or NIL for <tt>prefix</tt>.
|
||||
This function is called by the <tt>-dump_tags</tt> option to SWIG.
|
||||
This function is called by the <tt>-debug-tags</tt> option to SWIG.
|
||||
|
||||
<pre>
|
||||
% swig -dump_tags -python example.i
|
||||
% swig -debug-tags -python example.i
|
||||
. top (:1)
|
||||
. top . include (/Users/beazley/Projects/share/swig/1.3.31/swig.swg:0)
|
||||
. top . include . include (/Users/beazley/Projects/share/swig/1.3.31/swigwarnings.swg:0)
|
||||
|
|
@ -243,7 +243,7 @@ Since many language modules include hundreds of typemaps and other information,
|
|||
|
||||
<blockquote>
|
||||
Prints the contents of a parse tree node, including all children, to standard output. The output includes all attributes
|
||||
and other details. The command line option <tt>-dump_tree</tt> produces output generated by this function.
|
||||
and other details.
|
||||
</blockquote>
|
||||
|
||||
<p>
|
||||
|
|
@ -251,8 +251,8 @@ and other details. The command line option <tt>-dump_tree</tt> produces output
|
|||
|
||||
<blockquote>
|
||||
Prints the same output as <tt>Swig_print_node()</tt> except that it also processes all of the siblings of <tt>node</tt>. This can
|
||||
be used to dump the entire parse tree to standard output. Use the command line option <tt>-dump_tree</tt> to get
|
||||
the output of this function for a SWIG input file.
|
||||
be used to dump the entire parse tree to standard output. The command line options <tt>-debug-module</tt>
|
||||
and <tt>-debug-top</tt> use this function to display the parse tree for a SWIG input file.
|
||||
</blockquote>
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -14,7 +14,7 @@
|
|||
<ul>
|
||||
<li><a href="#Allegrocl_nn2">Basics</a>
|
||||
<ul>
|
||||
<li><a href="#Allegrocl_nn3">Running Swig</a>
|
||||
<li><a href="#Allegrocl_nn3">Running SWIG</a>
|
||||
<li><a href="#Allegrocl_nn4">Command Line Options</a>
|
||||
<li><a href="#Allegrocl_nn5">Inserting user code into generated files</a>
|
||||
</ul>
|
||||
|
|
@ -138,7 +138,7 @@ to it.
|
|||
<H2><a name="Allegrocl_nn2"></a>17.1 Basics</H2>
|
||||
|
||||
|
||||
<H3><a name="Allegrocl_nn3"></a>17.1.1 Running Swig</H3>
|
||||
<H3><a name="Allegrocl_nn3"></a>17.1.1 Running SWIG</H3>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
|
|||
|
|
@ -30,8 +30,6 @@
|
|||
|
||||
|
||||
|
||||
<b>Disclaimer: This chapter is under construction.</b>
|
||||
|
||||
<p>
|
||||
In Chapter 3, SWIG's treatment of basic datatypes and pointers was
|
||||
described. In particular, primitive types such as <tt>int</tt> and
|
||||
|
|
@ -351,7 +349,7 @@ function like this in an interface file :</p>
|
|||
|
||||
<div class="code"><pre>
|
||||
%module example
|
||||
%include typemaps.i
|
||||
%include "typemaps.i"
|
||||
...
|
||||
%{
|
||||
extern void negate(double *);
|
||||
|
|
|
|||
|
|
@ -55,7 +55,7 @@ The PInvoke interface has been chosen over Microsoft's Managed C++ interface as
|
|||
PInvoke is part of the ECMA/ISO C# specification.
|
||||
It is also better suited for robust production environments due to the Managed C++ flaw called the
|
||||
<a href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dv_vstechart/html/vcconMixedDLLLoadingProblem.asp">Mixed DLL Loading Problem</a>.
|
||||
Swig C# works equally well on non-Microsoft operating systems such as Linux, Solaris and Apple Mac using
|
||||
SWIG C# works equally well on non-Microsoft operating systems such as Linux, Solaris and Apple Mac using
|
||||
<a href="http://www.mono-project.com/">Mono</a> and <a href="http://www.dotgnu.org/pnet.html">Portable.NET</a>.
|
||||
</p>
|
||||
|
||||
|
|
@ -99,6 +99,7 @@ namespace com.bloggs.widget {
|
|||
...
|
||||
}
|
||||
</pre></div>
|
||||
Note that by default, the generated C# classes have no namespace and the module name is unrelated to namespaces. The module name is just like in Java and is merely used to name some of the generated classes.
|
||||
</li>
|
||||
|
||||
<li>
|
||||
|
|
@ -131,7 +132,7 @@ If it was used, it would generate an illegal runtime initialisation via a PInvok
|
|||
C# doesn't support the notion of throws clauses.
|
||||
Therefore there is no 'throws' typemap attribute support for adding exception classes to a throws clause.
|
||||
Likewise there is no need for an equivalent to <tt>%javaexception</tt>.
|
||||
In fact, throwing C# exceptions works quite differently, see <a href="CSharp.html#csharp_exceptions">C# Exceptions></a> below.
|
||||
In fact, throwing C# exceptions works quite differently, see <a href="CSharp.html#csharp_exceptions">C# Exceptions</a> below.
|
||||
</li>
|
||||
|
||||
<li>
|
||||
|
|
@ -248,7 +249,9 @@ public static extern IntPtr function(string jarg1);
|
|||
<p>
|
||||
Support for type attributes.
|
||||
The 'imtype' and 'cstype' typemaps can have an optional <tt>inattributes</tt> and <tt>outattributes</tt> typemap attribute.
|
||||
There are C# attributes and typemap attributes, don't get confused!!
|
||||
The 'imtype' typemap can also have an optional <tt>directorinattributes</tt> and <tt>directoroutattributes</tt>
|
||||
typemap attribute which attaches to director delegates, an implementation detail of directors, see <a href="#csharp_directors_implementation">directors implementation</a>.
|
||||
Note that there are C# attributes and typemap attributes, don't get confused between the two!!
|
||||
The C# attributes specified in these typemap attributes are generated wherever the type is used in the C# wrappers.
|
||||
These can be used to specify any C# attribute associated with a C/C++ type, but are more typically used for the C# <tt>MarshalAs</tt> attribute.
|
||||
For example:
|
||||
|
|
@ -292,11 +295,16 @@ These attributes are associated with the C/C++ parameter type or return type, wh
|
|||
the attribute features and typemaps covered next.
|
||||
Note that all these different C# attributes can be combined so that a method has more than one attribute.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The <tt>directorinattributes</tt> and <tt>directoroutattributes</tt> typemap attribute are attached to the delegates in the director class, for example, the SwigDelegateBase_0
|
||||
</p>
|
||||
|
||||
</li>
|
||||
|
||||
<li>
|
||||
<p>
|
||||
Support for attaching C# attributes to wrapped methods and variables.
|
||||
Support for attaching C# attributes to wrapped methods, variables and enum values.
|
||||
This is done using the <tt>%csattributes</tt> feature, see <a href="Customization.html#features">%feature directives</a>.
|
||||
Note that C# attributes are attached to proxy classes and enums using the <tt>csattributes</tt> typemap.
|
||||
For example, imagine we have a custom attribute class, <tt>ThreadSafeAttribute</tt>, for labelling thread safety.
|
||||
|
|
@ -343,6 +351,38 @@ they can be added using the 'csvarin' and 'csvarout' typemaps respectively.
|
|||
Note that the type used for the property is specified in the 'cstype' typemap.
|
||||
If the 'out' attribute exists in this typemap, then the type used is from the 'out' attribute.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
An example for attaching attributes to the enum and enum values is shown below.
|
||||
</p>
|
||||
|
||||
<div class="code">
|
||||
<pre>
|
||||
%typemap(csattributes) Couleur "[System.ComponentModel.Description(\"Colours\")]"
|
||||
%csattributes Rouge "[System.ComponentModel.Description(\"Red\")]"
|
||||
%csattributes Vert "[System.ComponentModel.Description(\"Green\")]"
|
||||
%inline %{
|
||||
enum Couleur { Rouge, Orange, Vert };
|
||||
%}
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
<p>
|
||||
which will result in the following C# enum:
|
||||
</p>
|
||||
|
||||
<div class="code">
|
||||
<pre>
|
||||
[System.ComponentModel.Description("Colours")]
|
||||
public enum Couleur {
|
||||
[System.ComponentModel.Description("Red")]
|
||||
Rouge,
|
||||
Orange,
|
||||
[System.ComponentModel.Description("Green")]
|
||||
Vert
|
||||
}
|
||||
</pre>
|
||||
</div>
|
||||
</li>
|
||||
|
||||
<li>
|
||||
|
|
@ -947,7 +987,7 @@ without setting the <tt>canthrow</tt> attribute you will get a warning message s
|
|||
|
||||
<div class="code">
|
||||
<pre>
|
||||
example.i:21: Warning(845): Unmanaged code contains a call to a SWIG_CSharpSetPendingException
|
||||
example.i:21: Warning 845: Unmanaged code contains a call to a SWIG_CSharpSetPendingException
|
||||
method and C# code does not handle pending exceptions via the canthrow attribute.
|
||||
</pre>
|
||||
</div>
|
||||
|
|
|
|||
|
|
@ -337,25 +337,31 @@
|
|||
</ul>
|
||||
<li><a href="Typemaps.html#Typemaps_nn10">Typemap specifications</a>
|
||||
<ul>
|
||||
<li><a href="Typemaps.html#Typemaps_nn11">Defining a typemap</a>
|
||||
<li><a href="Typemaps.html#Typemaps_defining">Defining a typemap</a>
|
||||
<li><a href="Typemaps.html#Typemaps_nn12">Typemap scope</a>
|
||||
<li><a href="Typemaps.html#Typemaps_nn13">Copying a typemap</a>
|
||||
<li><a href="Typemaps.html#Typemaps_nn14">Deleting a typemap</a>
|
||||
<li><a href="Typemaps.html#Typemaps_nn15">Placement of typemaps</a>
|
||||
</ul>
|
||||
<li><a href="Typemaps.html#Typemaps_nn16">Pattern matching rules</a>
|
||||
<li><a href="Typemaps.html#Typemaps_pattern_matching">Pattern matching rules</a>
|
||||
<ul>
|
||||
<li><a href="Typemaps.html#Typemaps_nn17">Basic matching rules</a>
|
||||
<li><a href="Typemaps.html#Typemaps_nn18">Typedef reductions</a>
|
||||
<li><a href="Typemaps.html#Typemaps_typedef_reductions">Typedef reductions</a>
|
||||
<li><a href="Typemaps.html#Typemaps_nn19">Default typemaps</a>
|
||||
<li><a href="Typemaps.html#Typemaps_mixed_default">Mixed default typemaps</a>
|
||||
<li><a href="Typemaps.html#Typemaps_nn20">Multi-arguments typemaps</a>
|
||||
<li><a href="Typemaps.html#Typemaps_debugging_search">Debugging typemap pattern matching</a>
|
||||
</ul>
|
||||
<li><a href="Typemaps.html#Typemaps_nn21">Code generation rules</a>
|
||||
<ul>
|
||||
<li><a href="Typemaps.html#Typemaps_nn22">Scope</a>
|
||||
<li><a href="Typemaps.html#Typemaps_nn23">Declaring new local variables</a>
|
||||
<li><a href="Typemaps.html#Typemaps_special_variables">Special variables</a>
|
||||
<li><a href="Typemaps.html#Typemaps_special_variable_macros">Special variable macros</a>
|
||||
<ul>
|
||||
<li><a href="Typemaps.html#Typemaps_special_macro_descriptor">$descriptor(type)</a>
|
||||
<li><a href="Typemaps.html#Typemaps_special_macro_typemap">$typemap(method, typepattern)</a>
|
||||
</ul>
|
||||
</ul>
|
||||
<li><a href="Typemaps.html#Typemaps_nn25">Common typemap methods</a>
|
||||
<ul>
|
||||
|
|
@ -378,13 +384,13 @@
|
|||
<li><a href="Typemaps.html#Typemaps_nn40">Typemaps for arrays</a>
|
||||
<li><a href="Typemaps.html#Typemaps_nn41">Implementing constraints with typemaps</a>
|
||||
</ul>
|
||||
<li><a href="Typemaps.html#Typemaps_nn43">Typemaps for multiple languages</a>
|
||||
<li><a href="Typemaps.html#Typemaps_nn43">Typemaps for multiple target languages</a>
|
||||
<li><a href="Typemaps.html#Typemaps_optimal">Optimal code generation when returning by value</a>
|
||||
<li><a href="Typemaps.html#Typemaps_multi_argument_typemaps">Multi-argument typemaps</a>
|
||||
<li><a href="Typemaps.html#runtime_type_checker">The run-time type checker</a>
|
||||
<ul>
|
||||
<li><a href="Typemaps.html#Typemaps_nn45">Implementation</a>
|
||||
<li><a href="Typemaps.html#Typemaps_nn46">Usage</a>
|
||||
<li><a href="Typemaps.html#Typemaps_runtime_type_checker_usage">Usage</a>
|
||||
</ul>
|
||||
<li><a href="Typemaps.html#Typemaps_overloading">Typemaps and overloading</a>
|
||||
<li><a href="Typemaps.html#Typemaps_nn48">More about <tt>%apply</tt> and <tt>%clear</tt></a>
|
||||
|
|
@ -488,6 +494,7 @@
|
|||
<!-- INDEX -->
|
||||
<div class="sectiontoc">
|
||||
<ul>
|
||||
<li><a href="Modules.html#Modules_introduction">Modules Introduction</a>
|
||||
<li><a href="Modules.html#Modules_nn1">Basics</a>
|
||||
<li><a href="Modules.html#Modules_nn2">The SWIG runtime code</a>
|
||||
<li><a href="Modules.html#external_run_time">External access to the runtime</a>
|
||||
|
|
@ -531,7 +538,7 @@
|
|||
<ul>
|
||||
<li><a href="Allegrocl.html#Allegrocl_nn2">Basics</a>
|
||||
<ul>
|
||||
<li><a href="Allegrocl.html#Allegrocl_nn3">Running Swig</a>
|
||||
<li><a href="Allegrocl.html#Allegrocl_nn3">Running SWIG</a>
|
||||
<li><a href="Allegrocl.html#Allegrocl_nn4">Command Line Options</a>
|
||||
<li><a href="Allegrocl.html#Allegrocl_nn5">Inserting user code into generated files</a>
|
||||
</ul>
|
||||
|
|
@ -1114,7 +1121,7 @@
|
|||
<li><a href="Perl5.html#Perl5_nn24">Modules and packages</a>
|
||||
</ul>
|
||||
<li><a href="Perl5.html#Perl5_nn25">Input and output parameters</a>
|
||||
<li><a href="Perl5.html#Perl5_nn26">Exception handling </a>
|
||||
<li><a href="Perl5.html#Perl5_nn26">Exception handling</a>
|
||||
<li><a href="Perl5.html#Perl5_nn27">Remapping datatypes with typemaps</a>
|
||||
<ul>
|
||||
<li><a href="Perl5.html#Perl5_nn28">A simple typemap example</a>
|
||||
|
|
@ -1124,8 +1131,8 @@
|
|||
</ul>
|
||||
<li><a href="Perl5.html#Perl5_nn32">Typemap Examples</a>
|
||||
<ul>
|
||||
<li><a href="Perl5.html#Perl5_nn33">Converting a Perl5 array to a char ** </a>
|
||||
<li><a href="Perl5.html#Perl5_nn34">Return values </a>
|
||||
<li><a href="Perl5.html#Perl5_nn33">Converting a Perl5 array to a char **</a>
|
||||
<li><a href="Perl5.html#Perl5_nn34">Return values</a>
|
||||
<li><a href="Perl5.html#Perl5_nn35">Returning values from arguments</a>
|
||||
<li><a href="Perl5.html#Perl5_nn36">Accessing array structure members</a>
|
||||
<li><a href="Perl5.html#Perl5_nn37">Turning Perl references into C pointers</a>
|
||||
|
|
@ -1172,6 +1179,16 @@
|
|||
</ul>
|
||||
<li><a href="Php.html#Php_nn2_7">PHP Pragmas, Startup and Shutdown code</a>
|
||||
</ul>
|
||||
<li><a href="Php.html#Php_nn3">Cross language polymorphism</a>
|
||||
<ul>
|
||||
<li><a href="Php.html#Php_nn3_1">Enabling directors</a>
|
||||
<li><a href="Php.html#Php_nn3_2">Director classes</a>
|
||||
<li><a href="Php.html#Php_nn3_3">Ownership and object destruction</a>
|
||||
<li><a href="Php.html#Php_nn3_4">Exception unrolling</a>
|
||||
<li><a href="Php.html#Php_nn3_5">Overhead and code bloat</a>
|
||||
<li><a href="Php.html#Php_nn3_6">Typemaps</a>
|
||||
<li><a href="Php.html#Php_nn3_7">Miscellaneous</a>
|
||||
</ul>
|
||||
</ul>
|
||||
</div>
|
||||
<!-- INDEX -->
|
||||
|
|
@ -1264,9 +1281,6 @@
|
|||
<li><a href="Python.html#Python_nn47">Simple pointers</a>
|
||||
<li><a href="Python.html#Python_nn48">Unbounded C Arrays</a>
|
||||
<li><a href="Python.html#Python_nn49">String handling</a>
|
||||
<li><a href="Python.html#Python_nn50">Arrays</a>
|
||||
<li><a href="Python.html#Python_nn51">String arrays</a>
|
||||
<li><a href="Python.html#Python_nn52">STL wrappers</a>
|
||||
</ul>
|
||||
<li><a href="Python.html#Python_nn53">Typemaps</a>
|
||||
<ul>
|
||||
|
|
@ -1501,6 +1515,7 @@
|
|||
<ul>
|
||||
<li><a href="Tcl.html#Tcl_nn45">Proxy classes</a>
|
||||
</ul>
|
||||
<li><a href="Tcl.html#Tcl_nn46">Tcl/Tk Stubs</a>
|
||||
</ul>
|
||||
</div>
|
||||
<!-- INDEX -->
|
||||
|
|
@ -1564,7 +1579,7 @@
|
|||
<li><a href="Extending.html#Extending_nn31">Writing a Language Module</a>
|
||||
<ul>
|
||||
<li><a href="Extending.html#Extending_nn32">Execution model</a>
|
||||
<li><a href="Extending.html#Extending_nn33">Starting out</a>
|
||||
<li><a href="Extending.html#Extending_starting_out">Starting out</a>
|
||||
<li><a href="Extending.html#Extending_nn34">Command line options</a>
|
||||
<li><a href="Extending.html#Extending_nn35">Configuration and preprocessing</a>
|
||||
<li><a href="Extending.html#Extending_nn36">Entry point to code generation</a>
|
||||
|
|
@ -1573,16 +1588,18 @@
|
|||
<li><a href="Extending.html#Extending_nn39">Configuration files</a>
|
||||
<li><a href="Extending.html#Extending_nn40">Runtime support</a>
|
||||
<li><a href="Extending.html#Extending_nn41">Standard library files</a>
|
||||
<li><a href="Extending.html#Extending_nn42">Examples and test cases</a>
|
||||
<li><a href="Extending.html#Extending_nn42">User examples</a>
|
||||
<li><a href="Extending.html#Extending_test_suite">Test driven development and the test-suite</a>
|
||||
<ul>
|
||||
<li><a href="Extending.html#Extending_running_test_suite">Running the test-suite</a>
|
||||
</ul>
|
||||
<li><a href="Extending.html#Extending_nn43">Documentation</a>
|
||||
<li><a href="Extending.html#Extending_prerequisites">Prerequisites for adding a new language module to the SWIG distribution</a>
|
||||
<li><a href="Extending.html#Extending_coding_style_guidelines">Coding style guidelines</a>
|
||||
</ul>
|
||||
<li><a href="Extending.html#Extending_nn44">Typemaps</a>
|
||||
<ul>
|
||||
<li><a href="Extending.html#Extending_nn45">Proxy classes</a>
|
||||
</ul>
|
||||
<li><a href="Extending.html#Extending_debugging_options">Debugging Options</a>
|
||||
<li><a href="Extending.html#Extending_nn46">Guide to parse tree nodes</a>
|
||||
<li><a href="Extending.html#Extending_further_info">Further Development Information</a>
|
||||
</ul>
|
||||
</div>
|
||||
<!-- INDEX -->
|
||||
|
|
|
|||
|
|
@ -53,6 +53,21 @@ The <tt>%exception</tt> directive allows you to define a general purpose excepti
|
|||
handler. For example, you can specify the following:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
%exception {
|
||||
try {
|
||||
$action
|
||||
}
|
||||
catch (RangeError) {
|
||||
... handle error ...
|
||||
}
|
||||
}
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
How the exception is handled depends on the target language, for example, Python:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
%exception {
|
||||
try {
|
||||
|
|
@ -60,7 +75,7 @@ handler. For example, you can specify the following:
|
|||
}
|
||||
catch (RangeError) {
|
||||
PyErr_SetString(PyExc_IndexError,"index out-of-bounds");
|
||||
return NULL;
|
||||
SWIG_fail;
|
||||
}
|
||||
}
|
||||
</pre></div>
|
||||
|
|
|
|||
|
|
@ -48,7 +48,7 @@
|
|||
<li><a href="#Extending_nn31">Writing a Language Module</a>
|
||||
<ul>
|
||||
<li><a href="#Extending_nn32">Execution model</a>
|
||||
<li><a href="#Extending_nn33">Starting out</a>
|
||||
<li><a href="#Extending_starting_out">Starting out</a>
|
||||
<li><a href="#Extending_nn34">Command line options</a>
|
||||
<li><a href="#Extending_nn35">Configuration and preprocessing</a>
|
||||
<li><a href="#Extending_nn36">Entry point to code generation</a>
|
||||
|
|
@ -57,16 +57,18 @@
|
|||
<li><a href="#Extending_nn39">Configuration files</a>
|
||||
<li><a href="#Extending_nn40">Runtime support</a>
|
||||
<li><a href="#Extending_nn41">Standard library files</a>
|
||||
<li><a href="#Extending_nn42">Examples and test cases</a>
|
||||
<li><a href="#Extending_nn42">User examples</a>
|
||||
<li><a href="#Extending_test_suite">Test driven development and the test-suite</a>
|
||||
<ul>
|
||||
<li><a href="#Extending_running_test_suite">Running the test-suite</a>
|
||||
</ul>
|
||||
<li><a href="#Extending_nn43">Documentation</a>
|
||||
<li><a href="#Extending_prerequisites">Prerequisites for adding a new language module to the SWIG distribution</a>
|
||||
<li><a href="#Extending_coding_style_guidelines">Coding style guidelines</a>
|
||||
</ul>
|
||||
<li><a href="#Extending_nn44">Typemaps</a>
|
||||
<ul>
|
||||
<li><a href="#Extending_nn45">Proxy classes</a>
|
||||
</ul>
|
||||
<li><a href="#Extending_debugging_options">Debugging Options</a>
|
||||
<li><a href="#Extending_nn46">Guide to parse tree nodes</a>
|
||||
<li><a href="#Extending_further_info">Further Development Information</a>
|
||||
</ul>
|
||||
</div>
|
||||
<!-- INDEX -->
|
||||
|
|
@ -1025,7 +1027,7 @@ Deletes <tt>s</tt>.
|
|||
</div>
|
||||
|
||||
<p>
|
||||
<b><tt>int Len(String_or_char *s)</tt></b>
|
||||
<b><tt>int Len(const String_or_char *s)</tt></b>
|
||||
</p>
|
||||
|
||||
<div class="indent">
|
||||
|
|
@ -1033,7 +1035,7 @@ Returns the length of the string.
|
|||
</div>
|
||||
|
||||
<p>
|
||||
<b><tt>char *Char(String_or_char *s)</tt></b>
|
||||
<b><tt>char *Char(const String_or_char *s)</tt></b>
|
||||
</p>
|
||||
|
||||
<div class="indent">
|
||||
|
|
@ -1041,7 +1043,7 @@ Returns a pointer to the first character in a string.
|
|||
</div>
|
||||
|
||||
<p>
|
||||
<b><tt>void Append(String *s, String_or_char *t)</tt></b>
|
||||
<b><tt>void Append(String *s, const String_or_char *t)</tt></b>
|
||||
</p>
|
||||
|
||||
<div class="indent">
|
||||
|
|
@ -1049,7 +1051,7 @@ Appends <tt>t</tt> to the end of string <tt>s</tt>.
|
|||
</div>
|
||||
|
||||
<p>
|
||||
<b><tt>void Insert(String *s, int pos, String_or_char *t)</tt></b>
|
||||
<b><tt>void Insert(String *s, int pos, const String_or_char *t)</tt></b>
|
||||
</p>
|
||||
|
||||
<div class="indent">
|
||||
|
|
@ -1162,7 +1164,7 @@ Returns the number of items in <tt>h</tt>.
|
|||
</div>
|
||||
|
||||
<p>
|
||||
<b><tt>Object *Getattr(Hash *h, String_or_char *key)</tt></b>
|
||||
<b><tt>Object *Getattr(Hash *h, const String_or_char *key)</tt></b>
|
||||
</p>
|
||||
|
||||
<div class="indent">
|
||||
|
|
@ -1171,7 +1173,7 @@ a simple <tt>char *</tt> string. Returns NULL if not found.
|
|||
</div>
|
||||
|
||||
<p>
|
||||
<b><tt>int Setattr(Hash *h, String_or_char *key, Object_or_char *val)</tt></b>
|
||||
<b><tt>int Setattr(Hash *h, const String_or_char *key, const Object_or_char *val)</tt></b>
|
||||
</p>
|
||||
|
||||
<div class="indent">
|
||||
|
|
@ -1185,7 +1187,7 @@ of <tt>val</tt>. Returns 1 if this operation replaced an existing hash entry,
|
|||
</div>
|
||||
|
||||
<p>
|
||||
<b><tt>int Delattr(Hash *h, String_or_char *key)</tt></b>
|
||||
<b><tt>int Delattr(Hash *h, const String_or_char *key)</tt></b>
|
||||
</p>
|
||||
|
||||
<div class="indent">
|
||||
|
|
@ -1249,7 +1251,7 @@ negative, the first item is returned.
|
|||
</div>
|
||||
|
||||
<p>
|
||||
<b><tt>int *Setitem(List *x, int n, Object_or_char *val)</tt></b>
|
||||
<b><tt>int *Setitem(List *x, int n, const Object_or_char *val)</tt></b>
|
||||
</p>
|
||||
|
||||
<div class="indent">
|
||||
|
|
@ -1271,7 +1273,7 @@ for <tt>n</tt>.
|
|||
</div>
|
||||
|
||||
<p>
|
||||
<b><tt>void Append(List *x, Object_or_char *t)</tt></b>
|
||||
<b><tt>void Append(List *x, const Object_or_char *t)</tt></b>
|
||||
</p>
|
||||
|
||||
<div class="indent">
|
||||
|
|
@ -1281,7 +1283,7 @@ used to create a String object.
|
|||
</div>
|
||||
|
||||
<p>
|
||||
<b><tt>void Insert(String *s, int pos, Object_or_char *t)</tt></b>
|
||||
<b><tt>void Insert(String *s, int pos, const Object_or_char *t)</tt></b>
|
||||
</p>
|
||||
|
||||
<div class="indent">
|
||||
|
|
@ -1479,13 +1481,14 @@ Same as the C <tt>tell()</tt> function.
|
|||
</div>
|
||||
|
||||
<p>
|
||||
<b><tt>File *NewFile(const char *filename, const char *mode)</tt></b>
|
||||
<b><tt>File *NewFile(const char *filename, const char *mode, List *newfiles)</tt></b>
|
||||
</p>
|
||||
|
||||
<div class="indent">
|
||||
Create a File object using the <tt>fopen()</tt> library call. This
|
||||
file differs from <tt>FILE *</tt> in that it can be placed in the standard
|
||||
SWIG containers (lists, hashes, etc.).
|
||||
SWIG containers (lists, hashes, etc.). The <tt>filename</tt> is added to the
|
||||
<tt>newfiles</tt> list if <tt>newfiles</tt> is non-zero and the file was created successfully.
|
||||
</div>
|
||||
|
||||
<p>
|
||||
|
|
@ -1922,7 +1925,7 @@ Adds a reference to <tt>ty</tt>.
|
|||
</div>
|
||||
|
||||
<p>
|
||||
<b><tt>void SwigType_add_array(SwigType *ty, String_or_char *dim)</tt></b>
|
||||
<b><tt>void SwigType_add_array(SwigType *ty, const String_or_char *size)</tt></b>
|
||||
</p>
|
||||
|
||||
<div class="indent">
|
||||
|
|
@ -1962,7 +1965,7 @@ Sets <tt>n</tt>th array dimensions of <tt>ty</tt> to <tt>rep</tt>.
|
|||
</div>
|
||||
|
||||
<p>
|
||||
<b><tt>void SwigType_add_qualifier(SwigType *ty, String_or_char *q)</tt></b>
|
||||
<b><tt>void SwigType_add_qualifier(SwigType *ty, const String_or_char *q)</tt></b>
|
||||
</p>
|
||||
|
||||
<div class="indent">
|
||||
|
|
@ -1971,7 +1974,7 @@ Adds a type qualifier <tt>q</tt> to <tt>ty</tt>. <tt>q</tt> is typically
|
|||
</div>
|
||||
|
||||
<p>
|
||||
<b><tt>void SwigType_add_memberpointer(SwigType *ty, String_or_char *cls)</tt></b>
|
||||
<b><tt>void SwigType_add_memberpointer(SwigType *ty, const String_or_char *cls)</tt></b>
|
||||
</p>
|
||||
|
||||
<div class="indent">
|
||||
|
|
@ -2292,7 +2295,7 @@ The following functions produce strings that are suitable for output.
|
|||
</p>
|
||||
|
||||
<p>
|
||||
<b><tt>String *SwigType_str(SwigType *ty, String_or_char *id = 0)</tt></b>
|
||||
<b><tt>String *SwigType_str(SwigType *ty, const String_or_char *id = 0)</tt></b>
|
||||
</p>
|
||||
|
||||
<div class="indent">
|
||||
|
|
@ -2303,7 +2306,7 @@ used to convert string-encoded types back into a form that is valid C syntax.
|
|||
</div>
|
||||
|
||||
<p>
|
||||
<b><tt>String *SwigType_lstr(SwigType *ty, String_or_char *id = 0)</tt></b>
|
||||
<b><tt>String *SwigType_lstr(SwigType *ty, const String_or_char *id = 0)</tt></b>
|
||||
</p>
|
||||
|
||||
<div class="indent">
|
||||
|
|
@ -2312,7 +2315,7 @@ is generated from the type's lvalue (as generated from SwigType_ltype).
|
|||
</div>
|
||||
|
||||
<p>
|
||||
<b><tt>String *SwigType_lcaststr(SwigType *ty, String_or_char *id = 0)</tt></b>
|
||||
<b><tt>String *SwigType_lcaststr(SwigType *ty, const String_or_char *id = 0)</tt></b>
|
||||
</p>
|
||||
|
||||
<div class="indent">
|
||||
|
|
@ -2323,7 +2326,7 @@ this function produces the string "<tt>(char *) foo</tt>".
|
|||
</div>
|
||||
|
||||
<p>
|
||||
<b><tt>String *SwigType_rcaststr(SwigType *ty, String_or_char *id = 0)</tt></b>
|
||||
<b><tt>String *SwigType_rcaststr(SwigType *ty, const String_or_char *id = 0)</tt></b>
|
||||
</p>
|
||||
|
||||
<div class="indent">
|
||||
|
|
@ -2470,7 +2473,7 @@ the parsing of command line options, all aspects of code generation are controll
|
|||
different methods of the <tt>Language</tt> that must be defined by your module.
|
||||
</p>
|
||||
|
||||
<H3><a name="Extending_nn33"></a>35.10.2 Starting out</H3>
|
||||
<H3><a name="Extending_starting_out"></a>35.10.2 Starting out</H3>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -2601,24 +2604,24 @@ void Language::main(int argc, char *argv[]) {
|
|||
} else {
|
||||
Swig_arg_error();
|
||||
}
|
||||
} else if (strcmp(argv[i],"-globals") == 0) {
|
||||
if (argv[i+1]) {
|
||||
global_name = NewString(argv[i+1]);
|
||||
Swig_mark_arg(i);
|
||||
Swig_mark_arg(i+1);
|
||||
i++;
|
||||
} else {
|
||||
Swig_arg_error();
|
||||
}
|
||||
} else if ( (strcmp(argv[i],"-proxy") == 0)) {
|
||||
proxy_flag = 1;
|
||||
Swig_mark_arg(i);
|
||||
} else if (strcmp(argv[i],"-keyword") == 0) {
|
||||
use_kw = 1;
|
||||
Swig_mark_arg(i);
|
||||
} else if (strcmp(argv[i],"-help") == 0) {
|
||||
fputs(usage,stderr);
|
||||
}
|
||||
} else if (strcmp(argv[i],"-globals") == 0) {
|
||||
if (argv[i+1]) {
|
||||
global_name = NewString(argv[i+1]);
|
||||
Swig_mark_arg(i);
|
||||
Swig_mark_arg(i+1);
|
||||
i++;
|
||||
} else {
|
||||
Swig_arg_error();
|
||||
}
|
||||
} else if ( (strcmp(argv[i],"-proxy") == 0)) {
|
||||
proxy_flag = 1;
|
||||
Swig_mark_arg(i);
|
||||
} else if (strcmp(argv[i],"-keyword") == 0) {
|
||||
use_kw = 1;
|
||||
Swig_mark_arg(i);
|
||||
} else if (strcmp(argv[i],"-help") == 0) {
|
||||
fputs(usage,stderr);
|
||||
}
|
||||
...
|
||||
}
|
||||
}
|
||||
|
|
@ -2776,6 +2779,7 @@ such as:
|
|||
class PYTHON : public Language {
|
||||
protected:
|
||||
/* General DOH objects used for holding the strings */
|
||||
File *f_begin;
|
||||
File *f_runtime;
|
||||
File *f_header;
|
||||
File *f_wrappers;
|
||||
|
|
@ -2791,22 +2795,25 @@ int Python::top(Node *n) {
|
|||
...
|
||||
|
||||
/* Initialize I/O */
|
||||
f_runtime = NewFile(outfile, "w");
|
||||
if (!f_runtime) {
|
||||
f_begin = NewFile(outfile, "w", SWIG_output_files());
|
||||
if (!f_begin) {
|
||||
FileErrorDisplay(outfile);
|
||||
SWIG_exit(EXIT_FAILURE);
|
||||
}
|
||||
f_runtime = NewString("");
|
||||
f_init = NewString("");
|
||||
f_header = NewString("");
|
||||
f_wrappers = NewString("");
|
||||
|
||||
/* Register file targets with the SWIG file handler */
|
||||
Swig_register_filebyname("begin", f_begin);
|
||||
Swig_register_filebyname("header", f_header);
|
||||
Swig_register_filebyname("wrapper", f_wrappers);
|
||||
Swig_register_filebyname("runtime", f_runtime);
|
||||
Swig_register_filebyname("init", f_init);
|
||||
|
||||
/* Output module initialization code */
|
||||
Swig_banner(f_begin);
|
||||
...
|
||||
|
||||
/* Emit code for children */
|
||||
|
|
@ -2814,16 +2821,18 @@ int Python::top(Node *n) {
|
|||
|
||||
...
|
||||
/* Write all to the file */
|
||||
Dump(f_header, f_runtime);
|
||||
Dump(f_wrappers, f_runtime);
|
||||
Wrapper_pretty_print(f_init, f_runtime);
|
||||
Dump(f_runtime, f_begin);
|
||||
Dump(f_header, f_begin);
|
||||
Dump(f_wrappers, f_begin);
|
||||
Wrapper_pretty_print(f_init, f_begin);
|
||||
|
||||
/* Cleanup files */
|
||||
Delete(f_runtime);
|
||||
Delete(f_header);
|
||||
Delete(f_wrappers);
|
||||
Delete(f_init);
|
||||
Close(f_runtime);
|
||||
Delete(f_runtime);
|
||||
Close(f_begin);
|
||||
Delete(f_begin);
|
||||
|
||||
return SWIG_OK;
|
||||
}
|
||||
|
|
@ -3046,7 +3055,7 @@ but without the typemaps, there is still work to do.
|
|||
<!-- please report bugs in this section to ttn -->
|
||||
|
||||
<p>
|
||||
At the time of this writing, SWIG supports nearly a dozen languages,
|
||||
At the time of this writing, SWIG supports nearly twenty languages,
|
||||
which means that for continued sanity in maintaining the configuration
|
||||
files, the language modules need to follow some conventions. These are
|
||||
outlined here along with the admission that, yes it is ok to violate
|
||||
|
|
@ -3218,7 +3227,7 @@ The following are the minimum that are usually supported:
|
|||
Please copy these and modify for any new language.
|
||||
</p>
|
||||
|
||||
<H3><a name="Extending_nn42"></a>35.10.11 Examples and test cases</H3>
|
||||
<H3><a name="Extending_nn42"></a>35.10.11 User examples</H3>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -3247,7 +3256,226 @@ during this process, see the section on <a href="#n37a">configuration
|
|||
files</a>.
|
||||
</p>
|
||||
|
||||
<H3><a name="Extending_nn43"></a>35.10.12 Documentation</H3>
|
||||
<H3><a name="Extending_test_suite"></a>35.10.12 Test driven development and the test-suite</H3>
|
||||
|
||||
|
||||
<p>
|
||||
A test driven development approach is central to the improvement and development of SWIG.
|
||||
Most modifications to SWIG are accompanied by additional regression tests and checking all
|
||||
tests to ensure that no regressions have been introduced.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The regression testing is carried out by the SWIG <i>test-suite</i>.
|
||||
The test-suite consists of numerous testcase interface files in the <tt>Examples/test-suite</tt> directory
|
||||
as well as target language specific runtime tests in the <tt>Examples/test-suite/[lang]</tt> directory.
|
||||
When a testcase is run, it will execute the following steps for each testcase:
|
||||
</p>
|
||||
|
||||
<ol>
|
||||
<li>Execute SWIG passing it the testcase interface file.</li>
|
||||
<li>Compile the resulting generated C/C++ code with either the C or C++ compiler into object files.</li>
|
||||
<li>Link the object files into a dynamic library (dll/shared object).</li>
|
||||
<li>Compile any generated and any runtime test target language code with the target language compiler, if the target language supports compilation. This step thus does not apply to the interpreted languages.</li>
|
||||
<li>Execute a runtime test if one exists.</li>
|
||||
</ol>
|
||||
|
||||
<p>
|
||||
For example, the <i>ret_by_value</i> testcase consists of two components.
|
||||
The first component is the <tt>Examples/test-suite/ret_by_value.i</tt> interface file.
|
||||
The name of the SWIG module <b>must</b> always be the name of the testcase, so the <tt>ret_by_value.i</tt> interface file thus begins with:
|
||||
</p>
|
||||
|
||||
<div class="code">
|
||||
<pre>
|
||||
%module ret_by_value
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
<p>
|
||||
The testcase code will then follow the module declaration,
|
||||
usually within a <tt>%inline %{ ... %}</tt> section for the majority of the tests.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The second component is the optional runtime tests.
|
||||
Any runtime tests are named using the following convention: <tt>[testcase]_runme.[ext]</tt>,
|
||||
where <tt>[testcase]</tt> is the testcase name and <tt>[ext]</tt> is the normal extension for the target language file.
|
||||
In this case, the Java and Python target languages implement a runtime test, so their files are respectively,
|
||||
<tt>Examples/test-suite/java/ret_by_value_runme.java</tt> and
|
||||
<tt>Examples/test-suite/python/ret_by_value_runme.py</tt>.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The goal of the test-suite is to test as much as possible in a <b>silent</b> manner.
|
||||
This way any SWIG or compiler errors or warnings are easily visible.
|
||||
Should there be any warnings, changes must be made to either fix them (preferably) or suppress them.
|
||||
Compilation or runtime errors result in a testcase failure and will be immediately visible.
|
||||
It is therefore essential that the runtime tests are written in a manner that displays nothing to stdout/stderr on success
|
||||
but error/exception out with an error message on stderr on failure.
|
||||
</p>
|
||||
|
||||
<H4><a name="Extending_running_test_suite"></a>35.10.12.1 Running the test-suite</H4>
|
||||
|
||||
|
||||
<p>
|
||||
In order for the test-suite to work for a particular target language, the language must be correctly detected
|
||||
and configured during the configure stage so that the correct Makefiles are generated.
|
||||
Most development occurs on Linux, so usually it is a matter of installing the development packages for the target language
|
||||
and simply configuring as outlined <a href="#Extending_starting_out">earlier</a>.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
If when running the test-suite commands that follow, you get a message that the test was skipped, it indicates that the
|
||||
configure stage is missing information in order to compile and run everything for that language.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The test-suite can be run in a number of ways.
|
||||
The first group of commands are for running multiple testcases in one run and should be executed in the top level directory.
|
||||
To run the entire test-suite (can take a long time):
|
||||
</p>
|
||||
|
||||
<div class="shell"><pre>
|
||||
make -k check-test-suite
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
To run the test-suite just for target language [lang], replace [lang] with one of csharp, java, perl5, python, ruby, tcl etc:
|
||||
</p>
|
||||
|
||||
<div class="shell"><pre>
|
||||
make check-[lang]-test-suite
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
Note that if a runtime test is available, a message "(with run test)" is displayed when run. For example:
|
||||
</p>
|
||||
|
||||
<div class="shell"><pre>
|
||||
$ make check-python-test-suite
|
||||
checking python test-suite
|
||||
checking testcase argcargvtest (with run test) under python
|
||||
checking testcase python_autodoc under python
|
||||
checking testcase python_append (with run test) under python
|
||||
checking testcase callback (with run test) under python
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
The files generated on a previous run can be deleted using the clean targets, either the whole test-suite or for a particular language:
|
||||
</p>
|
||||
|
||||
<div class="shell"><pre>
|
||||
make clean-test-suite
|
||||
make clean-[lang]-test-suite
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
The test-suite can be run in a <i>partialcheck</i> mode where just SWIG is executed, that is, the compile,
|
||||
link and running of the testcases is not performed.
|
||||
Note that the partialcheck does not require the target language to be correctly configured and detected and unlike the other test-suite make targets, is never skipped. Once again, either all the languages can be executed or just a chosen language:
|
||||
</p>
|
||||
|
||||
<div class="shell"><pre>
|
||||
make partialcheck-test-suite
|
||||
make partialcheck-[lang]-test-suite
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
If your computer has more than one CPU, you are strongly advised to use parallel make to speed up the execution speed.
|
||||
This can be done with any of the make targets that execute more than one testcase.
|
||||
For example, a dual core processor can efficiently use 2 parallel jobs:
|
||||
</p>
|
||||
|
||||
<div class="shell"><pre>
|
||||
make -j2 check-test-suite
|
||||
make -j2 check-python-test-suite
|
||||
make -j2 partialcheck-java-test-suite
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
The second group of commands are for running individual testcases and should be executed in the appropriate
|
||||
target language directory, <tt>Examples/test-suite/[lang]</tt>.
|
||||
Testcases can contain either C or C++ code and when one is written, a decision must be made as to which of these input
|
||||
languages is to be used.
|
||||
Replace <tt>[testcase]</tt> in the commands below with the name of the testcase.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
For a C language testcase, add the testcase under the C_TEST_CASES list in <tt>Examples/test-suite/common.mk</tt> and
|
||||
execute individually as:
|
||||
</p>
|
||||
<div class="shell"><pre>
|
||||
make -s [testcase].ctest
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
For a C++ language testcase, add the testcase under the CPP_TEST_CASES list in <tt>Examples/test-suite/common.mk</tt> and
|
||||
execute individually as:
|
||||
</p>
|
||||
<div class="shell"><pre>
|
||||
make -s [testcase].cpptest
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
A third category of tests are C++ language testcases testing multiple modules (the %import directive).
|
||||
These require more than one shared library (dll/shared object) to be built and so are separated out from the normal C++ testcases.
|
||||
Add the testcase under the MULTI_CPP_TEST_CASES list in <tt>Examples/test-suite/common.mk</tt> and
|
||||
execute individually as:
|
||||
</p>
|
||||
<div class="shell"><pre>
|
||||
make -s [testcase].multicpptest
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
To delete the generated files, execute:
|
||||
</p>
|
||||
<div class="shell"><pre>
|
||||
make -s [testcase].clean
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
If you would like to see the exact commands being executed, drop the -s option:
|
||||
</p>
|
||||
<div class="shell"><pre>
|
||||
make [testcase].ctest
|
||||
make [testcase].cpptest
|
||||
make [testcase].multicpptest
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
Some real examples of each:
|
||||
</p>
|
||||
<div class="shell"><pre>
|
||||
make -s ret_by_value.clean
|
||||
make -s ret_by_value.ctest
|
||||
make -s bools.cpptest
|
||||
make -s imports.multicpptest
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
Advanced usage of the test-suite facilitates running tools on some of the five stages.
|
||||
The make variables <tt>SWIGTOOL</tt> and <tt>RUNTOOL</tt> are used to specify a tool to respectively, invoke SWIG
|
||||
and the execution of the runtime test.
|
||||
You are advised to view the <tt>Examples/test-suite/common.mk</tt> file for details but for a short summary,
|
||||
the classic usage is to use <a href="http://valgrind.org/">Valgrind</a> for memory checking.
|
||||
For example, checking for memory leaks when running the runtime test in the target language interpreter:
|
||||
</p>
|
||||
|
||||
<div class="shell"><pre>
|
||||
make ret_by_value.ctest RUNTOOL="valgrind --leak-check=full"
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
This will probably make more sense if you look at the output of the above as it will show the exact commands being executed.
|
||||
SWIG can be analyzed for bad memory accesses using:
|
||||
</p>
|
||||
|
||||
<div class="shell"><pre>
|
||||
make ret_by_value.ctest SWIGTOOL="valgrind --tool=memcheck --trace-children=yes"
|
||||
</pre></div>
|
||||
|
||||
<H3><a name="Extending_nn43"></a>35.10.13 Documentation</H3>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -3279,7 +3507,7 @@ Some topics that you'll want to be sure to address include:
|
|||
if available.
|
||||
</ul>
|
||||
|
||||
<H3><a name="Extending_prerequisites"></a>35.10.13 Prerequisites for adding a new language module to the SWIG distribution</H3>
|
||||
<H3><a name="Extending_prerequisites"></a>35.10.14 Prerequisites for adding a new language module to the SWIG distribution</H3>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -3336,7 +3564,7 @@ should be added should there be an area not already covered by
|
|||
the existing tests.
|
||||
</p>
|
||||
|
||||
<H3><a name="Extending_coding_style_guidelines"></a>35.10.14 Coding style guidelines</H3>
|
||||
<H3><a name="Extending_coding_style_guidelines"></a>35.10.15 Coding style guidelines</H3>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -3360,11 +3588,30 @@ The generated C/C++ code should also follow this style as close as possible. How
|
|||
should be avoided as unlike the SWIG developers, users will never have consistent tab settings.
|
||||
</p>
|
||||
|
||||
<H2><a name="Extending_nn44"></a>35.11 Typemaps</H2>
|
||||
<H2><a name="Extending_debugging_options"></a>35.11 Debugging Options</H2>
|
||||
|
||||
|
||||
<H3><a name="Extending_nn45"></a>35.11.1 Proxy classes</H3>
|
||||
<p>
|
||||
There are various command line options which can aid debugging a SWIG interface as well as debugging the development of a language module. These are as follows:
|
||||
</p>
|
||||
|
||||
<div class="shell"><pre>
|
||||
-debug-classes - Display information about the classes found in the interface
|
||||
-debug-module <n> - Display module parse tree at stages 1-4, <n> is a csv list of stages
|
||||
-debug-symtabs - Display symbol tables information
|
||||
-debug-symbols - Display target language symbols in the symbol tables
|
||||
-debug-csymbols - Display C symbols in the symbol tables
|
||||
-debug-lsymbols - Display target language layer symbols
|
||||
-debug-tags - Display information about the tags found in the interface
|
||||
-debug-template - Display information for debugging templates
|
||||
-debug-top <n> - Display entire parse tree at stages 1-4, <n> is a csv list of stages
|
||||
-debug-typedef - Display information about the types and typedefs in the interface
|
||||
-debug-typemap - Display information for debugging typemaps
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
The complete list of command line options for SWIG are available by running <tt>swig -help</tt>.
|
||||
</p>
|
||||
|
||||
<H2><a name="Extending_nn46"></a>35.12 Guide to parse tree nodes</H2>
|
||||
|
||||
|
|
@ -3774,6 +4021,13 @@ extern "X" { ... } declaration.
|
|||
</pre>
|
||||
</div>
|
||||
|
||||
<H2><a name="Extending_further_info"></a>35.13 Further Development Information</H2>
|
||||
|
||||
|
||||
<p>
|
||||
There is further documentation available on the internals of SWIG, API documentation and debugging information.
|
||||
This is shipped with SWIG in the <tt>Doc/Devel</tt> directory.
|
||||
</P>
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -814,7 +814,7 @@ Produces the following code at the top of the generated GOOPS guile-module
|
|||
<code>Module-primitive.scm</code> (with <i>primitive</i> replaced with whatever is given with the <code>-primsuffix</code>
|
||||
argument. The code to load the <code>.so</code> library should be located in the <code>%scheme</code> directive,
|
||||
which will then be added to the scmstub file.
|
||||
Swig will automatically generate the line <code>(use-modules (<i>Package</i> <i>Module-primitive</i>))</code>
|
||||
SWIG will automatically generate the line <code>(use-modules (<i>Package</i> <i>Module-primitive</i>))</code>
|
||||
into the GOOPS guile-module. So if <i>Module-primitive.scm</i> is on the autoload path for guile, the
|
||||
<code>%goops</code> directive can be empty. Otherwise, the <code>%goops</code> directive should contain
|
||||
whatever code is needed to load the <i>Module-primitive.scm</i> file into guile.</p>
|
||||
|
|
@ -848,7 +848,7 @@ Produces the following code at the top of the generated GOOPS guile-module
|
|||
</li>
|
||||
|
||||
<li><p><b>Module Linkage</b>: This is very similar to passive linkage with a scmstub file.
|
||||
Swig will also automatically generate the line <code>(use-modules
|
||||
SWIG will also automatically generate the line <code>(use-modules
|
||||
(<i>Package</i> <i>Module-primitive</i>))</code> into the GOOPS guile-module. Again the <code>%goops</code>
|
||||
directive should contain whatever code is needed to get that module loaded into guile.</p>
|
||||
|
||||
|
|
|
|||
|
|
@ -334,7 +334,7 @@ major features include:
|
|||
|
||||
<p>
|
||||
Currently, the only major C++ feature not supported is nested classes--a limitation
|
||||
that will be removed in a future release.
|
||||
that should be removed in a future release, but has some workarounds for the moment.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
|
|
|
|||
|
|
@ -253,6 +253,12 @@ To change this, you can use the <tt>-o</tt> option.
|
|||
It is also possible to change the <a href="SWIG.html#output">output directory </a> that the Java files are generated into using <tt>-outdir</tt>.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The module name, specified with <tt>%module</tt>, determines the name of various generated classes as discussed <a href=#module_packages_classes>later</a>.
|
||||
Note that the module name does not define a Java package and by default, the generated Java classes do not have a Java package.
|
||||
The <tt>-package</tt> option described below can specify a Java package name to use.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The following sections have further practical examples and details on how you might go about
|
||||
compiling and using the generated files.
|
||||
|
|
@ -441,6 +447,19 @@ $
|
|||
<p>
|
||||
This error usually indicates that you forgot to include some object files or libraries in the linking of the native library file.
|
||||
Make sure you compile both the SWIG wrapper file and the code you are wrapping into the native library file.
|
||||
If you forget to compile and link in the SWIG wrapper file into your native library file, you will get a message similar to the following:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
$ java runme
|
||||
Exception in thread "main" java.lang.UnsatisfiedLinkError: exampleJNI.gcd(II)I
|
||||
at exampleJNI.gcd(Native Method)
|
||||
at example.gcd(example.java:12)
|
||||
at runme.main(runme.java:18)
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
where <tt>gcd</tt> is the missing JNI function that SWIG generated into the wrapper file.
|
||||
Also make sure you pass all of the required libraries to the linker.
|
||||
The <tt>java -verbose:jni</tt> commandline switch is also a great way to get more information on unresolved symbols.
|
||||
One last piece of advice is to beware of the common faux pas of having more than one native library version in your path.
|
||||
|
|
@ -657,7 +676,9 @@ This is often combined with the <tt>-outdir</tt> to specify a package directory
|
|||
swig -java -package com.bloggs.swig -outdir com/bloggs/swig example.i
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
SWIG won't create the directory, so make sure it exists beforehand.
|
||||
</p>
|
||||
|
||||
<H3><a name="functions"></a>21.3.2 Functions</H3>
|
||||
|
||||
|
|
@ -1753,7 +1774,7 @@ If declarations such as these appear, you will get a warning message like this:
|
|||
|
||||
<div class="code">
|
||||
<pre>
|
||||
example.i:12: Warning(515): Overloaded method spam(unsigned short) ignored.
|
||||
example.i:12: Warning 515: Overloaded method spam(unsigned short) ignored.
|
||||
Method spam(int) at example.i:11 used.
|
||||
</pre>
|
||||
</div>
|
||||
|
|
|
|||
|
|
@ -667,7 +667,7 @@ in order for this to work.
|
|||
</p>
|
||||
|
||||
<p>
|
||||
<b><tt>char *cdata(void *ptr, int nbytes)</tt></b>
|
||||
<b><tt>const char *cdata(void *ptr, size_t nbytes)</tt></b>
|
||||
</p>
|
||||
|
||||
<div class="indent"><p>
|
||||
|
|
@ -676,7 +676,7 @@ pointer.
|
|||
</p></div>
|
||||
|
||||
<p>
|
||||
<b><tt>void memmove(void *ptr, char *s)</tt></b>
|
||||
<b><tt>void memmove(void *ptr, const char *s)</tt></b>
|
||||
</p>
|
||||
|
||||
<div class="indent"><p>
|
||||
|
|
@ -890,7 +890,10 @@ char *foo();
|
|||
</div>
|
||||
|
||||
<p>
|
||||
This will release the result.
|
||||
This will release the result if the appropriate target language support is available.
|
||||
SWIG provides the appropriate "newfree" typemap for <tt>char *</tt> so that the memory is released,
|
||||
however, you may need to provide your own "newfree" typemap for other types.
|
||||
See <a href="Customization.html#ownership">Object ownership and %newobject</a> for more details.
|
||||
</p>
|
||||
|
||||
<H3><a name="Library_nn12"></a>8.3.4 cstring.i</H3>
|
||||
|
|
|
|||
|
|
@ -684,8 +684,8 @@ void foo(Bar &b);
|
|||
If declarations such as these appear, you will get a warning message like this:
|
||||
</p>
|
||||
<div class="shell"><pre>
|
||||
example.i:12: Warning(509): Overloaded spam(short) is shadowed by spam(int)
|
||||
at example.i:11.
|
||||
example.i:12: Warning 509: Overloaded method spam(short) effectively ignored,
|
||||
example.i:11: Warning 509: as it is shadowed by spam(int).
|
||||
</pre></div>
|
||||
<p>
|
||||
To fix this, you either need to ignore or rename one of the methods. For example:
|
||||
|
|
|
|||
|
|
@ -10,6 +10,7 @@
|
|||
<!-- INDEX -->
|
||||
<div class="sectiontoc">
|
||||
<ul>
|
||||
<li><a href="#Modules_introduction">Modules Introduction</a>
|
||||
<li><a href="#Modules_nn1">Basics</a>
|
||||
<li><a href="#Modules_nn2">The SWIG runtime code</a>
|
||||
<li><a href="#external_run_time">External access to the runtime</a>
|
||||
|
|
@ -22,11 +23,49 @@
|
|||
|
||||
|
||||
|
||||
<H2><a name="Modules_introduction"></a>15.1 Modules Introduction</H2>
|
||||
|
||||
|
||||
<p>
|
||||
Each invocation of SWIG requires a module name to be specified.
|
||||
The module name is used to name the resulting target language extension module.
|
||||
Exactly what this means and and what the name is used for
|
||||
depends on the target language, for example the name can define
|
||||
a target language namespace or merely be a useful name for naming files or helper classes.
|
||||
Essentially, a module comprises target language wrappers for a chosen collection of global variables/functions, structs/classes and other C/C++ types.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The module name can be supplied in one of two ways.
|
||||
The first is to specify it with the special <tt>%module</tt>
|
||||
directive. This directive must appear at the beginning of the interface file.
|
||||
The general form of this directive is:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
<tt>%module(option1="value1",option2="value2",...) modulename</tt>
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
where the modulename is mandatory and the options add one or more optional additional features.
|
||||
Typically no options are specified, for example:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
<tt>%module mymodule</tt>
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
The second way to specify the module name is with the <tt>-module</tt> command line option, for example <tt>-module mymodule</tt>.
|
||||
If the module name is supplied on the command line, it overrides the name specified by the
|
||||
<tt>%module</tt> directive.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
When first working with SWIG, users commonly start by creating a
|
||||
single module. That is, you might define a single SWIG interface that
|
||||
wraps some set of C/C++ code. You then compile all of the generated
|
||||
wrapper code into a module and use it. For large applications, however,
|
||||
wrapper code together and use it. For large applications, however,
|
||||
this approach is problematic---the size of the generated wrapper code
|
||||
can be rather large. Moreover, it is probably easier to manage the
|
||||
target language interface when it is broken up into smaller pieces.
|
||||
|
|
@ -34,10 +73,11 @@ target language interface when it is broken up into smaller pieces.
|
|||
|
||||
<p>
|
||||
This chapter describes the problem of using SWIG in programs
|
||||
where you want to create a collection of modules.
|
||||
where you want to create a collection of modules.
|
||||
Each module in the collection is created via separate invocations of SWIG.
|
||||
</p>
|
||||
|
||||
<H2><a name="Modules_nn1"></a>15.1 Basics</H2>
|
||||
<H2><a name="Modules_nn1"></a>15.2 Basics</H2>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -98,7 +138,7 @@ base class's methods. Typically you will get a warning when the module name is m
|
|||
</p>
|
||||
|
||||
<div class="shell"> <pre>
|
||||
derived_module.i:8: Warning(401): Base class 'base' ignored - unknown module name for base. Either import
|
||||
derived_module.i:8: Warning 401: Base class 'base' ignored - unknown module name for base. Either import
|
||||
the appropriate module interface file or specify the name of the module in the %import directive.
|
||||
</pre></div>
|
||||
|
||||
|
|
@ -135,7 +175,7 @@ in parallel from multiple threads as SWIG provides no locking - for more on that
|
|||
issue, read on.
|
||||
</p>
|
||||
|
||||
<H2><a name="Modules_nn2"></a>15.2 The SWIG runtime code</H2>
|
||||
<H2><a name="Modules_nn2"></a>15.3 The SWIG runtime code</H2>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -201,7 +241,7 @@ can peacefully coexist. So the type structures are separated by the
|
|||
is empty. Only modules compiled with the same pair will share type information.
|
||||
</p>
|
||||
|
||||
<H2><a name="external_run_time"></a>15.3 External access to the runtime</H2>
|
||||
<H2><a name="external_run_time"></a>15.4 External access to the runtime</H2>
|
||||
|
||||
|
||||
<p>As described in <a href="Typemaps.html#runtime_type_checker">The run-time type checker</a>,
|
||||
|
|
@ -238,7 +278,7 @@ SWIG_TYPE_TABLE to be the same as the module whose types you are trying to
|
|||
access.
|
||||
</p>
|
||||
|
||||
<H2><a name="Modules_nn4"></a>15.4 A word of caution about static libraries</H2>
|
||||
<H2><a name="Modules_nn4"></a>15.5 A word of caution about static libraries</H2>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -249,7 +289,7 @@ into it. This is very often <b>NOT</b> what you want and it can lead to unexpect
|
|||
behavior. When working with dynamically loadable modules, you should try to work exclusively with shared libraries.
|
||||
</p>
|
||||
|
||||
<H2><a name="Modules_nn5"></a>15.5 References</H2>
|
||||
<H2><a name="Modules_nn5"></a>15.6 References</H2>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -257,7 +297,7 @@ Due to the complexity of working with shared libraries and multiple modules, it
|
|||
an outside reference. John Levine's "Linkers and Loaders" is highly recommended.
|
||||
</p>
|
||||
|
||||
<H2><a name="Modules_nn6"></a>15.6 Reducing the wrapper file size</H2>
|
||||
<H2><a name="Modules_nn6"></a>15.7 Reducing the wrapper file size</H2>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
|
|||
|
|
@ -634,13 +634,13 @@ length. Instead, use multiple returns, as in the argout_ref example.
|
|||
#include "example.h"
|
||||
%}
|
||||
|
||||
%include stl.i
|
||||
%include <stl.i>
|
||||
|
||||
namespace std {
|
||||
%template(StringVector) std::vector < string >;
|
||||
};
|
||||
|
||||
%include example.h
|
||||
%include "example.h"
|
||||
</pre></td></tr>
|
||||
<tr><td><font size="-1"><i>This example is in Examples/ocaml/stl
|
||||
</i></font></td></tr>
|
||||
|
|
|
|||
|
|
@ -40,7 +40,7 @@
|
|||
<li><a href="#Perl5_nn24">Modules and packages</a>
|
||||
</ul>
|
||||
<li><a href="#Perl5_nn25">Input and output parameters</a>
|
||||
<li><a href="#Perl5_nn26">Exception handling </a>
|
||||
<li><a href="#Perl5_nn26">Exception handling</a>
|
||||
<li><a href="#Perl5_nn27">Remapping datatypes with typemaps</a>
|
||||
<ul>
|
||||
<li><a href="#Perl5_nn28">A simple typemap example</a>
|
||||
|
|
@ -50,8 +50,8 @@
|
|||
</ul>
|
||||
<li><a href="#Perl5_nn32">Typemap Examples</a>
|
||||
<ul>
|
||||
<li><a href="#Perl5_nn33">Converting a Perl5 array to a char ** </a>
|
||||
<li><a href="#Perl5_nn34">Return values </a>
|
||||
<li><a href="#Perl5_nn33">Converting a Perl5 array to a char **</a>
|
||||
<li><a href="#Perl5_nn34">Return values</a>
|
||||
<li><a href="#Perl5_nn35">Returning values from arguments</a>
|
||||
<li><a href="#Perl5_nn36">Accessing array structure members</a>
|
||||
<li><a href="#Perl5_nn37">Turning Perl references into C pointers</a>
|
||||
|
|
@ -112,7 +112,7 @@ options are found near the end of the chapter.
|
|||
|
||||
|
||||
<p>
|
||||
To build a Perl5 module, run Swig using the <tt>-perl</tt> option as
|
||||
To build a Perl5 module, run SWIG using the <tt>-perl</tt> option as
|
||||
follows :
|
||||
</p>
|
||||
|
||||
|
|
@ -264,7 +264,7 @@ extern int fact(int);
|
|||
%}
|
||||
|
||||
// Include code for rebuilding Perl
|
||||
%include perlmain.i
|
||||
%include <perlmain.i>
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
|
|
@ -815,7 +815,7 @@ extern char *path; // Declared later in the input
|
|||
|
||||
|
||||
<p>
|
||||
Constants are wrapped as read-only Perl variables. For example:
|
||||
By default, constants are wrapped as read-only Perl variables. For example:
|
||||
</p>
|
||||
|
||||
<div class="code">
|
||||
|
|
@ -838,6 +838,19 @@ $example::FOO = 2; # Error
|
|||
</pre>
|
||||
</div>
|
||||
|
||||
<p>
|
||||
Alternatively, if you use swig's <tt>-const</tt> option, constants are wrapped
|
||||
such that the leading $ isn't required (by using a constant subroutine), which
|
||||
usually gives a more natural Perl interface, for example:
|
||||
</p>
|
||||
|
||||
<div class="targetlang">
|
||||
<pre>
|
||||
use example;
|
||||
print example::FOO,"\n";
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
<H3><a name="Perl5_nn18"></a>28.4.4 Pointers</H3>
|
||||
|
||||
|
||||
|
|
@ -879,7 +892,7 @@ if (defined($ptr)) {
|
|||
</pre></div>
|
||||
|
||||
<p>
|
||||
To create a NULL pointer, you should pass the <tt>undef </tt>value to
|
||||
To create a NULL pointer, you should pass the <tt>undef</tt> value to
|
||||
a function.
|
||||
</p>
|
||||
|
||||
|
|
@ -889,7 +902,7 @@ pointer that SWIG wrapper functions return. Suppose that <tt>$a</tt>
|
|||
and <tt>$b</tt> are two references that point to the same C object.
|
||||
In general, <tt>$a</tt> and <tt>$b</tt> will be different--since they
|
||||
are different references. Thus, it is a mistake to check the equality
|
||||
of <tt>$a </tt>and <tt>$b</tt> to check the equality of two C
|
||||
of <tt>$a</tt> and <tt>$b</tt> to check the equality of two C
|
||||
pointers. The correct method to check equality of C pointers is to
|
||||
dereference them as follows :
|
||||
</p>
|
||||
|
|
@ -1543,7 +1556,7 @@ example:
|
|||
<div class="code">
|
||||
<pre>
|
||||
%module example
|
||||
%include typemaps.i
|
||||
%include "typemaps.i"
|
||||
|
||||
void add(int x, int y, int *REFERENCE);
|
||||
</pre>
|
||||
|
|
@ -1567,7 +1580,7 @@ print "$c\n";
|
|||
<b>Note:</b> The <tt>REFERENCE</tt> feature is only currently supported for numeric types (integers and floating point).
|
||||
</p>
|
||||
|
||||
<H2><a name="Perl5_nn26"></a>28.6 Exception handling </H2>
|
||||
<H2><a name="Perl5_nn26"></a>28.6 Exception handling</H2>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -2107,7 +2120,7 @@ might look at the files "<tt>perl5.swg</tt>" and "<tt>typemaps.i</tt>" in
|
|||
the SWIG library.
|
||||
</p>
|
||||
|
||||
<H3><a name="Perl5_nn33"></a>28.8.1 Converting a Perl5 array to a char ** </H3>
|
||||
<H3><a name="Perl5_nn33"></a>28.8.1 Converting a Perl5 array to a char **</H3>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -2160,7 +2173,7 @@ reference to be used as a char ** datatype.
|
|||
};
|
||||
myav = av_make(len,svs);
|
||||
free(svs);
|
||||
$result = newRV((SV*)myav);
|
||||
$result = newRV_noinc((SV*)myav);
|
||||
sv_2mortal($result);
|
||||
argvi++;
|
||||
}
|
||||
|
|
@ -2199,7 +2212,7 @@ print @$b,"\n"; # Print it out
|
|||
</pre></div>
|
||||
|
||||
|
||||
<H3><a name="Perl5_nn34"></a>28.8.2 Return values </H3>
|
||||
<H3><a name="Perl5_nn34"></a>28.8.2 Return values</H3>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -2714,7 +2727,7 @@ corresponding Perl object (this situation turns out to come up
|
|||
frequently when constructing objects like linked lists and trees).
|
||||
When C takes possession of an object, you can change Perl's ownership
|
||||
by simply deleting the object from the <tt>%OWNER</tt> hash. This is
|
||||
done using the <tt>DISOWN </tt>method.
|
||||
done using the <tt>DISOWN</tt> method.
|
||||
</p>
|
||||
|
||||
<div class="targetlang"><pre>
|
||||
|
|
|
|||
|
|
@ -32,16 +32,22 @@
|
|||
</ul>
|
||||
<li><a href="#Php_nn2_7">PHP Pragmas, Startup and Shutdown code</a>
|
||||
</ul>
|
||||
<li><a href="#Php_nn3">Cross language polymorphism</a>
|
||||
<ul>
|
||||
<li><a href="#Php_nn3_1">Enabling directors</a>
|
||||
<li><a href="#Php_nn3_2">Director classes</a>
|
||||
<li><a href="#Php_nn3_3">Ownership and object destruction</a>
|
||||
<li><a href="#Php_nn3_4">Exception unrolling</a>
|
||||
<li><a href="#Php_nn3_5">Overhead and code bloat</a>
|
||||
<li><a href="#Php_nn3_6">Typemaps</a>
|
||||
<li><a href="#Php_nn3_7">Miscellaneous</a>
|
||||
</ul>
|
||||
</ul>
|
||||
</div>
|
||||
<!-- INDEX -->
|
||||
|
||||
|
||||
|
||||
<p>
|
||||
<b>Caution: This chapter (and module!) is still under construction</b>
|
||||
</p>
|
||||
|
||||
<p>
|
||||
SWIG supports generating wrappers for PHP5. Support for PHP4 has been removed
|
||||
as of SWIG 1.3.37. The PHP developers are no longer making new PHP4 releases,
|
||||
|
|
@ -95,7 +101,7 @@ also contain PHP5 class wrappers.
|
|||
</p>
|
||||
|
||||
<p>
|
||||
Swig can generate PHP extensions from C++ libraries as well when
|
||||
SWIG can generate PHP extensions from C++ libraries as well when
|
||||
given the <tt>-c++</tt> option. The support for C++ is discussed in
|
||||
more detail in <a href="#Php_nn2_6">section 27.2.6</a>.
|
||||
</p>
|
||||
|
|
@ -479,7 +485,7 @@ One can include <b>cpointer.i</b> to generate PHP wrappers to <tt>int
|
|||
|
||||
<div class="code"><pre>
|
||||
%module example
|
||||
%include cpointer.i
|
||||
%include "cpointer.i"
|
||||
%pointer_functions(int,intp)
|
||||
|
||||
void add( int *in1, int *in2, int *result);
|
||||
|
|
@ -513,7 +519,7 @@ parameter names as appropriate.
|
|||
|
||||
<div class="code"><pre>
|
||||
%module example
|
||||
%include typemaps.i
|
||||
%include "typemaps.i"
|
||||
|
||||
void add( int *INPUT, int *INPUT, int *OUTPUT);
|
||||
|
||||
|
|
@ -545,7 +551,7 @@ named typemap REFERENCE.
|
|||
|
||||
<div class="code"><pre>
|
||||
%module example
|
||||
%include phppointers.i
|
||||
%include "phppointers.i"
|
||||
|
||||
void add( int *REF, int *REF, int *REF);
|
||||
|
||||
|
|
@ -866,5 +872,381 @@ The <tt>%rinit</tt> and <tt>%rshutdown</tt> statements insert code
|
|||
into the request init and shutdown code respectively.
|
||||
</p>
|
||||
|
||||
<H2><a name="Php_nn3"></a>29.3 Cross language polymorphism</H2>
|
||||
|
||||
|
||||
<p>
|
||||
Proxy classes provide a more natural, object-oriented way to access
|
||||
extension classes. As described above, each proxy instance has an
|
||||
associated C++ instance, and method calls to the proxy are passed to the
|
||||
C++ instance transparently via C wrapper functions.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
This arrangement is asymmetric in the sense that no corresponding
|
||||
mechanism exists to pass method calls down the inheritance chain from
|
||||
C++ to PHP. In particular, if a C++ class has been extended in PHP
|
||||
(by extending the proxy class), these extensions will not be visible
|
||||
from C++ code. Virtual method calls from C++ are thus not able access
|
||||
the lowest implementation in the inheritance chain.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Changes have been made to SWIG 1.3.18 to address this problem and make
|
||||
the relationship between C++ classes and proxy classes more symmetric.
|
||||
To achieve this goal, new classes called directors are introduced at the
|
||||
bottom of the C++ inheritance chain. Support for generating PHP classes
|
||||
has been added in SWIG 1.3.40. The job of the directors is to route
|
||||
method calls correctly, either to C++ implementations higher in the
|
||||
inheritance chain or to PHP implementations lower in the inheritance
|
||||
chain. The upshot is that C++ classes can be extended in PHP and from
|
||||
C++ these extensions look exactly like native C++ classes. Neither C++
|
||||
code nor PHP code needs to know where a particular method is
|
||||
implemented: the combination of proxy classes, director classes, and C
|
||||
wrapper functions takes care of all the cross-language method routing
|
||||
transparently.
|
||||
</p>
|
||||
|
||||
<H3><a name="Php_nn3_1"></a>29.3.1 Enabling directors</H3>
|
||||
|
||||
|
||||
<p>
|
||||
The director feature is disabled by default. To use directors you
|
||||
must make two changes to the interface file. First, add the "directors"
|
||||
option to the %module directive, like this:
|
||||
</p>
|
||||
|
||||
<div class="code">
|
||||
<pre>
|
||||
%module(directors="1") modulename
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
<p>
|
||||
Without this option no director code will be generated. Second, you
|
||||
must use the %feature("director") directive to tell SWIG which classes
|
||||
and methods should get directors. The %feature directive can be applied
|
||||
globally, to specific classes, and to specific methods, like this:
|
||||
</p>
|
||||
|
||||
<div class="code">
|
||||
<pre>
|
||||
// generate directors for all classes that have virtual methods
|
||||
%feature("director");
|
||||
|
||||
// generate directors for all virtual methods in class Foo
|
||||
%feature("director") Foo;
|
||||
|
||||
// generate a director for just Foo::bar()
|
||||
%feature("director") Foo::bar;
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
<p>
|
||||
You can use the %feature("nodirector") directive to turn off
|
||||
directors for specific classes or methods. So for example,
|
||||
</p>
|
||||
|
||||
<div class="code">
|
||||
<pre>
|
||||
%feature("director") Foo;
|
||||
%feature("nodirector") Foo::bar;
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
<p>
|
||||
will generate directors for all virtual methods of class Foo except
|
||||
bar().
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Directors can also be generated implicitly through inheritance.
|
||||
In the following, class Bar will get a director class that handles
|
||||
the methods one() and two() (but not three()):
|
||||
</p>
|
||||
|
||||
<div class="code">
|
||||
<pre>
|
||||
%feature("director") Foo;
|
||||
class Foo {
|
||||
public:
|
||||
Foo(int foo);
|
||||
virtual void one();
|
||||
virtual void two();
|
||||
};
|
||||
|
||||
class Bar: public Foo {
|
||||
public:
|
||||
virtual void three();
|
||||
};
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
<p>
|
||||
then at the PHP side you can define
|
||||
</p>
|
||||
|
||||
<div class="targetlang">
|
||||
<pre>
|
||||
require("mymodule.php");
|
||||
|
||||
class MyFoo extends Foo {
|
||||
function one() {
|
||||
print "one from php\n";
|
||||
}
|
||||
}
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
|
||||
<H3><a name="Php_nn3_2"></a>29.3.2 Director classes</H3>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<p>
|
||||
For each class that has directors enabled, SWIG generates a new class
|
||||
that derives from both the class in question and a special
|
||||
<tt>Swig::Director</tt> class. These new classes, referred to as director
|
||||
classes, can be loosely thought of as the C++ equivalent of the PHP
|
||||
proxy classes. The director classes store a pointer to their underlying
|
||||
PHP object. Indeed, this is quite similar to the "_cPtr" and "thisown"
|
||||
members of the PHP proxy classes.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
For simplicity let's ignore the <tt>Swig::Director</tt> class and refer to the
|
||||
original C++ class as the director's base class. By default, a director
|
||||
class extends all virtual methods in the inheritance chain of its base
|
||||
class (see the preceding section for how to modify this behavior).
|
||||
Thus all virtual method calls, whether they originate in C++ or in
|
||||
PHP via proxy classes, eventually end up in at the implementation in the
|
||||
director class. The job of the director methods is to route these method
|
||||
calls to the appropriate place in the inheritance chain. By "appropriate
|
||||
place" we mean the method that would have been called if the C++ base
|
||||
class and its extensions in PHP were seamlessly integrated. That
|
||||
seamless integration is exactly what the director classes provide,
|
||||
transparently skipping over all the messy extension API glue that binds
|
||||
the two languages together.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
In reality, the "appropriate place" is one of only two possibilities:
|
||||
C++ or PHP. Once this decision is made, the rest is fairly easy. If the
|
||||
correct implementation is in C++, then the lowest implementation of the
|
||||
method in the C++ inheritance chain is called explicitly. If the correct
|
||||
implementation is in PHP, the Zend API is used to call the method of the
|
||||
underlying PHP object (after which the usual virtual method resolution
|
||||
in PHP automatically finds the right implementation).
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Now how does the director decide which language should handle the method call?
|
||||
The basic rule is to handle the method in PHP, unless there's a good
|
||||
reason not to. The reason for this is simple: PHP has the most
|
||||
"extended" implementation of the method. This assertion is guaranteed,
|
||||
since at a minimum the PHP proxy class implements the method. If the
|
||||
method in question has been extended by a class derived from the proxy
|
||||
class, that extended implementation will execute exactly as it should.
|
||||
If not, the proxy class will route the method call into a C wrapper
|
||||
function, expecting that the method will be resolved in C++. The wrapper
|
||||
will call the virtual method of the C++ instance, and since the director
|
||||
extends this the call will end up right back in the director method. Now
|
||||
comes the "good reason not to" part. If the director method were to blindly
|
||||
call the PHP method again, it would get stuck in an infinite loop. We avoid this
|
||||
situation by adding special code to the C wrapper function that tells
|
||||
the director method to not do this. The C wrapper function compares the
|
||||
called and the declaring class name of the given method. If these are
|
||||
not the same, then the C wrapper function tells the director to resolve
|
||||
the method by calling up the C++ inheritance chain, preventing an
|
||||
infinite loop.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
One more point needs to be made about the relationship between director
|
||||
classes and proxy classes. When a proxy class instance is created in
|
||||
PHP, SWIG creates an instance of the original C++ class and assigns it
|
||||
to <tt>->_cPtr</tt>. This is exactly what happens without directors
|
||||
and is true even if directors are enabled for the particular class in
|
||||
question. When a class <i>derived</i> from a proxy class is created,
|
||||
however, SWIG then creates an instance of the corresponding C++ director
|
||||
class. The reason for this difference is that user-defined subclasses
|
||||
may override or extend methods of the original class, so the director
|
||||
class is needed to route calls to these methods correctly. For
|
||||
unmodified proxy classes, all methods are ultimately implemented in C++
|
||||
so there is no need for the extra overhead involved with routing the
|
||||
calls through PHP.
|
||||
</p>
|
||||
|
||||
<H3><a name="Php_nn3_3"></a>29.3.3 Ownership and object destruction</H3>
|
||||
|
||||
|
||||
<p>
|
||||
Memory management issues are slightly more complicated with directors
|
||||
than for proxy classes alone. PHP instances hold a pointer to the
|
||||
associated C++ director object, and the director in turn holds a pointer
|
||||
back to the PHP object. By default, proxy classes own their C++ director
|
||||
object and take care of deleting it when they are garbage collected.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
This relationship can be reversed by calling the special
|
||||
<tt>->thisown</tt> property of the proxy class. After setting this
|
||||
property to <tt>0</tt>, the director class no longer destroys the PHP
|
||||
object. Assuming no outstanding references to the PHP object remain,
|
||||
the PHP object will be destroyed at the same time. This is a good thing,
|
||||
since directors and proxies refer to each other and so must be created
|
||||
and destroyed together. Destroying one without destroying the other will
|
||||
likely cause your program to segfault.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Here is an example:
|
||||
</p>
|
||||
|
||||
<div class="code">
|
||||
<pre>
|
||||
class Foo {
|
||||
public:
|
||||
...
|
||||
};
|
||||
class FooContainer {
|
||||
public:
|
||||
void addFoo(Foo *);
|
||||
...
|
||||
};
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
<br>
|
||||
|
||||
<div class="targetlang">
|
||||
<pre>
|
||||
$c = new FooContainer();
|
||||
$a = new Foo();
|
||||
$a->thisown = 0;
|
||||
$c->addFoo($a);
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
<p>
|
||||
In this example, we are assuming that FooContainer will take care of
|
||||
deleting all the Foo pointers it contains at some point.
|
||||
</p>
|
||||
|
||||
<H3><a name="Php_nn3_4"></a>29.3.4 Exception unrolling</H3>
|
||||
|
||||
|
||||
<p>
|
||||
With directors routing method calls to PHP, and proxies routing them
|
||||
to C++, the handling of exceptions is an important concern. By default, the
|
||||
directors ignore exceptions that occur during method calls that are
|
||||
resolved in PHP. To handle such exceptions correctly, it is necessary
|
||||
to temporarily translate them into C++ exceptions. This can be done with
|
||||
the %feature("director:except") directive. The following code should
|
||||
suffice in most cases:
|
||||
</p>
|
||||
|
||||
<div class="code">
|
||||
<pre>
|
||||
%feature("director:except") {
|
||||
if ($error == FAILURE) {
|
||||
throw Swig::DirectorMethodException();
|
||||
}
|
||||
}
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
<p>
|
||||
This code will check the PHP error state after each method call from a
|
||||
director into PHP, and throw a C++ exception if an error occurred. This
|
||||
exception can be caught in C++ to implement an error handler.
|
||||
Currently no information about the PHP error is stored in the
|
||||
Swig::DirectorMethodException object, but this will likely change in the
|
||||
future.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
It may be the case that a method call originates in PHP, travels up to
|
||||
C++ through a proxy class, and then back into PHP via a director method.
|
||||
If an exception occurs in PHP at this point, it would be nice for that
|
||||
exception to find its way back to the original caller. This can be done
|
||||
by combining a normal %exception directive with the
|
||||
<tt>director:except</tt> handler shown above. Here is an example of a
|
||||
suitable exception handler:
|
||||
</p>
|
||||
|
||||
<div class="code">
|
||||
<pre>
|
||||
%exception {
|
||||
try { $action }
|
||||
catch (Swig::DirectorException &e) { SWIG_fail; }
|
||||
}
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
<p>
|
||||
The class Swig::DirectorException used in this example is actually a
|
||||
base class of Swig::DirectorMethodException, so it will trap this
|
||||
exception. Because the PHP error state is still set when
|
||||
Swig::DirectorMethodException is thrown, PHP will register the exception
|
||||
as soon as the C wrapper function returns.
|
||||
</p>
|
||||
|
||||
<H3><a name="Php_nn3_5"></a>29.3.5 Overhead and code bloat</H3>
|
||||
|
||||
|
||||
<p>
|
||||
Enabling directors for a class will generate a new director method for
|
||||
every virtual method in the class' inheritance chain. This alone can
|
||||
generate a lot of code bloat for large hierarchies. Method arguments
|
||||
that require complex conversions to and from target language types can
|
||||
result in large director methods. For this reason it is recommended that
|
||||
you selectively enable directors only for specific classes that are
|
||||
likely to be extended in PHP and used in C++.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Compared to classes that do not use directors, the call routing in the
|
||||
director methods does add some overhead. In particular, at least one
|
||||
dynamic cast and one extra function call occurs per method call from
|
||||
PHP. Relative to the speed of PHP execution this is probably completely
|
||||
negligible. For worst case routing, a method call that ultimately
|
||||
resolves in C++ may take one extra detour through PHP in order to ensure
|
||||
that the method does not have an extended PHP implementation. This could
|
||||
result in a noticeable overhead in some cases.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Although directors make it natural to mix native C++ objects with PHP
|
||||
objects (as director objects) via a common base class pointer, one
|
||||
should be aware of the obvious fact that method calls to PHP objects
|
||||
will be much slower than calls to C++ objects. This situation can be
|
||||
optimized by selectively enabling director methods (using the %feature
|
||||
directive) for only those methods that are likely to be extended in PHP.
|
||||
</p>
|
||||
|
||||
<H3><a name="Php_nn3_6"></a>29.3.6 Typemaps</H3>
|
||||
|
||||
|
||||
<p>
|
||||
Typemaps for input and output of most of the basic types from director
|
||||
classes have been written. These are roughly the reverse of the usual
|
||||
input and output typemaps used by the wrapper code. The typemap
|
||||
operation names are 'directorin', 'directorout', and 'directorargout'.
|
||||
The director code does not currently use any of the other kinds of
|
||||
typemaps. It is not clear at this point which kinds are appropriate and
|
||||
need to be supported.
|
||||
</p>
|
||||
|
||||
|
||||
<H3><a name="Php_nn3_7"></a>29.3.7 Miscellaneous</H3>
|
||||
|
||||
|
||||
<p> Director typemaps for STL classes are mostly in place, and hence you
|
||||
should be able to use std::string, etc., as you would any other type.
|
||||
</p>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
|
|
|
|||
Some files were not shown because too many files have changed in this diff Show more
Loading…
Reference in a new issue