diff --git a/CCache/Makefile.in b/CCache/Makefile.in
index ec55ccaf5..ef20f48a0 100644
--- a/CCache/Makefile.in
+++ b/CCache/Makefile.in
@@ -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:
diff --git a/CHANGES b/CHANGES
index d9426512b..509484e2f 100644
--- a/CHANGES
+++ b/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
-
+Please also read the Debugging Functions section in SWIG Parse Tree Handling for the Swig_print_node(), Swig_print_tree() and Swig_print_tags() 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.
+
@@ -251,8 +251,8 @@ and other details. The command line option -dump_tree produces output
diff --git a/Doc/Manual/Arguments.html b/Doc/Manual/Arguments.html
index af8780452..8ab51faf6 100644
--- a/Doc/Manual/Arguments.html
+++ b/Doc/Manual/Arguments.html
@@ -30,8 +30,6 @@
-Disclaimer: This chapter is under construction.
-
In Chapter 3, SWIG's treatment of basic datatypes and pointers was
described. In particular, primitive types such as int and
@@ -351,7 +349,7 @@ function like this in an interface file :
Support for type attributes.
The 'imtype' and 'cstype' typemaps can have an optional inattributes and outattributes typemap attribute.
-There are C# attributes and typemap attributes, don't get confused!!
+The 'imtype' typemap can also have an optional directorinattributes and directoroutattributes
+typemap attribute which attaches to director delegates, an implementation detail of directors, see directors implementation.
+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# MarshalAs 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.
+The directorinattributes and directoroutattributes typemap attribute are attached to the delegates in the director class, for example, the SwigDelegateBase_0
+
-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 %csattributes feature, see %feature directives.
Note that C# attributes are attached to proxy classes and enums using the csattributes typemap.
For example, imagine we have a custom attribute class, ThreadSafeAttribute, 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.
+An example for attaching attributes to the enum and enum values is shown below.
+
+which will result in the following C# enum:
+ { 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
-(String *)((DohBase *)s)->data
+(struct String *)((DohBase *)s)->data
The underlying char * string can be displayed with
-((String *)((DohBase *)s)->data)->str
+(*(struct String *)(((DohBase *)s)->data)).str
-(String *)((DohBase *)t)->data
+(struct String *)((DohBase *)t)->data
The underlying char * string can be displayed with
-((String *)((DohBase *)t)->data)->str
+(*(struct String *)(((DohBase *)t)->data)).str
-((String *)((DohBase *)sc)->data)->str
+(*(struct String *)(((DohBase *)sc)->data)).str
or
(char *)sc
will work depending on whether the underlying type is really a String * or char *.
+
Copyright (C) 1999-2004 SWIG Development Team.
diff --git a/Doc/Devel/tree.html b/Doc/Devel/tree.html
index 64d9d197d..43ad191f6 100644
--- a/Doc/Devel/tree.html
+++ b/Doc/Devel/tree.html
@@ -218,10 +218,10 @@ The following functions are used to help debug SWIG parse trees.
Prints the tag-structure of the parse tree to standard output. node is the top-level parse tree node. prefix is
a string prefix thats added to the start of each line. Normally, you would specify the empty string or NIL for prefix.
-This function is called by the -dump_tags option to SWIG.
+This function is called by the -debug-tags option to SWIG.
-% 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,
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 -dump_tree produces output generated by this function.
+and other details.
Prints the same output as Swig_print_node() except that it also processes all of the siblings of node. This can
-be used to dump the entire parse tree to standard output. Use the command line option -dump_tree 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 -debug-module
+and -debug-top use this function to display the parse tree for a SWIG input file.
diff --git a/Doc/Manual/Allegrocl.html b/Doc/Manual/Allegrocl.html
index cc950db7c..cf70f6c27 100644
--- a/Doc/Manual/Allegrocl.html
+++ b/Doc/Manual/Allegrocl.html
@@ -14,7 +14,7 @@
17.1 Basics
-17.1.1 Running Swig
+17.1.1 Running SWIG
%module example
-%include typemaps.i
+%include "typemaps.i"
...
%{
extern void negate(double *);
diff --git a/Doc/Manual/CSharp.html b/Doc/Manual/CSharp.html
index 3e17ee7f1..324be63ec 100644
--- a/Doc/Manual/CSharp.html
+++ b/Doc/Manual/CSharp.html
@@ -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
Mixed DLL Loading Problem.
-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
Mono and Portable.NET.
@@ -99,6 +99,7 @@ namespace com.bloggs.widget {
...
}
+%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 };
+%}
+
+
+[System.ComponentModel.Description("Colours")]
+public enum Couleur {
+ [System.ComponentModel.Description("Red")]
+ Rouge,
+ Orange,
+ [System.ComponentModel.Description("Green")]
+ Vert
+}
+
+
-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.
@@ -378,13 +384,13 @@
-
+
+
@@ -1501,6 +1515,7 @@
+
@@ -1564,7 +1579,7 @@
-
+%exception {
+ try {
+ $action
+ }
+ catch (RangeError) {
+ ... handle error ...
+ }
+}
++How the exception is handled depends on the target language, for example, Python: +
+
%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;
}
}
-int Len(String_or_char *s) +int Len(const String_or_char *s)
-char *Char(String_or_char *s) +char *Char(const String_or_char *s)
-void Append(String *s, String_or_char *t) +void Append(String *s, const String_or_char *t)
-void Insert(String *s, int pos, String_or_char *t) +void Insert(String *s, int pos, const String_or_char *t)
-Object *Getattr(Hash *h, String_or_char *key) +Object *Getattr(Hash *h, const String_or_char *key)
-int Setattr(Hash *h, String_or_char *key, Object_or_char *val) +int Setattr(Hash *h, const String_or_char *key, const Object_or_char *val)
-int Delattr(Hash *h, String_or_char *key) +int Delattr(Hash *h, const String_or_char *key)
-int *Setitem(List *x, int n, Object_or_char *val) +int *Setitem(List *x, int n, const Object_or_char *val)
-void Append(List *x, Object_or_char *t) +void Append(List *x, const Object_or_char *t)
-void Insert(String *s, int pos, Object_or_char *t) +void Insert(String *s, int pos, const Object_or_char *t)
-File *NewFile(const char *filename, const char *mode) +File *NewFile(const char *filename, const char *mode, List *newfiles)
@@ -1922,7 +1925,7 @@ Adds a reference to ty.
-void SwigType_add_array(SwigType *ty, String_or_char *dim) +void SwigType_add_array(SwigType *ty, const String_or_char *size)
-void SwigType_add_qualifier(SwigType *ty, String_or_char *q) +void SwigType_add_qualifier(SwigType *ty, const String_or_char *q)
-void SwigType_add_memberpointer(SwigType *ty, String_or_char *cls) +void SwigType_add_memberpointer(SwigType *ty, const String_or_char *cls)
-String *SwigType_str(SwigType *ty, String_or_char *id = 0) +String *SwigType_str(SwigType *ty, const String_or_char *id = 0)
-String *SwigType_lstr(SwigType *ty, String_or_char *id = 0) +String *SwigType_lstr(SwigType *ty, const String_or_char *id = 0)
-String *SwigType_lcaststr(SwigType *ty, String_or_char *id = 0) +String *SwigType_lcaststr(SwigType *ty, const String_or_char *id = 0)
-String *SwigType_rcaststr(SwigType *ty, String_or_char *id = 0) +String *SwigType_rcaststr(SwigType *ty, const String_or_char *id = 0)
@@ -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.
-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.
-@@ -3247,7 +3256,226 @@ during this process, see the section on configuration files.
-+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. +
+ ++The regression testing is carried out by the SWIG test-suite. +The test-suite consists of numerous testcase interface files in the Examples/test-suite directory +as well as target language specific runtime tests in the Examples/test-suite/[lang] directory. +When a testcase is run, it will execute the following steps for each testcase: +
+ ++For example, the ret_by_value testcase consists of two components. +The first component is the Examples/test-suite/ret_by_value.i interface file. +The name of the SWIG module must always be the name of the testcase, so the ret_by_value.i interface file thus begins with: +
+ ++%module ret_by_value ++
+The testcase code will then follow the module declaration, +usually within a %inline %{ ... %} section for the majority of the tests. +
+ ++The second component is the optional runtime tests. +Any runtime tests are named using the following convention: [testcase]_runme.[ext], +where [testcase] is the testcase name and [ext] 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, +Examples/test-suite/java/ret_by_value_runme.java and +Examples/test-suite/python/ret_by_value_runme.py. +
+ ++The goal of the test-suite is to test as much as possible in a silent 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. +
+ ++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 earlier. +
+ ++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. +
+ ++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): +
+ ++make -k check-test-suite +
+To run the test-suite just for target language [lang], replace [lang] with one of csharp, java, perl5, python, ruby, tcl etc: +
+ ++make check-[lang]-test-suite +
+Note that if a runtime test is available, a message "(with run test)" is displayed when run. For example: +
+ ++$ 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 +
+The files generated on a previous run can be deleted using the clean targets, either the whole test-suite or for a particular language: +
+ ++make clean-test-suite +make clean-[lang]-test-suite +
+The test-suite can be run in a partialcheck 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: +
+ ++make partialcheck-test-suite +make partialcheck-[lang]-test-suite +
+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: +
+ ++make -j2 check-test-suite +make -j2 check-python-test-suite +make -j2 partialcheck-java-test-suite +
+The second group of commands are for running individual testcases and should be executed in the appropriate +target language directory, Examples/test-suite/[lang]. +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 [testcase] in the commands below with the name of the testcase. +
+ ++For a C language testcase, add the testcase under the C_TEST_CASES list in Examples/test-suite/common.mk and +execute individually as: +
++make -s [testcase].ctest +
+For a C++ language testcase, add the testcase under the CPP_TEST_CASES list in Examples/test-suite/common.mk and +execute individually as: +
++make -s [testcase].cpptest +
+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 Examples/test-suite/common.mk and +execute individually as: +
++make -s [testcase].multicpptest +
+To delete the generated files, execute: +
++make -s [testcase].clean +
+If you would like to see the exact commands being executed, drop the -s option: +
++make [testcase].ctest +make [testcase].cpptest +make [testcase].multicpptest +
+Some real examples of each: +
++make -s ret_by_value.clean +make -s ret_by_value.ctest +make -s bools.cpptest +make -s imports.multicpptest +
+Advanced usage of the test-suite facilitates running tools on some of the five stages. +The make variables SWIGTOOL and RUNTOOL are used to specify a tool to respectively, invoke SWIG +and the execution of the runtime test. +You are advised to view the Examples/test-suite/common.mk file for details but for a short summary, +the classic usage is to use Valgrind for memory checking. +For example, checking for memory leaks when running the runtime test in the target language interpreter: +
+ ++make ret_by_value.ctest RUNTOOL="valgrind --leak-check=full" +
+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: +
+ ++make ret_by_value.ctest SWIGTOOL="valgrind --tool=memcheck --trace-children=yes" +
@@ -3279,7 +3507,7 @@ Some topics that you'll want to be sure to address include: if available. -
@@ -3336,7 +3564,7 @@ should be added should there be an area not already covered by the existing tests.
-@@ -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.
-+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: +
++-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 +
+The complete list of command line options for SWIG are available by running swig -help. +
+There is further documentation available on the internals of SWIG, API documentation and debugging information. +This is shipped with SWIG in the Doc/Devel directory. +
diff --git a/Doc/Manual/Guile.html b/Doc/Manual/Guile.html index cf7e8da2c..61b5ba7d6 100644 --- a/Doc/Manual/Guile.html +++ b/Doc/Manual/Guile.html @@ -814,7 +814,7 @@ Produces the following code at the top of the generated GOOPS guile-moduleModule-primitive.scm (with primitive replaced with whatever is given with the -primsuffix
argument. The code to load the .so library should be located in the %scheme directive,
which will then be added to the scmstub file.
-Swig will automatically generate the line (use-modules (Package Module-primitive))
+SWIG will automatically generate the line (use-modules (Package Module-primitive))
into the GOOPS guile-module. So if Module-primitive.scm is on the autoload path for guile, the
%goops directive can be empty. Otherwise, the %goops directive should contain
whatever code is needed to load the Module-primitive.scm file into guile.
@@ -848,7 +848,7 @@ Produces the following code at the top of the generated GOOPS guile-module
Module Linkage: This is very similar to passive linkage with a scmstub file.
-Swig will also automatically generate the line (use-modules
+SWIG will also automatically generate the line (use-modules
(Package Module-primitive)) into the GOOPS guile-module. Again the %goops
directive should contain whatever code is needed to get that module loaded into guile.
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.
diff --git a/Doc/Manual/Java.html b/Doc/Manual/Java.html index a19cc5e84..7869c5269 100644 --- a/Doc/Manual/Java.html +++ b/Doc/Manual/Java.html @@ -253,6 +253,12 @@ To change this, you can use the -o option. It is also possible to change the output directory that the Java files are generated into using -outdir.
++The module name, specified with %module, determines the name of various generated classes as discussed later. +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 -package option described below can specify a Java package name to use. +
+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 @@ $
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: +
+ ++$ 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) +
+where gcd 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 java -verbose:jni 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 -outdir to specify a package directory swig -java -package com.bloggs.swig -outdir com/bloggs/swig example.i
SWIG won't create the directory, so make sure it exists beforehand. +
-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.
-char *cdata(void *ptr, int nbytes) +const char *cdata(void *ptr, size_t nbytes)
@@ -676,7 +676,7 @@ pointer.
-void memmove(void *ptr, char *s) +void memmove(void *ptr, const char *s)
@@ -890,7 +890,10 @@ char *foo();
-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 char * so that the memory is released, +however, you may need to provide your own "newfree" typemap for other types. +See Object ownership and %newobject for more details.
-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).
To fix this, you either need to ignore or rename one of the methods. For example: diff --git a/Doc/Manual/Modules.html b/Doc/Manual/Modules.html index 5ac66dc2e..406bdeaef 100644 --- a/Doc/Manual/Modules.html +++ b/Doc/Manual/Modules.html @@ -10,6 +10,7 @@
+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. +
+ ++The module name can be supplied in one of two ways. +The first is to specify it with the special %module +directive. This directive must appear at the beginning of the interface file. +The general form of this directive is: +
+ ++%module(option1="value1",option2="value2",...) modulename +
+where the modulename is mandatory and the options add one or more optional additional features. +Typically no options are specified, for example: +
+ ++%module mymodule +
+The second way to specify the module name is with the -module command line option, for example -module mymodule. +If the module name is supplied on the command line, it overrides the name specified by the +%module directive. +
+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.
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.
-@@ -98,7 +138,7 @@ base class's methods. Typically you will get a warning when the module name is m
-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.
@@ -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.
-As described in The run-time type checker, @@ -238,7 +278,7 @@ SWIG_TYPE_TABLE to be the same as the module whose types you are trying to access.
-@@ -249,7 +289,7 @@ into it. This is very often NOT 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.
-@@ -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.
-diff --git a/Doc/Manual/Ocaml.html b/Doc/Manual/Ocaml.html index 6dbf24c11..b65831192 100644 --- a/Doc/Manual/Ocaml.html +++ b/Doc/Manual/Ocaml.html @@ -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"
-To build a Perl5 module, run Swig using the -perl option as +To build a Perl5 module, run SWIG using the -perl option as follows :
@@ -264,7 +264,7 @@ extern int fact(int); %} // Include code for rebuilding Perl -%include perlmain.i +%include <perlmain.i>@@ -815,7 +815,7 @@ extern char *path; // Declared later in the input
-Constants are wrapped as read-only Perl variables. For example: +By default, constants are wrapped as read-only Perl variables. For example:
+Alternatively, if you use swig's -const 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: +
+ ++use example; +print example::FOO,"\n"; ++
-To create a NULL pointer, you should pass the undef value to +To create a NULL pointer, you should pass the undef value to a function.
@@ -889,7 +902,7 @@ pointer that SWIG wrapper functions return. Suppose that $a and $b are two references that point to the same C object. In general, $a and $b will be different--since they are different references. Thus, it is a mistake to check the equality -of $a and $b to check the equality of two C +of $a and $b to check the equality of two C pointers. The correct method to check equality of C pointers is to dereference them as follows : @@ -1543,7 +1556,7 @@ example:%module example -%include typemaps.i +%include "typemaps.i" void add(int x, int y, int *REFERENCE);@@ -1567,7 +1580,7 @@ print "$c\n"; Note: The REFERENCE feature is only currently supported for numeric types (integers and floating point). -
@@ -2107,7 +2120,7 @@ might look at the files "perl5.swg" and "typemaps.i" in the SWIG library.
-@@ -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
@@ -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 %OWNER hash. This is -done using the DISOWN method. +done using the DISOWN method.
diff --git a/Doc/Manual/Php.html b/Doc/Manual/Php.html index 6e87a29a2..b9dcb83c5 100644 --- a/Doc/Manual/Php.html +++ b/Doc/Manual/Php.html @@ -32,16 +32,22 @@
-Caution: This chapter (and module!) is still under construction -
-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.
-Swig can generate PHP extensions from C++ libraries as well when +SWIG can generate PHP extensions from C++ libraries as well when given the -c++ option. The support for C++ is discussed in more detail in section 27.2.6.
@@ -479,7 +485,7 @@ One can include cpointer.i to generate PHP wrappers to int%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.%module example -%include typemaps.i +%include "typemaps.i" void add( int *INPUT, int *INPUT, int *OUTPUT); @@ -545,7 +551,7 @@ named typemap REFERENCE.%module example -%include phppointers.i +%include "phppointers.i" void add( int *REF, int *REF, int *REF); @@ -866,5 +872,381 @@ The %rinit and %rshutdown statements insert code into the request init and shutdown code respectively. +29.3 Cross language polymorphism
+ + ++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. +
+ ++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. +
+ ++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. +
+ +29.3.1 Enabling directors
+ + ++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: +
+ +++ ++%module(directors="1") modulename +++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: +
+ +++ ++// 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; +++You can use the %feature("nodirector") directive to turn off +directors for specific classes or methods. So for example, +
+ +++ ++%feature("director") Foo; +%feature("nodirector") Foo::bar; +++will generate directors for all virtual methods of class Foo except +bar(). +
+ ++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()): +
+ +++ ++%feature("director") Foo; +class Foo { +public: + Foo(int foo); + virtual void one(); + virtual void two(); +}; + +class Bar: public Foo { +public: + virtual void three(); +}; +++then at the PHP side you can define +
+ +++ + ++require("mymodule.php"); + +class MyFoo extends Foo { + function one() { + print "one from php\n"; + } +} ++29.3.2 Director classes
+ + + + + ++For each class that has directors enabled, SWIG generates a new class +that derives from both the class in question and a special +Swig::Director 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. +
+ ++For simplicity let's ignore the Swig::Director 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. +
+ ++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). +
+ ++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. +
+ ++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 ->_cPtr. This is exactly what happens without directors +and is true even if directors are enabled for the particular class in +question. When a class derived 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. +
+ +29.3.3 Ownership and object destruction
+ + ++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. +
+ ++This relationship can be reversed by calling the special +->thisown property of the proxy class. After setting this +property to 0, 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. +
+ ++Here is an example: +
+ +++ ++class Foo { +public: + ... +}; +class FooContainer { +public: + void addFoo(Foo *); + ... +}; ++
+ +++ ++$c = new FooContainer(); +$a = new Foo(); +$a->thisown = 0; +$c->addFoo($a); +++In this example, we are assuming that FooContainer will take care of +deleting all the Foo pointers it contains at some point. +
+ +29.3.4 Exception unrolling
+ + ++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: +
+ +++ ++%feature("director:except") { + if ($error == FAILURE) { + throw Swig::DirectorMethodException(); + } +} +++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. +
+ ++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 +director:except handler shown above. Here is an example of a +suitable exception handler: +
+ +++ ++%exception { + try { $action } + catch (Swig::DirectorException &e) { SWIG_fail; } +} +++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. +
+ +29.3.5 Overhead and code bloat
+ + ++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++. +
+ ++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. +
+ ++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. +
+ +29.3.6 Typemaps
+ + ++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. +
+ + +29.3.7 Miscellaneous
+ + +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. +
+