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

Another merge with master.

Browse source 
Updated Doxygen error numbers yet again, as Python errors got added in the
meanwhile, pushing the Doxygen ones further off.

And re-merged PEP8/whitespace-related conflicts in autodoc_runme.py once again
(if anybody is looking for a motivating example about why significant
whitespace is bad, here is a great use case).
This commit is contained in:
Vadim Zeitlin 2015-07-20 00:40:32 +02:00
commit 302955a152
448 changed files with 8836 additions and 5079 deletions
Download patch file Download diff file Expand all files Collapse all files

58
Doc/Manual/CSharp.html
View file

@ -12,6 +12,7 @@
<li><a href="#CSharp_introduction">Introduction</a>
<ul>
<li><a href="#CSharp_introduction_swig2_compatibility">SWIG 2 Compatibility</a>
<li><a href="#CSharp_commandline">Additional command line options</a>
</ul>
<li><a href="#CSharp_differences_java">Differences to the Java module</a>
<li><a href="#CSharp_void_pointers">Void pointers</a>
@ -34,7 +35,7 @@
<li><a href="#CSharp_directors_implementation">Directors implementation</a>
<li><a href="#CSharp_director_caveats">Director caveats</a>
</ul>
<li><a href="#CSharp_multiple_modules">Multiples modules</a>
<li><a href="#CSharp_multiple_modules">Multiple modules</a>
<li><a href="#CSharp_typemap_examples">C# Typemap examples</a>
<ul>
<li><a href="#CSharp_memory_management_member_variables">Memory management when returning references to member variables</a>
@ -79,6 +80,59 @@ Monodoc, available from the Mono project, has a very useful section titled <a hr
In order to minimize name collisions between names generated based on input to SWIG and names used in the generated code from the .NET framework, SWIG 3 fully qualifies the use of all .NET types. Furthermore, SWIG 3 avoids <tt>using</tt> directives in generated code. This breaks backwards compatibility with typemaps, pragmas, etc written for use with SWIG 2 that assume the presence of <tt>using System;</tt> or <tt>using System.Runtime.InteropServices;</tt> directives in the intermediate class imports, module imports, or proxy imports. SWIG 3 supports backwards compatibility though the use of the <tt>SWIG2_CSHARP</tt> macro. If <tt>SWIG2_CSHARP</tt> is defined, SWIG 3 generates <tt>using</tt> directives in the intermediate class, module class, and proxy class code similar to those generated by SWIG 2. This can be done without modifying any of the input code by passing the <tt>-DSWIG2_CSHARP</tt> commandline parameter when executing <tt>swig</tt>.
</p>
<H3><a name="CSharp_commandline"></a>20.1.2 Additional command line options</H3>
<p>
The following table lists the additional commandline options available for the C# module. They can also be seen by using:
</p>
<div class="code"><pre>
swig -csharp -help
</pre></div>
<table summary="C# specific options">
<tr>
<th>C# specific options</th>
</tr>
<tr>
<td>-dllimport &lt;dl&gt;</td>
<td>Override DllImport attribute name to &lt;dl&gt;</td>
</tr>
<tr>
<td>-namespace &lt;nm&gt;</td>
<td>Generate wrappers into C# namespace &lt;nm&gt;</td>
</tr>
<tr>
<td>-noproxy</td>
<td>Generate the low-level functional interface instead of proxy classes</td>
</tr>
<tr>
<td>-oldvarnames</td>
<td>Old intermediary method names for variable wrappers</td>
</tr>
<tr>
<td>-outfile &lt;file&gt;</td>
<td>Write all C# into a single &lt;file&gt; located in the output directory
</td>
</tr>
</table>
<p>
The -outfile option combines all the generated C# code into a single output file instead of creating multiple C# files.
The default, when this option is not provided, is to generate separate .cs files for the module class,
intermediary class and each of the generated proxy and type wrapper classes.
Note that the file extension (.cs) will not be automatically added and needs to be provided.
Due to possible compiler limits it is not advisable to use <tt>-outfile</tt> for large projects.
</p>
<H2><a name="CSharp_differences_java"></a>20.2 Differences to the Java module</H2>
@ -1682,7 +1736,7 @@ However, a call from C# to <tt>CSharpDefaults.DefaultMethod()</tt> will of cours
should pass the call on to <tt>CSharpDefaults.DefaultMethod(int)</tt>using the C++ default value, as shown above.
</p>
<H2><a name="CSharp_multiple_modules"></a>20.7 Multiples modules</H2>
<H2><a name="CSharp_multiple_modules"></a>20.7 Multiple modules</H2>
<p>

8
Doc/Manual/Contents.html
View file

@ -725,6 +725,7 @@
<li><a href="CSharp.html#CSharp_introduction">Introduction</a>
<ul>
<li><a href="CSharp.html#CSharp_introduction_swig2_compatibility">SWIG 2 Compatibility</a>
<li><a href="CSharp.html#CSharp_commandline">Additional command line options</a>
</ul>
<li><a href="CSharp.html#CSharp_differences_java">Differences to the Java module</a>
<li><a href="CSharp.html#CSharp_void_pointers">Void pointers</a>
@ -747,7 +748,7 @@
<li><a href="CSharp.html#CSharp_directors_implementation">Directors implementation</a>
<li><a href="CSharp.html#CSharp_director_caveats">Director caveats</a>
</ul>
<li><a href="CSharp.html#CSharp_multiple_modules">Multiples modules</a>
<li><a href="CSharp.html#CSharp_multiple_modules">Multiple modules</a>
<li><a href="CSharp.html#CSharp_typemap_examples">C# Typemap examples</a>
<ul>
<li><a href="CSharp.html#CSharp_memory_management_member_variables">Memory management when returning references to member variables</a>
@ -1074,7 +1075,7 @@
</ul>
<li><a href="Javascript.html#Javascript_applications_webkit">Creating Applications with node-webkit</a>
</ul>
<li><a href="Javascript.html#Javascript_nn14">Examples</a>
<li><a href="Javascript.html#Javascript_examples">Examples</a>
<ul>
<li><a href="Javascript.html#Javascript_simple_example">Simple</a>
<li><a href="Javascript.html#Javascript_class_example">Class</a>
@ -1529,6 +1530,7 @@
<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_default_args">Default arguments</a>
</ul>
<li><a href="Python.html#Python_nn53">Typemaps</a>
<ul>
@ -1762,7 +1764,7 @@
<li><a href="Scilab.html#Scilab_wrapping_pointers_null_pointers">Null pointers</a>
</ul>
<li><a href="Scilab.html#Scilab_wrapping_structs">Structures</a>
<li><a href="Scilab.html#Scilab_wrapping_cpp_classes">C++ Classes</a>
<li><a href="Scilab.html#Scilab_wrapping_cpp_classes">C++ classes</a>
<li><a href="Scilab.html#Scilab_wrapping_cpp_inheritance">C++ inheritance</a>
<li><a href="Scilab.html#Scilab_wrapping_pointers_references_values_arrays">Pointers, references, values, and arrays</a>
<li><a href="Scilab.html#Scilab_wrapping_cpp_templates">C++ templates</a>

198
Doc/Manual/Go.html
View file

@ -111,6 +111,14 @@ swig -go -help
<th>Go specific options</th>
</tr>
<tr>
<td>-cgo</td>
<td>Generate files to be used as input for the Go cgo tool. This
option is required for Go 1.5 and later, and works for Go 1.2 and
later. In the future this option will likely become the
default.</td>
</tr>
<tr>
<td>-intgosize &lt;s&gt;</td>
<td>Set the size for the Go type <tt>int</tt>. This controls the size
@ -171,8 +179,13 @@ swig -go -help
<H3><a name="Go_outputs"></a>23.3.2 Go Output Files</H3>
<p> When generating Go code, SWIG will generate the following
files:</p>
<p>There are two different approaches to generating output files,
controlled by SWIG's <tt>-cgo</tt> option. The <tt>-cgo</tt> option
works with Go version 1.2 or later. It is required when using Go
version 1.5 or later.</p>
<p>With or without the <tt>-cgo</tt> option, SWIG will generate the
following files when generating Go code:</p>
<ul>
<li>
@ -180,21 +193,30 @@ MODULE.go will contain the Go functions that your Go code will call.
These functions will be wrappers for the C++ functions defined by your
module. This file should, of course, be compiled with the Go
compiler.
</li>
<li>
MODULE_wrap.c or MODULE_wrap.cxx will contain C/C++ functions will be
invoked by the Go wrapper code. This file should be compiled with the
usual C or C++ compiler and linked into a shared library.
usual C or C++ compiler.
</li>
<li>
MODULE_wrap.h will be generated if you use the directors feature. It
provides a definition of the generated C++ director classes. It is
generally not necessary to use this file, but in some special cases it
may be helpful to include it in your code, compiled with the usual C
or C++ compiler.
</li>
</ul>
<p>When neither the <tt>-cgo</tt> nor the <tt>-gccgo</tt> option is
used, SWIG will also generate an additional file:</p>
<ul>
<li>
If using the gc compiler, MODULE_gc.c will contain C code which should
be compiled with the C compiler distributed as part of the gc
compiler. It should then be combined with the compiled MODULE.go
using gopack. This file will not be generated when using gccgo.
MODULE_gc.c will contain C code which should be compiled with the C
compiler distributed as part of the gc compiler. It should then be
combined with the compiled MODULE.go using go tool pack.
</li>
</ul>
<p>
@ -203,14 +225,33 @@ support for SWIG. To use it, put your SWIG interface into a file with
the extension .swig, or, if you are wrapping C++ code, .swigcxx. Put
that file in a GOPATH/src directory as usual for Go sources. Put
other interface code in the same directory with extensions of .c and
.cxx. The go build command and go install commands will automatically
run SWIG for you and will build the interface code.
.cxx. The <tt>go build</tt> and <tt>go install</tt> commands will
automatically run SWIG for you and will build the interface code.
</p>
<p>
You can also use SWIG directly yourself. When using the gc compiler
version 1.2 or later, or when using gccgo, the code generated by SWIG
can be linked directly into the Go program. A typical command
You can also use SWIG directly yourself. When using
the <tt>-cgo</tt> option, SWIG will generate files that can be used
directly by <tt>go build</tt>. Put your SWIG input file in a
directory under GOPATH/src, and give it a name that does not end in
.swig or .swigcxx.
</p>
<div class="code"><pre>
% swig -go -cgo example.i
% go install
</pre></div>
<p>
You will now have a Go package that you can import from other Go
packages as usual.
</p>
<p>
To use SWIG without the <tt>-cgo</tt> option, more steps are required.
Recall that this only works with Go versions before 1.5. When using
Go version 1.2 or later, or when using gccgo, the code generated by
SWIG can be linked directly into the Go program. A typical command
sequence when using the gc compiler would look like this:
</p>
@ -227,9 +268,8 @@ sequence when using the gc compiler would look like this:
<p>
You can also put the wrapped code into a shared library, and when
using the gc compiler before version 1.2 this is the only supported
option. A typical command sequence for this approach would look like
this:
using the Go versions before 1.2 this is the only supported option. A
typical command sequence for this approach would look like this:
</p>
<div class="code"><pre>
@ -396,34 +436,120 @@ for this by calling the Swigcptr() method.
<p>
Calling <tt>NewClassName</tt> for some C++ class <tt>ClassName</tt>
will allocate memory using the C++ memory allocator. This memory will
not be automatically freed by Go's garbage collector as the object ownership is
not tracked. When you are done with the C++ object you must free it manually
using <tt>DeleteClassName</tt>.
</p>
<p>
A common technique is to store the C++ object into a Go object, and
use the Go function <tt>runtime.SetFinalizer</tt> to free the C++ object when
the Go object is freed. It is strongly recommended to read the
<a href="https://golang.org/pkg/runtime/#SetFinalizer">runtime.SetFinalizer</a>
documentation before using this technique to understand its limitations.
For example, if the SWIG package is imported as "wrap":
Calling <tt>NewClassName</tt> for a C++ class <tt>ClassName</tt> will allocate
memory using the C++ memory allocator. This memory will not be automatically
freed by Go's garbage collector as the object ownership is not tracked. When
you are done with the C++ object you must free it using
<tt>DeleteClassName</tt>.<br>
<br>
The most Go idiomatic way to manage the memory for some C++ class is to call
<tt>NewClassName</tt> followed by a
<tt><a href="https://golang.org/doc/effective_go.html#defer">defer</a></tt> of
the <tt>DeleteClassName</tt> call. Using <tt>defer</tt> ensures that the memory
of the C++ object is freed as soon as the function containing the <tt>defer</tt>
statement returns. Furthemore <tt>defer</tt> works great for short-lived
objects and fits nicely C++'s RAII idiom. Example:
</p>
<div class="code">
<pre>
func UseClassName(...) ... {
o := NewClassName(...)
defer DeleteClassName(o)
// Use the ClassName object
return ...
}
</pre>
</div>
<p>
With increasing complexity, especially complex C++ object hierarchies, the
correct placement of <tt>defer</tt> statements becomes harder and harder as C++
objects need to be freed in the correct order. This problem can be eased by
keeping a C++ object function local so that it is only available to the function
that creates a C++ object and functions called by this function. Example:
</p>
<div class="code">
<pre>
func WithClassName(constructor args, f func(ClassName, ...interface{}) error, data ...interface{}) error {
o := NewClassName(constructor args)
defer DeleteClassName(o)
return f(o, data...)
}
func UseClassName(o ClassName, data ...interface{}) (err error) {
// Use the ClassName object and additional data and return error.
}
func main() {
WithClassName(constructor args, UseClassName, additional data)
}
</pre>
</div>
<p>
Using <tt>defer</tt> has limitations though, especially when it comes to
long-lived C++ objects whichs lifetimes are hard to predict. For such C++
objects a common technique is to store the C++ object into a Go object, and to
use the Go function <tt>runtime.SetFinalizer</tt> to add a finalizer which frees
the C++ object when the Go object is freed. It is strongly recommended to read
the <a href="https://golang.org/pkg/runtime/#SetFinalizer">runtime.SetFinalizer
</a> documentation before using this technique to understand the
<tt>runtime.SetFinalizer</tt> limitations.<br>
</p>
<p>
Common pitfalls with <tt>runtime.SetFinalizer</tt> are:
</p>
<ul>
<li>
If a hierarchy of C++ objects will be automatically freed by Go finalizers then
the Go objects that store the C++ objects need to replicate the hierarchy of the
C++ objects to prevent that C++ objects are freed prematurely while other C++
objects still rely on them.
</li>
<li>
The usage of Go finalizers is problematic with C++'s RAII idiom as it isn't
predictable when the finalizer will run and this might require a Close or Delete
method to be added the Go object that stores a C++ object to mitigate.
</li>
<li>
The Go finalizer function typically runs in a different OS thread which can be
problematic with C++ code that uses thread-local storage.
</li>
</ul>
<p>
<tt>runtime.SetFinalizer</tt> Example:
</p>
<div class="code">
<pre>
import (
"runtime"
"wrap" // SWIG generated wrapper code
)
type GoClassName struct {
w wrap.ClassName
wcn wrap.ClassName
}
func NewGoClassName() *GoClassName {
r := &amp;GoClassName{wrap.NewClassName()}
runtime.SetFinalizer(r,
func(r *GoClassName) {
wrap.DeleteClassName(r.w)
})
return r
o := &amp;GoClassName{wcn: wrap.NewClassName()}
runtime.SetFinalizer(o, deleteGoClassName)
return o
}
func deleteGoClassName(o *GoClassName) {
// Runs typically in a different OS thread!
wrap.DeleteClassName(o.wcn)
o.wcn = nil
}
func (o *GoClassName) Close() {
// If the C++ object has a Close method.
o.wcn.Close()
// If the GoClassName object is no longer in an usable state.
runtime.SetFinalizer(o, nil) // Remove finalizer.
deleteGoClassName() // Free the C++ object.
}
</pre>
</div>

6
Doc/Manual/Introduction.html
View file

@ -457,6 +457,12 @@ be used on any platform. Again, this is an important part of staying out
of the programmer's way----the last thing any developer wants to do is
to spend their time debugging the output of a tool that relies on
non-portable or unreliable programming features.
Dependencies are often a source of incompatibilities and problems and so
additional third party libraries are not used in the generated code.
SWIG will also generally avoid generating code that introduces a dependency
on the C++ Standard Template Library (STL).
SWIG will generate code that depends on the C libraries though.
</p>
</body>
</html>

8
Doc/Manual/Javascript.html
View file

@ -30,7 +30,7 @@
</ul>
<li><a href="#Javascript_applications_webkit">Creating Applications with node-webkit</a>
</ul>
<li><a href="#Javascript_nn14">Examples</a>
<li><a href="#Javascript_examples">Examples</a>
<ul>
<li><a href="#Javascript_simple_example">Simple</a>
<li><a href="#Javascript_class_example">Class</a>
@ -197,10 +197,10 @@ $ sudo npm install -g node-gyp</pre>
<pre>
$ swig -javascript -node -c++ example.i</pre>
</div>
<p>Then run <code>node-gyp</code></p>
<p>Then run <code>node-gyp build</code> to actually create the module:</p>
<div class="shell">
<pre>
$ node-gyp</pre>
$ node-gyp build</pre>
</div>
<p>This will create a <code>build</code> folder containing the native module. To use the extension you need to 'require' it in your Javascript source file:</p>
<div class="code">
@ -410,7 +410,7 @@ open new windows, and many more things.
};</pre>
</div>
<H2><a name="Javascript_nn14"></a>26.4 Examples</H2>
<H2><a name="Javascript_examples"></a>26.4 Examples</H2>
<p>Some basic examples are shown here in more detail.</p>

4
Doc/Manual/Library.html
View file

@ -1900,7 +1900,9 @@ Adding the missing <tt>%shared_ptr</tt> macros will fix this:
</div>
<p>
<b>Note:</b> There is currently no support for <tt>%shared_ptr</tt> and the director feature.
<b>Note:</b> There is somewhat limited support for <tt>%shared_ptr</tt> and the director feature
and the degress of success varies among the different target languages.
Please help to improve this support by providing patches with improvements.
</p>

2
Doc/Manual/Lua.html
View file

@ -891,7 +891,7 @@ void spam(short);
<p>
or
</p>
<DIV CLASS="CODE"><PRE>VOID FOO(bAR *B);
<div class="code"><pre>void foo(Bar *b);
void foo(Bar &amp;b);
</pre></div>
<p>

4
Doc/Manual/Modules.html
View file

@ -250,7 +250,9 @@ the functions <tt>SWIG_TypeQuery</tt>, <tt>SWIG_NewPointerObj</tt>, and others s
to be called. Calling these functions from a typemap is supported, since the typemap code
is embedded into the <tt>_wrap.c</tt> file, which has those declarations available. If you need
to call the SWIG run-time functions from another C file, there is one header you need
to include. To generate the header that needs to be included, run the following command:
to include. To generate the header that needs to be included, SWIG can be run in a different
mode via <tt>-external-runtime</tt> to generate the run-time instead of the normal mode of
processing an input interface file. For example:
<div class="shell"><pre>
$ swig -python -external-runtime &lt;filename&gt;

308
Doc/Manual/Ocaml.html
View file

@ -1,11 +1,11 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>SWIG and Ocaml</title>
<title>SWIG and Ocaml</title>
<link rel="stylesheet" type="text/css" href="style.css">
</head>
<body bgcolor="#ffffff">
<a name="n1"></a>
<body bgcolor="#ffffff">
<H1><a name="Ocaml"></a>31 SWIG and Ocaml</H1>
<!-- INDEX -->
<div class="sectiontoc">
@ -59,20 +59,23 @@
<p>
This chapter describes SWIG's
support of Ocaml. Ocaml is a relatively recent addition to the ML family,
and is a recent addition to SWIG. It's the second compiled, typed
language to be added. Ocaml has widely acknowledged benefits for engineers,
mostly derived from a sophisticated type system, compile-time checking
which eliminates several classes of common programming errors, and good
native performance. While all of this is wonderful, there are well-written
C and C++ libraries that Ocaml users will want to take advantage of as
part of their arsenal (such as SSL and gdbm), as well as their own mature
C and C++ code. SWIG allows this code to be used in a natural, type-safe
way with Ocaml, by providing the necessary, but repetitive glue code
which creates and uses Ocaml values to communicate with C and C++ code.
In addition, SWIG also produces the needed Ocaml source that binds
variants, functions, classes, etc.
This chapter describes SWIG's support of Ocaml.
</p>
<p>
Ocaml is a relatively recent addition to the ML family,
and is a recent addition to SWIG. It's the second compiled, typed
language to be added. Ocaml has widely acknowledged benefits for engineers,
mostly derived from a sophisticated type system, compile-time checking
which eliminates several classes of common programming errors, and good
native performance. While all of this is wonderful, there are well-written
C and C++ libraries that Ocaml users will want to take advantage of as
part of their arsenal (such as SSL and gdbm), as well as their own mature
C and C++ code. SWIG allows this code to be used in a natural, type-safe
way with Ocaml, by providing the necessary, but repetitive glue code
which creates and uses Ocaml values to communicate with C and C++ code.
In addition, SWIG also produces the needed Ocaml source that binds
variants, functions, classes, etc.
</p>
<p>
@ -84,17 +87,16 @@ If you're not familiar with the Objective Caml language, you can visit
<p>
SWIG 1.3 works with Ocaml 3.04 and above. Given the choice,
you should use the latest stable release. The SWIG Ocaml module has
been tested on Linux (x86,PPC,Sparc) and Cygwin on Windows. The
best way to determine whether your system will work is to compile the
examples and test-suite which come with SWIG. You can do this by running
<tt>make check</tt> from the SWIG root directory after installing SWIG.
The Ocaml module has been tested using the system's dynamic linking (the
usual -lxxx against libxxx.so, as well as with Gerd Stolpmann's
<a
href="http://download.camlcity.org/download/">Dl package
</a>. The ocaml_dynamic and ocaml_dynamic_cpp targets in the
SWIG 3.0 works with Ocaml 3.08.3 and above. Given the choice,
you should use the latest stable release. The SWIG Ocaml module has
been tested on Linux (x86,PPC,Sparc) and Cygwin on Windows. The
best way to determine whether your system will work is to compile the
examples and test-suite which come with SWIG. You can do this by running
<tt>make check</tt> from the SWIG root directory after installing SWIG.
The Ocaml module has been tested using the system's dynamic linking (the
usual -lxxx against libxxx.so, as well as with Gerd Stolpmann's
<a href="http://download.camlcity.org/download/">Dl package</a>.
The ocaml_dynamic and ocaml_dynamic_cpp targets in the
file Examples/Makefile illustrate how to compile and link SWIG modules that
will be loaded dynamically. This has only been tested on Linux so far.
</p>
@ -103,30 +105,30 @@ will be loaded dynamically. This has only been tested on Linux so far.
<p>
The basics of getting a SWIG Ocaml module up and running
can be seen from one of SWIG's example Makefiles, but is also described
here. To build an Ocaml module, run SWIG using the <tt>-ocaml</tt>
option.
The basics of getting a SWIG Ocaml module up and running
can be seen from one of SWIG's example Makefiles, but is also described
here. To build an Ocaml module, run SWIG using the <tt>-ocaml</tt>
option.
</p>
<div class="code">
<pre>
<div class="code">
<pre>
%swig -ocaml example.i
</pre>
</pre>
</div>
<p> This will produce 3 files. The file <tt>example_wrap.c</tt> contains
<p>This will produce 3 files. The file <tt>example_wrap.c</tt> contains
all of the C code needed to build an Ocaml module. To build the module,
you will compile the file <tt>example_wrap.c</tt> with <tt>ocamlc</tt> or
you will compile the file <tt>example_wrap.c</tt> with <tt>ocamlc</tt> or
<tt>ocamlopt</tt> to create the needed .o file. You will need to compile
the resulting .ml and .mli files as well, and do the final link with -custom
(not needed for native link). </p>
(not needed for native link).</p>
<H3><a name="Ocaml_nn4"></a>31.1.2 Compiling the code</H3>
<p>
The OCaml SWIG module now requires you to compile a module (<tt>Swig</tt>)
The OCaml SWIG module now requires you to compile a module (<tt>Swig</tt>)
separately. In addition to aggregating common SWIG functionality, the Swig
module contains the data structure that represents C/C++ values. This allows
easier data sharing between modules if two or more are combined, because
@ -134,28 +136,29 @@ the type of each SWIG'ed module's c_obj is derived from Swig.c_obj_t. This
also allows SWIG to acquire new conversions painlessly, as well as giving
the user more freedom with respect to custom typing.
Use <tt>ocamlc</tt> or <tt>ocamlopt</tt> to compile your
SWIG interface like:
Use <tt>ocamlc</tt> or <tt>ocamlopt</tt> to compile your SWIG interface like:
</p>
<div class="code">
<pre>
<div class="code">
<pre>
% swig -ocaml -co swig.mli ; swig -ocaml co swig.ml
% ocamlc -c swig.mli ; ocamlc -c swig.ml
% ocamlc -c -ccopt "-I/usr/include/foo" example_wrap.c
% ocamlc -c example.mli
% ocamlc -c example.ml
</pre>
</pre>
</div>
<p> <tt>ocamlc</tt> is aware of .c files and knows how to handle them. Unfortunately,
it does not know about .cxx, .cc, or .cpp files, so when SWIG is invoked
in C++ mode, you must: </p>
<div class="code">
<pre>
% cp example_wrap.cxx example_wrap.cxx.c<br>% ocamlc -c ... -ccopt -xc++ example_wrap.cxx.c<br>% ...<br>
</pre>
<p><tt>ocamlc</tt> is aware of .c files and knows how to handle them. Unfortunately,
it does not know about .cxx, .cc, or .cpp files, so when SWIG is invoked
in C++ mode, you must:</p>
<div class="code">
<pre>
% cp example_wrap.cxx example_wrap.cxx.c
% ocamlc -c ... -ccopt -xc++ example_wrap.cxx.c
% ...
</pre>
</div>
<H3><a name="Ocaml_nn5"></a>31.1.3 The camlp4 module</H3>
@ -165,8 +168,8 @@ the user more freedom with respect to custom typing.
The camlp4 module (swigp4.ml -&gt; swigp4.cmo) contains a simple rewriter which
makes C++ code blend more seamlessly with objective caml code. Its use is
optional, but encouraged. The source file is included in the Lib/ocaml
directory of the SWIG source distribution. You can checkout this file with
<tt>"swig -ocaml -co swigp4.ml"</tt>. You should compile the file with
directory of the SWIG source distribution. You can checkout this file with
<tt>"swig -ocaml -co swigp4.ml"</tt>. You should compile the file with
<tt>"ocamlc -I `camlp4 -where` -pp 'camlp4o pa_extend.cmo q_MLast.cmo' -c swigp4.ml"</tt>
</p>
@ -192,7 +195,7 @@ a '+= b</td>
<td>
(invoke object) "+=" argument as in<br>
(invoke a) "+=" b<td></tr>
<tr><th colspan=2>Note that because camlp4 always recognizes &lt;&lt;
<tr><th colspan=2>Note that because camlp4 always recognizes &lt;&lt;
and &gt;&gt;, they are replaced by lsl and lsr in operator names.
<tr><td>
<i>'unop</i> object as in<br>
@ -241,11 +244,11 @@ let b = C_string (getenv "PATH")
You can test-drive your module by building a
toplevel ocaml interpreter. Consult the ocaml manual for details.
</p>
<p>
When linking any ocaml bytecode with your module, use the -custom
option to build your functions into the primitive list. This
option is not needed when you build native code.
option to build your functions into the primitive list. This
option is not needed when you build native code.
</p>
<H3><a name="Ocaml_nn7"></a>31.1.5 Compilation problems and compiling with C++</H3>
@ -273,9 +276,9 @@ In the code as seen by the typemap
writer, there is a value, swig_result, that always contains the
current return data. It is a list, and must be appended with the
caml_list_append function, or with functions and macros provided by
objective caml.<br>
objective caml.
</p>
<div class="code"><pre>
type c_obj =
C_void
@ -299,66 +302,65 @@ type c_obj =
</pre></div>
<p>
A few functions exist which generate and return these:
A few functions exist which generate and return these:
</p>
<ul>
<li>caml_ptr_val receives a c_obj and returns a void *. &nbsp;This
should be used for all pointer purposes.</li>
<li>caml_long_val receives a c_obj and returns a long. &nbsp;This
should be used for most integral purposes.<br>
</li>
<li>caml_val_ptr receives a void * and returns a c_obj.</li>
<li>caml_val_bool receives a C int and returns a c_obj representing
its bool value.</li>
<li>caml_val_(u)?(char|short|int|long|float|double) receives an
appropriate C value and returns a c_obj representing it.</li>
<li>caml_val_string receives a char * and returns a string value.</li>
<li>caml_val_string_len receives a char * and a length and returns
a string value.</li>
<li>caml_val_obj receives a void * and an object type and returns
a C_obj, which contains a closure giving method access.</li>
<li>caml_ptr_val receives a c_obj and returns a void *. This
should be used for all pointer purposes.</li>
<li>caml_long_val receives a c_obj and returns a long. This
should be used for most integral purposes.</li>
<li>caml_val_ptr receives a void * and returns a c_obj.</li>
<li>caml_val_bool receives a C int and returns a c_obj representing
its bool value.</li>
<li>caml_val_(u)?(char|short|int|long|float|double) receives an
appropriate C value and returns a c_obj representing it.</li>
<li>caml_val_string receives a char * and returns a string value.</li>
<li>caml_val_string_len receives a char * and a length and returns
a string value.</li>
<li>caml_val_obj receives a void * and an object type and returns
a C_obj, which contains a closure giving method access.</li>
</ul>
<p>
Because of this style, a typemap can return any kind of value it
wants from a function. &nbsp;This enables out typemaps and inout typemaps
to work well. &nbsp;The one thing to remember about outputting values
is that you must append them to the return list with swig_result = caml_list_append(swig_result,v).
wants from a function. This enables out typemaps and inout typemaps
to work well. The one thing to remember about outputting values
is that you must append them to the return list with swig_result = caml_list_append(swig_result,v).
</p>
<p>
&nbsp;This function will return a new list that has your element
appended. Upon return to caml space, the fnhelper function
beautifies the result. A list containing a single item degrades to
only that item (i.e. [ C_int 3 ] -&gt; C_int 3), and a list
containing more than one item is wrapped in C_list (i.e. [ C_char
'a' ; C_char 'b' -&gt; C_list [ C_char 'a' ; C_char b
]). &nbsp;This is in order to make return values easier to handle
when functions have only one return value, such as constructors,
and operators. &nbsp;In addition, string, pointer, and object
values are interchangeable with respect to caml_ptr_val, so you can
allocate memory as caml strings and still use the resulting
pointers for C purposes, even using them to construct simple objects
on. Note, though, that foreign C++ code does not respect the garbage
collector, although the SWIG interface does.</p>
This function will return a new list that has your element
appended. Upon return to caml space, the fnhelper function
beautifies the result. A list containing a single item degrades to
only that item (i.e. [ C_int 3 ] -&gt; C_int 3), and a list
containing more than one item is wrapped in C_list (i.e. [ C_char
'a' ; C_char 'b' -&gt; C_list [ C_char 'a' ; C_char b
]). This is in order to make return values easier to handle
when functions have only one return value, such as constructors,
and operators. In addition, string, pointer, and object
values are interchangeable with respect to caml_ptr_val, so you can
allocate memory as caml strings and still use the resulting
pointers for C purposes, even using them to construct simple objects
on. Note, though, that foreign C++ code does not respect the garbage
collector, although the SWIG interface does.</p>
<p>
The wild card type that you can use in lots of different ways is
C_obj. It allows you to wrap any type of thing you like as an
object using the same mechanism that the ocaml module
does. &nbsp;When evaluated in caml_ptr_val, the returned value is
the result of a call to the object's "&amp;" operator, taken as a pointer.
</p>
<p>
You should only construct values using objective caml, or using the
functions caml_val_* functions provided as static functions to a SWIG
ocaml module, as well as the caml_list_* functions. These functions
provide everything a typemap needs to produce values. In addition,
value items pass through directly, but you must make your own type
signature for a function that uses value in this way.
</p>
<p>
The wild card type that you can use in lots of different ways is
C_obj. It allows you to wrap any type of thing you like as an
object using the same mechanism that the ocaml module
does. When evaluated in caml_ptr_val, the returned value is
the result of a call to the object's "&amp;" operator, taken as a pointer.
</p>
<p>
You should only construct values using objective caml, or using the
functions caml_val_* functions provided as static functions to a SWIG
ocaml module, as well as the caml_list_* functions. These functions
provide everything a typemap needs to produce values. In addition,
value items pass through directly, but you must make your own type
signature for a function that uses value in this way.
</p>
<H3><a name="Ocaml_nn9"></a>31.2.1 The generated module</H3>
@ -376,7 +378,7 @@ that the keywords are not the same as the C++ ones.
You can introduce extra code into the output wherever you like with SWIG.
These are the places you can introduce code:
<table border="1" summary="Extra code sections">
<tr><td>"header"</td><td>This code is inserted near the beginning of the
<tr><td>"header"</td><td>This code is inserted near the beginning of the
C wrapper file, before any function definitions.</td></tr>
<tr><td>"wrapper"</td><td>This code is inserted in the function definition
section.</td></tr>
@ -385,25 +387,25 @@ file.</td></tr>
<tr><td>"mli"</td><td>This code is inserted into the caml interface file.
Special signatures should be inserted here.
</td></tr>
<tr><td>"ml"</td><td>This code is inserted in the caml code defining the
<tr><td>"ml"</td><td>This code is inserted in the caml code defining the
interface to your C code. Special caml code, as well as any initialization
which should run when the module is loaded may be inserted here.
</td></tr>
</td></tr>
<tr><td>"classtemplate"</td><td>The "classtemplate" place is special because
it describes the output SWIG will generate for class definitions.
</td></tr>
</table>
<H3><a name="Ocaml_nn10"></a>31.2.2 Enums</H3>
<p>
SWIG will wrap enumerations as polymorphic variants in the output
Ocaml code, as above in C_enum.&nbsp; In order to support all
Ocaml code, as above in C_enum. In order to support all
C++-style uses of enums, the function int_to_enum and enum_to_int are
provided for ocaml code to produce and consume these values as
integers. &nbsp;Other than that, correct uses of enums will not have
a problem. &nbsp;Since enum labels may overlap between enums, the
integers. Other than that, correct uses of enums will not have
a problem. Since enum labels may overlap between enums, the
enum_to_int and int_to_enum functions take an enum type label as an
argument. Example:
</p>
@ -416,9 +418,9 @@ enum c_enum_type { a = 1, b, c = 4, d = 8 };
enum c_enum_type { a = 1, b, c = 4, d = 8 };
</pre></div>
<p>
<p>
The output mli contains:
</p>
</p>
<div class="code"><pre>
type c_enum_type = [
@ -435,16 +437,16 @@ type c_enum_tag = [
val int_to_enum c_enum_type -&gt; int -&gt; c_obj
val enum_to_int c_enum_type -&gt; c_obj -&gt; c_obj
</pre>
</div>
</div>
<p>
So it's possible to do this:
So it's possible to do this:
</p>
<div class="code">
<pre>
<div class="code">
<pre>
bash-2.05a$ ocamlmktop -custom enum_test_wrap.o enum_test.cmo -o enum_test_top
bash-2.05a$ ./enum_test_top
bash-2.05a$ ./enum_test_top
Objective Caml version 3.04
# open Enum_test ;;
@ -455,7 +457,7 @@ val x : Enum_test.c_obj = C_enum `a
# int_to_enum `c_enum_type 4 ;;
- : Enum_test.c_obj = C_enum `c
</pre>
</div>
</div>
<H4><a name="Ocaml_nn11"></a>31.2.2.1 Enum typing in Ocaml</H4>
@ -485,7 +487,7 @@ distribution.
<p>
By including "carray.i", you will get access to some macros that help you
create typemaps for array types fairly easily.
create typemaps for array types fairly easily.
</p>
<p>
@ -547,7 +549,7 @@ void printfloats( float *tab, int len ) {
printf( "%f ", tab[i] );
}
printf( "\n" );
printf( "\n" );
}
%}
@ -577,25 +579,25 @@ void printfloats( float *tab, int len );
<p>
C++ classes, along with structs and unions are represented by C_obj
(string -&gt; c_obj -&gt; c_obj) wrapped closures. &nbsp;These objects
(string -&gt; c_obj -&gt; c_obj) wrapped closures. These objects
contain a method list, and a type, which allow them to be used like
C++ objects. When passed into typemaps that use pointers, they
degrade to pointers through their "&amp;" method. &nbsp;Every method
degrade to pointers through their "&amp;" method. Every method
an object has is represented as a string in the object's method table,
and each method table exists in memory only once. &nbsp;In addition
and each method table exists in memory only once. In addition
to any other operators an object might have, certain builtin ones are
provided by SWIG: (all of these take no arguments (C_void))
provided by SWIG: (all of these take no arguments (C_void))
</p>
<table summary="SWIG provided operators">
<tr><td>"~"</td><td>Delete this object</td></tr>
<tr><td>"&amp;"</td><td>Return an ordinary C_ptr value representing this
<tr><td>"&amp;"</td><td>Return an ordinary C_ptr value representing this
object's address</td></tr>
<tr><td>"sizeof"</td><td>If enabled with ("sizeof"="1") on the module node,
return the object's size in char.</td></tr>
<tr><td>":methods"</td><td>Returns a list of strings containing the names of
the methods this object contains</td></tr>
<tr><td>":classof"</td><td>Returns the name of the class this object belongs
<tr><td>":classof"</td><td>Returns the name of the class this object belongs
to.</td></tr>
<tr><td>":parents"</td><td>Returns a list of all direct parent classes which
have been wrapped by SWIG.</td></tr>
@ -603,8 +605,8 @@ have been wrapped by SWIG.</td></tr>
indicated parent class. This is mainly used internally by the SWIG module,
but may be useful to client programs.</td></tr>
<tr><td>"[member-variable]"</td><td>Each member variable is wrapped as a
method with an optional parameter.
Called with one argument, the member variable is set to the value of the
method with an optional parameter.
Called with one argument, the member variable is set to the value of the
argument. With zero arguments, the value is returned.
</td></tr>
</table>
@ -652,12 +654,12 @@ Since there's a makefile in that directory, the example is easy to build.
<p>
Here's a sample transcript of an interactive session using a string vector
after making a toplevel (make toplevel). This example uses the camlp4
after making a toplevel (make toplevel). This example uses the camlp4
module.
</p>
<div class="code"><pre>
bash-2.05a$ ./example_top
bash-2.05a$ ./example_top
Objective Caml version 3.06
Camlp4 Parsing version 3.06
@ -685,14 +687,14 @@ C_list
- : Example.c_obj = C_void
# x '[1] ;;
- : Example.c_obj = C_string "spam"
# for i = 0 to (x -&gt; size() as int) - 1 do
print_endline ((x '[i to int]) as string)
# for i = 0 to (x -&gt; size() as int) - 1 do
print_endline ((x '[i to int]) as string)
done ;;
foo
bar
baz
- : unit = ()
#
#
</pre></div>
<H4><a name="Ocaml_nn19"></a>31.2.4.2 C++ Class Example</H4>
@ -703,7 +705,7 @@ Here's a simple example using Trolltech's Qt Library:
</p>
<table border="1" bgcolor="#dddddd" summary="Qt Library example">
<tr><th><center>qt.i</center></th></tr>
<tr><th><center>qt.i</center></th></tr>
<tr><td><pre>
%module qt
%{
@ -733,9 +735,9 @@ bash-2.05a$ QTPATH=/your/qt/path
bash-2.05a$ for file in swig.mli swig.ml swigp4.ml ; do swig -ocaml -co $file ; done
bash-2.05a$ ocamlc -c swig.mli ; ocamlc -c swig.ml
bash-2.05a$ ocamlc -I `camlp4 -where` -pp "camlp4o pa_extend.cmo q_MLast.cmo" -c swigp4.ml
bash-2.05a$ swig -ocaml -c++ -I$QTPATH/include qt.i
bash-2.05a$ swig -ocaml -c++ -I$QTPATH/include qt.i
bash-2.05a$ mv qt_wrap.cxx qt_wrap.c
bash-2.05a$ ocamlc -c -ccopt -xc++ -ccopt -g -g -ccopt -I$QTPATH/include qt_wrap.c
bash-2.05a$ ocamlc -c -ccopt -xc++ -ccopt -g -g -ccopt -I$QTPATH/include qt_wrap.c
bash-2.05a$ ocamlc -c qt.mli
bash-2.05a$ ocamlc -c qt.ml
bash-2.05a$ ocamlmktop -custom swig.cmo -I `camlp4 -where` \
@ -747,7 +749,7 @@ bash-2.05a$ ocamlmktop -custom swig.cmo -I `camlp4 -where` \
<div class="code"><pre>
bash-2.05a$ ./qt_top
bash-2.05a$ ./qt_top
Objective Caml version 3.06
Camlp4 Parsing version 3.06
@ -767,7 +769,7 @@ val hello : Qt.c_obj = C_obj &lt;fun&gt;
<p>
Assuming you have a working installation of QT, you will see a window
containing the string "hi" in a button.
containing the string "hi" in a button.
</p>
<H3><a name="Ocaml_nn22"></a>31.2.5 Director Classes</H3>
@ -852,7 +854,7 @@ let triangle_class pts ob meth args =
| _ -&gt; (invoke ob) meth args ;;
let triangle =
new_derived_object
new_derived_object
new_shape
(triangle_class ((0.0,0.0),(0.5,1.0),(1.0,0.0)))
'() ;;
@ -896,7 +898,7 @@ The definition of the actual object triangle can be described this way:
<div class="code"><pre>
let triangle =
new_derived_object
new_derived_object
new_shape
(triangle_class ((0.0,0.0),(0.5,1.0),(1.0,0.0)))
'()
@ -904,13 +906,13 @@ let triangle =
<p>
The first argument to <tt>new_derived_object</tt>, new_shape is the method
which returns a shape instance. This function will be invoked with the
which returns a shape instance. This function will be invoked with the
third argument will be appended to the argument list [ C_void ]. In the
example, the actual argument list is sent as (C_list [ C_void ; C_void ]).
The augmented constructor for a director class needs the first argument
to determine whether it is being constructed as a derived object, or as
an object of the indicated type only (in this case <tt>shape</tt>). The
Second argument is a closure that will be added to the final C_obj.
Second argument is a closure that will be added to the final C_obj.
</p>
<p>

2
Doc/Manual/Octave.html
View file

@ -59,7 +59,7 @@ Also, there are a dozen or so examples in the Examples/octave directory, and hun
<p>
As of SWIG 3.0.3, the Octave module has been tested with Octave versions 3.2.4, 3.4.3, 3.6.4, and 3.8.1.
As of SWIG 3.0.7, the Octave module is regularly tested with Octave versions 3.2.4, 3.8.1, and 4.0.0.
Use of older Octave versions is not recommended, as these versions are no longer tested with SWIG.
</p>

121
Doc/Manual/Python.html
View file

@ -74,6 +74,7 @@
<li><a href="#Python_nn47">Simple pointers</a>
<li><a href="#Python_nn48">Unbounded C Arrays</a>
<li><a href="#Python_nn49">String handling</a>
<li><a href="#Python_default_args">Default arguments</a>
</ul>
<li><a href="#Python_nn53">Typemaps</a>
<ul>
@ -3382,6 +3383,18 @@ problems, for example: <tt># error handling</tt>). SWIG 3.0.3 and later report
an error for invalid preprocessor directives, so you may have to update
existing interface files to delimit blocks of Python code correctly.</p>
<p>As an alternative to providing a block containing Python code, you can
include python code from a file. The code is inserted exactly as in the
file, so this avoids any issues with the SWIG preprocessor. It's a good
approach if you have a non-trivial chunk of Python code to insert. To
use this feature you specify a filename in double quotes, for example:</p>
<div class="code">
<pre>
%pythoncode "somecode.py"
</pre>
</div>
<p>Sometimes you may want to replace or modify the wrapper function
that SWIG creates in the proxy <tt>.py</tt> file. The Python module
in SWIG provides some features that enable you to do this. First, to
@ -3404,7 +3417,7 @@ def bar(*args):
class Foo {
public:
int bar(int x);
}
};
</pre>
</div>
@ -3441,7 +3454,7 @@ proxy, just before the return statement.
class Foo {
public:
int bar(int x);
}
};
</pre>
</div>
@ -3470,7 +3483,7 @@ SWIG version 1.3.28 you can use the directive forms
class Foo {
public:
int bar(int x);
}
};
</pre>
</div>
@ -3500,7 +3513,7 @@ class Foo {
public:
int bar(int x);
int bar();
}
};
</pre>
</div>
@ -4147,6 +4160,106 @@ If you need to return binary data, you might use the
also be used to extra binary data from arbitrary pointers.
</p>
<H3><a name="Python_default_args"></a>36.7.5 Default arguments</H3>
<p>
C++ default argument code generation is documented in the main
<a href="SWIG.html#SWIGPlus_default_args">Default arguments</a> section.
There is also an optional Python specific feature that can be used called the <tt>python:cdefaultargs</tt>
<a href="Customization.html#Customization_feature_flags">feature flag</a>.
By default, SWIG attempts to convert C++ default argument values
into Python values and generates code into the Python layer containing these values.
For example:
</p>
<div class="code">
<pre>
struct CDA {
int fff(int a = 1, bool b = false);
};
</pre>
</div>
<p>
From Python this can be called as follows:
</p>
<div class="targetlang">
<pre>
&gt;&gt;&gt; CDA().fff() # C++ layer receives a=1 and b=false
&gt;&gt;&gt; CDA().fff(2) # C++ layer receives a=2 and b=false
&gt;&gt;&gt; CDA().fff(3, True) # C++ layer receives a=3 and b=true
</pre>
</div>
<p>
The default code generation in the Python layer is:
</p>
<div class="targetlang">
<pre>
class CDA(object):
...
def fff(self, a=1, b=False):
return _default_args.CDA_fff(self, a, b)
</pre>
</div>
<p>
Adding the feature:
</p>
<div class="code">
<pre>
%feature("python:cdefaultargs") CDA::fff;
struct CDA {
int fff(int a = 1, bool b = false);
</pre>
</div>
<p>
results in identical behaviour when called from Python, however, it results in different code generation:
</p>
<div class="targetlang">
<pre>
class CDA(object):
...
def fff(self, *args):
return _default_args.CDA_fff(self, *args)
</pre>
</div>
<p>
The default arguments are obtained in the C++ wrapper layer instead of the Python layer.
Some code generation modes are quite different, eg <tt>-builtin</tt> and <tt>-fastproxy</tt>,
and are unaffected by <tt>python:cdefaultargs</tt> as the default values are always obtained from the C++ layer.
</p>
<p>
Note that not all default arguments can be converted into a Python equivalent.
When SWIG does not convert them, it will generate code to obtain them from the C++ layer as if
<tt>python:cdefaultargs</tt> was specified.
This will happen if just one argument cannot be converted into a Python equivalent.
This occurs typically when the argument is not fully numeric, such as <tt>int(1)</tt>:
</p>
<div class="code">
<pre>
struct CDA {
int fff(int a = int(1), bool b = false);
};
</pre>
</div>
<p>
<b>Compatibility Note:</b> SWIG-3.0.6 introduced the <tt>python:cdefaultargs</tt> feature.
Versions of SWIG prior to this varied in their ability to convert C++ default values into
equivalent Python default argument values.
</p>
<H2><a name="Python_nn53"></a>36.8 Typemaps</H2>

17
Doc/Manual/R.html
View file

@ -119,6 +119,23 @@ Without it, inheritance of wrapped objects may fail.
These two files can be loaded in any order
</p>
<p>
If you are compiling code yourself (not using R itself), there are a few things to watch out for:
</p>
<ul>
<li>The output shared library name (to the left of the file extension) MUST match the module name, or alternatively, you can also set the -package NAME command line argument. See swig -r -help for more information
<li>If you do not set the output file name appropriately, you might see errors like
<div class="shell">
<pre>
> fact(4)
Error in .Call("R_swig_fact", s_arg1, as.logical(.copy), PACKAGE = "example") :
"R_swig_fact" not available for .Call() for package "example"
</pre>
</div>
<li>Make sure the architecture of the shared library(x64 for instance), matches the architecture of the R program you want to load your shared library into
</ul>
<H2><a name="R_nn4"></a>37.3 Precompiling large R files</H2>

5
Doc/Manual/SWIG.html
View file

@ -146,7 +146,8 @@ can be obtained by typing <tt>swig -help</tt> or <tt>swig
-I<em>dir</em> Add a directory to the file include path
-l<em>file</em> Include a SWIG library file.
-module <em>name</em> Set the name of the SWIG module
-o <em>outfile</em> Name of output file
-o <em>outfile</em> Set name of C/C++ output file to &lt;outfile&gt;
-oh <em>headfile</em> Set name of C++ output header file for directors to &lt;headfile&gt;
-outcurrentdir Set default output dir to current dir instead of input file's path
-outdir <em>dir</em> Set language specific files output directory
-pcreversion Display PCRE version information
@ -212,7 +213,7 @@ additional files depending on the target language. By default, an input file
with the name <tt>file.i</tt> is transformed into a file
<tt>file_wrap.c</tt> or <tt>file_wrap.cxx</tt> (depending on whether
or not the <tt>-c++</tt> option has been used). The name of the
output file can be changed using the <tt>-o</tt> option. In certain
output C/C++ file can be changed using the <tt>-o</tt> option. In certain
cases, file suffixes are used by the compiler to determine the source
language (C, C++, etc.). Therefore, you have to use the
<tt>-o</tt> option to change the suffix of the SWIG-generated wrapper

9
Doc/Manual/SWIGPlus.html
View file

@ -2101,13 +2101,13 @@ Therefore, earlier methods will shadow methods that appear later.
</p>
<p>
When wrapping an overloaded function, there is a chance that you will get an error message like this:
When wrapping an overloaded function, there is a chance that you will get a warning message like this:
</p>
<div class="shell">
<pre>
example.i:3: Warning 467: Overloaded foo(int) not supported (no type checking
rule for 'int').
example.i:3: Warning 467: Overloaded foo(int) not supported (incomplete type checking rule -
no precedence level in typecheck typemap for 'int').
</pre>
</div>
@ -2116,7 +2116,8 @@ This error means that the target language module supports overloading,
but for some reason there is no type-checking rule that can be used to
generate a working dispatch function. The resulting behavior is then
undefined. You should report this as a bug to the
<a href="http://www.swig.org/bugs.html">SWIG bug tracking database</a>.
<a href="http://www.swig.org/bugs.html">SWIG bug tracking database</a>
if this is due to one of the typemaps supplied with SWIG.
</p>
<p>

6
Doc/Manual/Scilab.html
View file

@ -42,7 +42,7 @@
<li><a href="#Scilab_wrapping_pointers_null_pointers">Null pointers</a>
</ul>
<li><a href="#Scilab_wrapping_structs">Structures</a>
<li><a href="#Scilab_wrapping_cpp_classes">C++ Classes</a>
<li><a href="#Scilab_wrapping_cpp_classes">C++ classes</a>
<li><a href="#Scilab_wrapping_cpp_inheritance">C++ inheritance</a>
<li><a href="#Scilab_wrapping_pointers_references_values_arrays">Pointers, references, values, and arrays</a>
<li><a href="#Scilab_wrapping_cpp_templates">C++ templates</a>
@ -931,7 +931,7 @@ ans =
</pre></div>
<H3><a name="Scilab_wrapping_cpp_classes"></a>39.3.8 C++ Classes</H3>
<H3><a name="Scilab_wrapping_cpp_classes"></a>39.3.8 C++ classes</H3>
<p>
@ -1365,7 +1365,7 @@ void throw_int() throw(int) {
}
void throw_stl_invalid_arg(int i) throw(std::invalid_argument) {
if (i &amp;lt 0)
if (i &lt; 0)
throw std::invalid_argument("argument is negative.");
}
%}

2
Doc/Manual/Sections.html
View file

@ -6,7 +6,7 @@
<body bgcolor="#ffffff">
<H1><a name="Sections"></a>SWIG-3.0 Documentation</H1>
Last update : SWIG-3.0.6 (in progress)
Last update : SWIG-3.0.7 (in progress)
<H2>Sections</H2>

28
Doc/Manual/Typemaps.html
View file

@ -4429,7 +4429,7 @@ before arrays, and so forth.
<p>
Using the above table as a guide, each target language defines a collection of "typecheck" typemaps.
The follow excerpt from the Python module illustrates this:
The following excerpt from the Python module illustrates this:
</p>
<div class="code">
@ -4542,11 +4542,31 @@ Here is an example,
<p>
The bottom line: If you are writing new typemaps and you are using overloaded methods, you will probably
have to write typecheck code or copy existing code. Since this is a relatively new SWIG feature, there are
few examples to work with. However, you might look at some of the existing library files likes 'typemaps.i' for
a guide.
have to write new typecheck code or copy and modify existing typecheck code.
</p>
<p>
If you write a typecheck typemap and omit the precedence level, for example commenting it out as shown below:
</p>
<div class="code">
<pre>
%typemap(typecheck /*,precedence=SWIG_TYPECHECK_INTEGER*/) int {
$1 = PyInt_Check($input) ? 1 : 0;
}
</pre>
</div>
<p>
then the type is given a precedence higher than any other known precedence level and a <a href="Warnings.html#Warnings">warning</a> is issued:
</p>
<div class="shell">
<pre>
example.i:18: Warning 467: Overloaded method foo(int) not supported (incomplete type checking rule - no precedence level in typecheck typemap for 'int').
</pre>
</div>
<p>
<b>Notes:</b>
</p>

2
Doc/Manual/Warnings.html
View file

@ -492,7 +492,7 @@ example.i(4) : Syntax error in input(1).
<li>464. Unsupported constant value.
<li>465. Unable to handle type <em>type</em>.
<li>466. Unsupported variable type <em>type</em>.
<li>467. Overloaded <em>declaration</em> not supported (no type checking rule for '<em>type</em>')
<li>467. Overloaded <em>declaration</em> not supported (incomplete type checking rule - no precedence level in typecheck typemap for '<em>type</em>')
<li>468. No 'throw' typemap defined for exception type <em>type</em>
<li>469. No or improper directorin typemap defined for <em>type</em>
<li>470. Thread/reentrant unsafe wrapping, consider returning by value instead.

51
Doc/Manual/Windows.html
View file

@ -293,9 +293,9 @@ Execute the steps in the order shown and don't use spaces in path names. In fact
Start the MSYS command prompt and execute:
<div class="shell"><pre>
cd /
tar -jxf msys-automake-1.8.2.tar.bz2
tar -jxf msys-automake-1.8.2.tar.bz2
tar -jxf msys-autoconf-2.59.tar.bz2
tar -zxf bison-2.0-MSYS.tar.gz
tar -zxf bison-2.0-MSYS.tar.gz
</pre></div>
</li>
@ -388,6 +388,53 @@ Include it like you would any other interface file, for example:
__declspec(dllexport) ULONG __stdcall foo(DWORD, __int32);
</pre></div>
<p>Note that if you follow Microsoft's recommendation of wrapping the
<tt>__declspec</tt> calls in a preprocessor definition, you will need to
make sure that the definition is included by SWIG as well, by either defining it
manually or via a header. For example, if you have specified the
preprocessor definition in a header named <tt>export_lib.h</tt> and include
other headers which depend on it, you should use the <tt>%include</tt> directive
to include the definition explicitly. For example, if you had a header file,
<tt>bar.h</tt>, which depended on <tt>export_lib.h</tt>, your SWIG definition
file might look like:</p>
<div class="code"><pre>
// bar.i
%module bar
%include &lt;windows.i&gt;
%include "export_lib.h"
%include "bar.h"
</pre></div>
<p>
where export_lib.h may contain:
</p>
<div class="code"><pre>
// export_lib.h
#define BAR_API __declspec(dllexport)
</pre></div>
<p>
and bar.h may look like:
</p>
<div class="code"><pre>
// bar.h
#include "export_lib.h"
BAR_API void bar_function(int, double);
</pre></div>
<p>
Using the preprocessor to remove BAR_API is a popular simpler solution:
</p>
<div class="code"><pre>
// bar.i
%module bar
#define BAR_API
%include "bar.h"
</pre></div>
</body>
</html>