Merge branch 'master' into gsoc2009-matevz
Conflicts: Examples/Makefile.in Examples/guile/Makefile.in Lib/php/php.swg Makefile.in Source/CParse/parser.y configure.ac
This commit is contained in:
William S Fulton
commit
bcb7aee022
585 changed files with 9528 additions and 12959 deletions
|
|
@ -1613,7 +1613,7 @@ opoverload>
|
|||
<p>
|
||||
Variable length argument lists are not supported, by default. If
|
||||
such a function is encountered, a warning will generated to
|
||||
stderr. Varargs are supported via the SWIG <tt>%vararg</tt>
|
||||
stderr. Varargs are supported via the SWIG <tt>%varargs</tt>
|
||||
directive. This directive allows you to specify a (finite)
|
||||
argument list which will be inserted into the wrapper in place
|
||||
of the variable length argument indicator. As an example,
|
||||
|
|
@ -1624,7 +1624,7 @@ opoverload>
|
|||
<p>
|
||||
See the following section
|
||||
on <a href="Varargs.html#Varargs">Variable Length arguments</a>
|
||||
provides examples on how <tt>%vararg</tt> can be used, along
|
||||
provides examples on how <tt>%varargs</tt> can be used, along
|
||||
with other ways such functions can be wrapped.
|
||||
</p>
|
||||
|
||||
|
|
|
|||
|
|
@ -16,13 +16,23 @@
|
|||
<ul>
|
||||
<li><a href="Preface.html#Preface_nn2">Introduction</a>
|
||||
<li><a href="Preface.html#Preface_nn4">SWIG Versions</a>
|
||||
<li><a href="Preface.html#Preface_license">SWIG License</a>
|
||||
<li><a href="Preface.html#Preface_nn5">SWIG resources</a>
|
||||
<li><a href="Preface.html#Preface_nn6">Prerequisites</a>
|
||||
<li><a href="Preface.html#Preface_nn7">Organization of this manual</a>
|
||||
<li><a href="Preface.html#Preface_nn8">How to avoid reading the manual</a>
|
||||
<li><a href="Preface.html#Preface_nn9">Backwards compatibility</a>
|
||||
<li><a href="Preface.html#Preface_release_notes">Release notes</a>
|
||||
<li><a href="Preface.html#Preface_nn10">Credits</a>
|
||||
<li><a href="Preface.html#Preface_nn11">Bug reports</a>
|
||||
<li><a href="Preface.html#Preface_installation">Installation</a>
|
||||
<ul>
|
||||
<li><a href="Preface.html#Preface_windows_installation">Windows installation</a>
|
||||
<li><a href="Preface.html#Preface_unix_installation">Unix installation</a>
|
||||
<li><a href="Preface.html#Preface_osx_installation">Macintosh OS X installation</a>
|
||||
<li><a href="Preface.html#Preface_testing">Testing</a>
|
||||
<li><a href="Preface.html#Preface_examples">Examples</a>
|
||||
</ul>
|
||||
</ul>
|
||||
</div>
|
||||
<!-- INDEX -->
|
||||
|
|
@ -803,8 +813,9 @@
|
|||
<!-- INDEX -->
|
||||
<div class="sectiontoc">
|
||||
<ul>
|
||||
<li><a href="Guile.html#Guile_nn1">Supported Guile Versions</a>
|
||||
<li><a href="Guile.html#Guile_nn2">Meaning of "Module"</a>
|
||||
<li><a href="Guile.html#Guile_nn3">Using the SCM or GH Guile API</a>
|
||||
<li><a href="Guile.html#Guile_nn3">Old GH Guile API</a>
|
||||
<li><a href="Guile.html#Guile_nn4">Linkage</a>
|
||||
<ul>
|
||||
<li><a href="Guile.html#Guile_nn5">Simple Linkage</a>
|
||||
|
|
@ -817,8 +828,7 @@
|
|||
<li><a href="Guile.html#Guile_nn11">Typemaps</a>
|
||||
<li><a href="Guile.html#Guile_nn12">Representation of pointers as smobs</a>
|
||||
<ul>
|
||||
<li><a href="Guile.html#Guile_nn13">GH Smobs</a>
|
||||
<li><a href="Guile.html#Guile_nn14">SCM Smobs</a>
|
||||
<li><a href="Guile.html#Guile_nn14">Smobs</a>
|
||||
<li><a href="Guile.html#Guile_nn15">Garbage Collection</a>
|
||||
</ul>
|
||||
<li><a href="Guile.html#Guile_nn16">Exception Handling</a>
|
||||
|
|
@ -1518,9 +1528,9 @@
|
|||
<li><a href="Ruby.html#Ruby_Placement_of_typemaps">Placement of typemaps</a>
|
||||
<li><a href="Ruby.html#Ruby_nn39">Ruby typemaps</a>
|
||||
<ul>
|
||||
<li><a href="Ruby.html#Ruby_in_typemap"> "in" typemap</a>
|
||||
<li><a href="Ruby.html#Ruby_in_typemap">"in" typemap</a>
|
||||
<li><a href="Ruby.html#Ruby_typecheck_typemap">"typecheck" typemap</a>
|
||||
<li><a href="Ruby.html#Ruby_out_typemap"> "out" typemap</a>
|
||||
<li><a href="Ruby.html#Ruby_out_typemap">"out" typemap</a>
|
||||
<li><a href="Ruby.html#Ruby_arginit_typemap">"arginit" typemap</a>
|
||||
<li><a href="Ruby.html#Ruby_default_typemap">"default" typemap</a>
|
||||
<li><a href="Ruby.html#Ruby_check_typemap">"check" typemap</a>
|
||||
|
|
|
|||
|
|
@ -592,9 +592,7 @@ SWIG_NullReferenceError
|
|||
</pre></div>
|
||||
|
||||
<p>
|
||||
Since the <tt>SWIG_exception()</tt> function is defined at the C-level
|
||||
it can be used elsewhere in SWIG. This includes typemaps and helper
|
||||
functions.
|
||||
The <tt>SWIG_exception()</tt> function can also be used in typemaps.
|
||||
</p>
|
||||
|
||||
<H2><a name="Customization_ownership"></a>11.2 Object ownership and %newobject</H2>
|
||||
|
|
|
|||
|
|
@ -3101,7 +3101,7 @@ As you can see, most usages are direct.
|
|||
|
||||
<dl>
|
||||
|
||||
<dt> <b>configure.in</b>
|
||||
<dt> <b>configure.ac</b>
|
||||
<dd> This file is processed by
|
||||
|
||||
<p>
|
||||
|
|
@ -3551,7 +3551,7 @@ details being outlined earlier on.
|
|||
a runtime test, see for example <tt>Examples/python/class</tt>.
|
||||
</li>
|
||||
<li>
|
||||
Modify <tt>configure.in</tt>, <tt>Makefile.in</tt> and <tt>Examples/Makefile.in</tt> to run
|
||||
Modify <tt>configure.ac</tt>, <tt>Makefile.in</tt> and <tt>Examples/Makefile.in</tt> to run
|
||||
these examples. Please make sure that if the new language is not
|
||||
installed properly on a box, <tt>make -k check</tt> should still work by
|
||||
skipping the tests and examples for the new language module.
|
||||
|
|
|
|||
|
|
@ -12,8 +12,9 @@
|
|||
<!-- INDEX -->
|
||||
<div class="sectiontoc">
|
||||
<ul>
|
||||
<li><a href="#Guile_nn1">Supported Guile Versions</a>
|
||||
<li><a href="#Guile_nn2">Meaning of "Module"</a>
|
||||
<li><a href="#Guile_nn3">Using the SCM or GH Guile API</a>
|
||||
<li><a href="#Guile_nn3">Old GH Guile API</a>
|
||||
<li><a href="#Guile_nn4">Linkage</a>
|
||||
<ul>
|
||||
<li><a href="#Guile_nn5">Simple Linkage</a>
|
||||
|
|
@ -26,8 +27,7 @@
|
|||
<li><a href="#Guile_nn11">Typemaps</a>
|
||||
<li><a href="#Guile_nn12">Representation of pointers as smobs</a>
|
||||
<ul>
|
||||
<li><a href="#Guile_nn13">GH Smobs</a>
|
||||
<li><a href="#Guile_nn14">SCM Smobs</a>
|
||||
<li><a href="#Guile_nn14">Smobs</a>
|
||||
<li><a href="#Guile_nn15">Garbage Collection</a>
|
||||
</ul>
|
||||
<li><a href="#Guile_nn16">Exception Handling</a>
|
||||
|
|
@ -47,7 +47,21 @@
|
|||
<p>
|
||||
This section details guile-specific support in SWIG.
|
||||
|
||||
<H2><a name="Guile_nn2"></a>23.1 Meaning of "Module"</H2>
|
||||
<H2><a name="Guile_nn1"></a>23.1 Supported Guile Versions</H2>
|
||||
|
||||
|
||||
<p>
|
||||
SWIG works with Guile versions 1.8.x and 2.0.x. Support for version
|
||||
1.6.x has been dropped. The last version of SWIG that still works with
|
||||
Guile version 1.6.x is SWIG 2.0.9.
|
||||
|
||||
<p>
|
||||
Note that starting with guile 2.0, the guile sources can be compiled for
|
||||
improved performance. This is currently not tested with swig
|
||||
so your mileage may vary. To be safe set environment variable
|
||||
GUILE_AUTO_COMPILE to 0 when using swig generated guile code.
|
||||
|
||||
<H2><a name="Guile_nn2"></a>23.2 Meaning of "Module"</H2>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -55,55 +69,18 @@ There are three different concepts of "module" involved, defined
|
|||
separately for SWIG, Guile, and Libtool. To avoid horrible confusion,
|
||||
we explicitly prefix the context, e.g., "guile-module".
|
||||
|
||||
<H2><a name="Guile_nn3"></a>23.2 Using the SCM or GH Guile API</H2>
|
||||
<H2><a name="Guile_nn3"></a>23.3 Old GH Guile API</H2>
|
||||
|
||||
|
||||
<p>The guile module can currently export wrapper files that use the guile GH interface or the
|
||||
SCM interface. This is controlled by an argument passed to swig. The "-gh" argument causes swig
|
||||
to output GH code, and the "-scm" argument causes swig to output SCM code. Right now the "-scm" argument
|
||||
is the default. The "-scm" wrapper generation assumes a guile version >= 1.6 and has several advantages over
|
||||
the "-gh" wrapper generation including garbage collection and GOOPS support.
|
||||
The "-gh" wrapper generation can be used for older versions of guile.
|
||||
The guile GH wrapper code generation is depreciated and the
|
||||
SCM interface is the default. The SCM and GH interface differ greatly in how they store
|
||||
pointers and have completely different run-time code. See below for more info.
|
||||
|
||||
<p>The GH interface to guile is deprecated. Read more about why in the
|
||||
<p>Guile 1.8 and older could be interfaced using two different api's, the SCM
|
||||
or the GH API. The GH interface to guile is deprecated. Read more about why in the
|
||||
<a href="http://www.gnu.org/software/guile/docs/docs-1.6/guile-ref/GH.html#GH">Guile manual</a>.
|
||||
The idea of the GH interface was to provide a high level API that other languages and projects
|
||||
could adopt. This was a good idea, but didn't pan out well for general development. But for the
|
||||
specific, minimal uses that the SWIG typemaps put the GH interface to use is ideal for
|
||||
using a high level API. So even though the GH interface is depreciated, SWIG will continue to use
|
||||
the GH interface and provide mappings from the GH interface to whatever API we need.
|
||||
We can maintain this mapping where guile failed because SWIG uses a small subset of all the GH functions
|
||||
which map easily. All the guile typemaps like typemaps.i and std_vector.i
|
||||
will continue to use the GH functions to do things like create lists of values, convert strings to
|
||||
integers, etc. Then every language module will define a mapping between the GH interface and
|
||||
whatever custom API the language uses. This is currently implemented by the guile module to use
|
||||
the SCM guile API rather than the GH guile API.
|
||||
For example, here are some of the current mapping file for the SCM API</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
<p>Support for the guile GH wrapper code generation has been dropped from SWIG. The last
|
||||
version of SWIG that can still generate guile GH wrapper code is 2.0.9. Please
|
||||
use that version if you really need the GH wrapper code.
|
||||
|
||||
#define gh_append2(a, b) scm_append(scm_listify(a, b, SCM_UNDEFINED))
|
||||
#define gh_apply(a, b) scm_apply(a, b, SCM_EOL)
|
||||
#define gh_bool2scm SCM_BOOL
|
||||
#define gh_boolean_p SCM_BOOLP
|
||||
#define gh_car SCM_CAR
|
||||
#define gh_cdr SCM_CDR
|
||||
#define gh_cons scm_cons
|
||||
#define gh_double2scm scm_make_real
|
||||
...
|
||||
</pre></div>
|
||||
|
||||
<p>This file is parsed by SWIG at wrapper generation time, so every reference to a gh_ function is replaced
|
||||
by a scm_ function in the wrapper file. Thus the gh_ function calls will never be seen in the wrapper;
|
||||
the wrapper will look exactly like it was generated
|
||||
for the specific API. Currently only the guile language module has created a mapping policy from gh_ to scm_,
|
||||
but there is no reason other languages (like mzscheme or chicken) couldn't also use this.
|
||||
If that happens, there is A LOT less code duplication in the standard typemaps.</p>
|
||||
|
||||
<H2><a name="Guile_nn4"></a>23.3 Linkage</H2>
|
||||
<H2><a name="Guile_nn4"></a>23.4 Linkage</H2>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -111,7 +88,7 @@ Guile support is complicated by a lack of user community cohesiveness,
|
|||
which manifests in multiple shared-library usage conventions. A set of
|
||||
policies implementing a usage convention is called a <b>linkage</b>.
|
||||
|
||||
<H3><a name="Guile_nn5"></a>23.3.1 Simple Linkage</H3>
|
||||
<H3><a name="Guile_nn5"></a>23.4.1 Simple Linkage</H3>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -134,7 +111,7 @@ libraries into Guile.</p>
|
|||
<div class="targetlang">
|
||||
<pre>
|
||||
(define-module (my module))
|
||||
(define my-so (dynamic-link "./example.so"))
|
||||
(define my-so (dynamic-link "./libexample.so"))
|
||||
(dynamic-call "SWIG_init" my-so) ; make SWIG bindings
|
||||
;; Scheme definitions can go here
|
||||
</pre>
|
||||
|
|
@ -147,7 +124,17 @@ and <code>dynamic-call</code>:
|
|||
|
||||
<div class="targetlang">
|
||||
<pre>
|
||||
(load-extension "./example.so" "SWIG_init")
|
||||
(load-extension "./libexample.so" "SWIG_init")
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
<p>
|
||||
A more portable approach would be to drop the shared library extension:
|
||||
</p>
|
||||
|
||||
<div class="targetlang">
|
||||
<pre>
|
||||
(load-extension "./libexample" "SWIG_init")
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
|
|
@ -190,7 +177,7 @@ information by including a directive like this in the interface file:
|
|||
|
||||
<div class="code">
|
||||
<pre>
|
||||
%scheme %{ (load-extension "./example.so" "SWIG_init") %}
|
||||
%scheme %{ (load-extension "./libexample.so" "SWIG_init") %}
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
|
|
@ -206,7 +193,7 @@ placed between the <code>define-module</code> form and the
|
|||
<code>SWIG_init</code> via a preprocessor define to avoid symbol
|
||||
clashes. For this case, however, passive linkage is available.
|
||||
|
||||
<H3><a name="Guile_nn6"></a>23.3.2 Passive Linkage</H3>
|
||||
<H3><a name="Guile_nn6"></a>23.4.2 Passive Linkage</H3>
|
||||
|
||||
|
||||
<p>Passive linkage is just like simple linkage, but it generates an
|
||||
|
|
@ -216,12 +203,12 @@ package name (see below).
|
|||
<p>You should use passive linkage rather than simple linkage when you
|
||||
are using multiple modules.
|
||||
|
||||
<H3><a name="Guile_nn7"></a>23.3.3 Native Guile Module Linkage</H3>
|
||||
<H3><a name="Guile_nn7"></a>23.4.3 Native Guile Module Linkage</H3>
|
||||
|
||||
|
||||
<p>SWIG can also generate wrapper code that does all the Guile module
|
||||
declarations on its own if you pass it the <code>-Linkage
|
||||
module</code> command-line option. This requires Guile 1.5.0 or later.
|
||||
module</code> command-line option.
|
||||
|
||||
<p>The module name is set with the <code>-package</code> and
|
||||
<code>-module</code> command-line options. Suppose you want to define
|
||||
|
|
@ -244,7 +231,7 @@ shared libraries into Guile; all bindings are automatically put in
|
|||
newly created Guile modules.
|
||||
<div class="targetlang">
|
||||
<pre>
|
||||
(define my-so (dynamic-link "./foo.so"))
|
||||
(define my-so (dynamic-link "./libfoo"))
|
||||
;; create new module and put bindings there:
|
||||
(dynamic-call "scm_init_my_modules_foo_module" my-so)
|
||||
</pre>
|
||||
|
|
@ -252,12 +239,12 @@ newly created Guile modules.
|
|||
Newer Guile versions have a shorthand procedure for this:
|
||||
<div class="targetlang">
|
||||
<pre>
|
||||
(load-extension "./foo.so" "scm_init_my_modules_foo_module")
|
||||
(load-extension "./libfoo.so" "scm_init_my_modules_foo_module")
|
||||
</pre>
|
||||
</div>
|
||||
</ul>
|
||||
|
||||
<H3><a name="Guile_nn8"></a>23.3.4 Old Auto-Loading Guile Module Linkage</H3>
|
||||
<H3><a name="Guile_nn8"></a>23.4.4 Old Auto-Loading Guile Module Linkage</H3>
|
||||
|
||||
|
||||
<p>Guile used to support an autoloading facility for object-code
|
||||
|
|
@ -283,7 +270,7 @@ option, SWIG generates an exported module initialization function with
|
|||
an appropriate name.
|
||||
|
||||
|
||||
<H3><a name="Guile_nn9"></a>23.3.5 Hobbit4D Linkage</H3>
|
||||
<H3><a name="Guile_nn9"></a>23.4.5 Hobbit4D Linkage</H3>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -308,7 +295,7 @@ my/lib/libfoo.so.X.Y.Z and friends. This scheme is still very
|
|||
experimental; the (hobbit4d link) conventions are not well understood.
|
||||
</p>
|
||||
|
||||
<H2><a name="Guile_nn10"></a>23.4 Underscore Folding</H2>
|
||||
<H2><a name="Guile_nn10"></a>23.5 Underscore Folding</H2>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -320,7 +307,7 @@ complained so far.
|
|||
<code>%rename</code> to specify the Guile name of the wrapped
|
||||
functions and variables (see CHANGES).
|
||||
|
||||
<H2><a name="Guile_nn11"></a>23.5 Typemaps</H2>
|
||||
<H2><a name="Guile_nn11"></a>23.6 Typemaps</H2>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -412,7 +399,7 @@ constant will appear as a scheme variable. See
|
|||
<a href="Customization.html#Customization_features">Features and the %feature directive</a>
|
||||
for info on how to apply the %feature.</p>
|
||||
|
||||
<H2><a name="Guile_nn12"></a>23.6 Representation of pointers as smobs</H2>
|
||||
<H2><a name="Guile_nn12"></a>23.7 Representation of pointers as smobs</H2>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -433,7 +420,7 @@ representing the expected pointer type. See also
|
|||
If the Scheme object passed was not a SWIG smob representing a compatible
|
||||
pointer, a <code>wrong-type-arg</code> exception is raised.
|
||||
|
||||
<H3><a name="Guile_nn13"></a>23.6.1 GH Smobs</H3>
|
||||
<H3><a name="Guile_nn14"></a>23.7.1 Smobs</H3>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -444,44 +431,19 @@ mangled type name. As Guile allows registering user types, so-called
|
|||
implemented now. The details will be discussed in the following.
|
||||
</p>
|
||||
|
||||
<p> A smob is a cons cell where the lower half of the CAR contains the smob type
|
||||
tag, while the upper half of the CAR and the whole CDR are available. Every
|
||||
module creates its own smob type in the clientdata field of the module. So the
|
||||
lower 16 bits of the car of the smob store the tag and the upper 16 bits store
|
||||
the index this type is in the array. We can then, given a smob, find its
|
||||
swig_type_info struct by using the tag (lower 16 bits of car) to find which
|
||||
module this type is in (since each tag is unique for the module). Then we use
|
||||
the upper 16 bits to index into the array of types attached to this module.
|
||||
Looking up the module from the tag is worst case O(# of modules) but average
|
||||
case O(1). This is because the modules are stored in a circularly linked list,
|
||||
and when we start searching the modules for the tag, we start looking with the
|
||||
module that the function doing the lookup is in. SWIG_Guile_ConvertPtr() takes
|
||||
as its first argument the swig_module_info * of the calling function, which is
|
||||
where we start comparing tags. Most types will be looked up in the same module
|
||||
that created them, so the first module we check will most likely be correct.
|
||||
Once we have a swig_type_info structure, we loop through the linked list of
|
||||
casts, using pointer comparisons.</p>
|
||||
|
||||
<H3><a name="Guile_nn14"></a>23.6.2 SCM Smobs</H3>
|
||||
|
||||
|
||||
<p>The SCM interface (using the "-scm" argument to swig) uses swigrun.swg.
|
||||
The whole type system, when it is first initialized, creates two smobs named "swig" and "collected_swig".
|
||||
<p>The whole type system, when it is first initialized, creates two smobs named "swig" and "collected_swig".
|
||||
The swig smob is used for non-garbage collected smobs, while the collected_swig smob is used as described
|
||||
below. Each smob has the same format, which is a double cell created by SCM_NEWSMOB2()
|
||||
The first word of data is the pointer to the object and the second word of data is the swig_type_info *
|
||||
structure describing this type. This is a lot easier than the GH interface above because we can store
|
||||
a pointer to the type info structure right in the type. With the GH interface, there was not enough
|
||||
room in the smob to store two whole words of data so we needed to store part of the "swig_type_info address"
|
||||
in the smob tag. If a generated GOOPS module has been loaded, smobs will be wrapped by the corresponding
|
||||
GOOPS class.</p>
|
||||
structure describing this type. If a generated GOOPS module has been loaded, smobs will be wrapped by
|
||||
the corresponding GOOPS class.</p>
|
||||
|
||||
|
||||
<H3><a name="Guile_nn15"></a>23.6.3 Garbage Collection</H3>
|
||||
<H3><a name="Guile_nn15"></a>23.7.2 Garbage Collection</H3>
|
||||
|
||||
|
||||
<p>Garbage collection is a feature of the new SCM interface, and it is automatically included
|
||||
if you pass the "-scm" flag to swig. Thus the swig garbage collection support requires guile >1.6.
|
||||
<p>Garbage collection is a feature of Guile since version 1.6. As SWIG now requires Guile > 1.8,
|
||||
it is automatically included.
|
||||
Garbage collection works like this. Every swig_type_info structure stores in its clientdata field a pointer
|
||||
to the destructor for this type. The destructor is the generated wrapper around the delete function.
|
||||
So swig still exports a wrapper for the destructor, it just does not call scm_c_define_gsubr() for
|
||||
|
|
@ -491,7 +453,7 @@ is exactly like described in <a href="Customization.html#Customization_ownership
|
|||
Object ownership and %newobject</a> in the SWIG manual. All typemaps use an $owner var, and
|
||||
the guile module replaces $owner with 0 or 1 depending on feature:new.</p>
|
||||
|
||||
<H2><a name="Guile_nn16"></a>23.7 Exception Handling</H2>
|
||||
<H2><a name="Guile_nn16"></a>23.8 Exception Handling</H2>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -517,14 +479,13 @@ mapping:
|
|||
The default when not specified here is to use "swig-error".
|
||||
See Lib/exception.i for details.
|
||||
|
||||
<H2><a name="Guile_nn17"></a>23.8 Procedure documentation</H2>
|
||||
<H2><a name="Guile_nn17"></a>23.9 Procedure documentation</H2>
|
||||
|
||||
|
||||
<p>If invoked with the command-line option <code>-procdoc
|
||||
<var>file</var></code>, SWIG creates documentation strings for the
|
||||
generated wrapper functions, describing the procedure signature and
|
||||
return value, and writes them to <var>file</var>. You need Guile 1.4
|
||||
or later to make use of the documentation files.
|
||||
return value, and writes them to <var>file</var>.
|
||||
|
||||
<p>SWIG can generate documentation strings in three formats, which are
|
||||
selected via the command-line option <code>-procdocformat
|
||||
|
|
@ -553,7 +514,7 @@ like this:
|
|||
typemap argument <code>doc</code>. See <code>Lib/guile/typemaps.i</code> for
|
||||
details.
|
||||
|
||||
<H2><a name="Guile_nn18"></a>23.9 Procedures with setters</H2>
|
||||
<H2><a name="Guile_nn18"></a>23.10 Procedures with setters</H2>
|
||||
|
||||
|
||||
<p>For global variables, SWIG creates a single wrapper procedure
|
||||
|
|
@ -581,7 +542,7 @@ struct members, the procedures <code>(<var>struct</var>-<var>member</var>-get
|
|||
pointer)</code> and <code>(<var>struct-member</var>-set pointer
|
||||
value)</code> are <em>not</em> generated.
|
||||
|
||||
<H2><a name="Guile_nn19"></a>23.10 GOOPS Proxy Classes</H2>
|
||||
<H2><a name="Guile_nn19"></a>23.11 GOOPS Proxy Classes</H2>
|
||||
|
||||
|
||||
<p>SWIG can also generate classes and generic functions for use with
|
||||
|
|
@ -589,10 +550,7 @@ Guile's Object-Oriented Programming System (GOOPS). GOOPS is a
|
|||
sophisticated object system in the spirit of the Common Lisp Object
|
||||
System (CLOS).
|
||||
|
||||
<p>GOOPS support is
|
||||
only available with the new SCM interface (enabled with the
|
||||
<code>-scm</code> command-line option of SWIG). To enable GOOPS
|
||||
support, pass the <code>-proxy</code> argument to
|
||||
<p>To enable GOOPS support, pass the <code>-proxy</code> argument to
|
||||
swig. This will export the GOOPS wrapper definitions into the
|
||||
<code><i>module</i>.scm</code> file in the directory specified by -outdir or the
|
||||
current directory. GOOPS support requires either passive or module linkage.</p>
|
||||
|
|
@ -730,7 +688,7 @@ Notice that <Foo> is used before it is defined. The fix is to just put th
|
|||
<code>%import "foo.h"</code> before the <code>%inline</code> block.
|
||||
</p>
|
||||
|
||||
<H3><a name="Guile_nn20"></a>23.10.1 Naming Issues</H3>
|
||||
<H3><a name="Guile_nn20"></a>23.11.1 Naming Issues</H3>
|
||||
|
||||
|
||||
<p>As you can see in the example above, there are potential naming conflicts. The default exported
|
||||
|
|
@ -767,7 +725,7 @@ guile-modules. For example,</p>
|
|||
(use-modules ((Test) #:renamer (symbol-prefix-proc 'goops:)))
|
||||
</pre></div>
|
||||
|
||||
<H3><a name="Guile_nn21"></a>23.10.2 Linking</H3>
|
||||
<H3><a name="Guile_nn21"></a>23.11.2 Linking</H3>
|
||||
|
||||
|
||||
<p>The guile-modules generated above all need to be linked together. GOOPS support requires
|
||||
|
|
@ -787,10 +745,10 @@ and might conflict with names from the GOOPS guile-module (see above). Pass the
|
|||
argument to solve this problem. If the <code>-exportprimitive</code> option is passed to SWIG the
|
||||
<code>(export ...)</code> code that would be exported into the scmstub file is exported at the bottom
|
||||
of the generated GOOPS guile-module.
|
||||
The <code>%goops</code> directive should contain code to load the .so library.
|
||||
The <code>%goops</code> directive should contain code to load the shared library.
|
||||
|
||||
<div class="code"><pre>
|
||||
%goops %{ (load-extension "./foo.so" "scm_init_my_modules_foo_module") %}
|
||||
%goops %{ (load-extension "./libfoo.so" "scm_init_my_modules_foo_module") %}
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
|
|
@ -802,7 +760,7 @@ Produces the following code at the top of the generated GOOPS guile-module
|
|||
(define-module (my modules foo))
|
||||
|
||||
;; %goops directive goes here
|
||||
(load-extension "./foo.so" "scm_init_my_modules_foo_module")
|
||||
(load-extension "./libfoo.so" "scm_init_my_modules_foo_module")
|
||||
|
||||
(use-modules (oop goops) (Swig common))
|
||||
</pre></div>
|
||||
|
|
@ -810,7 +768,7 @@ Produces the following code at the top of the generated GOOPS guile-module
|
|||
|
||||
<li><p><b>Passive Linkage with -scmstub</b>: Here, the name of the scmstub file should be
|
||||
<code>Module-primitive.scm</code> (with <i>primitive</i> replaced with whatever is given with the <code>-primsuffix</code>
|
||||
argument. The code to load the <code>.so</code> library should be located in the <code>%scheme</code> directive,
|
||||
argument. The code to load the shared library should be located in the <code>%scheme</code> directive,
|
||||
which will then be added to the scmstub file.
|
||||
SWIG will automatically generate the line <code>(use-modules (<i>Package</i> <i>Module-primitive</i>))</code>
|
||||
into the GOOPS guile-module. So if <i>Module-primitive.scm</i> is on the autoload path for guile, the
|
||||
|
|
@ -818,7 +776,7 @@ into the GOOPS guile-module. So if <i>Module-primitive.scm</i> is on the autolo
|
|||
whatever code is needed to load the <i>Module-primitive.scm</i> file into guile.</p>
|
||||
|
||||
<div class="targetlang"><pre>
|
||||
%scheme %{ (load-extension "./foo.so" "scm_init_my_modules_foo_module") %}
|
||||
%scheme %{ (load-extension "./libfoo.so" "scm_init_my_modules_foo_module") %}
|
||||
// only include the following definition if (my modules foo) cannot
|
||||
// be loaded automatically
|
||||
%goops %{
|
||||
|
|
@ -851,7 +809,7 @@ SWIG will also automatically generate the line <code>(use-modules
|
|||
directive should contain whatever code is needed to get that module loaded into guile.</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
%goops %{ (load-extension "./foo.so" "scm_init_my_modules_foo_module") %}
|
||||
%goops %{ (load-extension "./libfoo.so" "scm_init_my_modules_foo_module") %}
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
|
|
@ -862,7 +820,7 @@ Produces the following code at the top of the generated GOOPS guile-module
|
|||
(define-module (my modules foo))
|
||||
|
||||
;; %goops directive goes here (if any)
|
||||
(load-extension "./foo.so" "scm_init_my_modules_foo_module")
|
||||
(load-extension "./libfoo.so" "scm_init_my_modules_foo_module")
|
||||
|
||||
(use-modules (oop goops) (Swig common))
|
||||
(use-modules ((my modules foo-primitive) :renamer (symbol-prefix-proc
|
||||
|
|
|
|||
|
|
@ -5662,7 +5662,7 @@ to make the method and constructor public:
|
|||
|
||||
<p>
|
||||
The Java directors feature requires the "javadirectorin", "javadirectorout", "directorin" and the "directorout" typemaps in order to work properly.
|
||||
The "javapackage" typemap is an optional typemap used to identify the Java package path for individual SWIG generated proxy classes.
|
||||
The "javapackage" typemap is an optional typemap used to identify the Java package path for individual SWIG generated proxy classes used in director methods.
|
||||
</p>
|
||||
|
||||
<p><tt>%typemap(directorin)</tt></p>
|
||||
|
|
@ -5803,6 +5803,7 @@ The target method is the method in the Java proxy class which overrides the virt
|
|||
<p>
|
||||
The "javapackage" typemap is optional; it serves to identify a class's Java package.
|
||||
This typemap should be used in conjunction with classes that are defined outside of the current SWIG interface file.
|
||||
The typemap is only used if the type is used in a director method, that is, in a virtual method in a director class.
|
||||
For example:
|
||||
</p>
|
||||
|
||||
|
|
@ -5819,7 +5820,7 @@ For example:
|
|||
class Example {
|
||||
public:
|
||||
virtual ~Example();
|
||||
void ping(Foo *arg1, Bar *arg2);
|
||||
virtual void ping(Foo *arg1, Bar *arg2);
|
||||
};
|
||||
}
|
||||
</pre>
|
||||
|
|
@ -5844,7 +5845,7 @@ The corrected interface file looks like:
|
|||
class Example {
|
||||
public:
|
||||
virtual ~Example();
|
||||
void ping(Foo *arg1, Bar *arg2);
|
||||
virtual void ping(Foo *arg1, Bar *arg2);
|
||||
};
|
||||
}
|
||||
</pre>
|
||||
|
|
@ -7885,7 +7886,7 @@ where it is possible to step from Java code into a JNI method within one environ
|
|||
<p>
|
||||
Alternatively, debugging can involve placing debug printout statements in the JNI layer using the <tt>%exception</tt> directive.
|
||||
See the <a href="Customization.html#Customization_exception_special_variables">special variables for %exception</a> section.
|
||||
Many of the default typemaps can also be overidden and modified for adding in extra logging/debug display information.
|
||||
Many of the default typemaps can also be overridden and modified for adding in extra logging/debug display information.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
|
|
|
|||
|
|
@ -1359,7 +1359,7 @@ extern void sort_double(double* arr, int len);
|
|||
to create an array in C/C++ then this can be filled within Lua and passed into the function. It works, but it's a bit tedious.
|
||||
More details can be found in the <a href="Library.html#Library_carrays">carrays.i</a> documentation.</p>
|
||||
|
||||
<p>The second and more intuitive way, would be to pass a Lua table directly into the function, and have SWIG automatically convert between Lua-table and C-array. Within the <tt><typemaps.i></tt> file there are typemaps ready written to perform this task. To use them is again a matter of using %appy in the correct manner.</p>
|
||||
<p>The second and more intuitive way, would be to pass a Lua table directly into the function, and have SWIG automatically convert between Lua-table and C-array. Within the <tt><typemaps.i></tt> file there are typemaps ready written to perform this task. To use them is again a matter of using %apply in the correct manner.</p>
|
||||
|
||||
<p>The wrapper file below, shows both the use of carrays as well as the use of the typemap to wrap arrays. </p>
|
||||
|
||||
|
|
|
|||
|
|
@ -74,7 +74,7 @@ Let's start with a very simple SWIG interface file, example.i:
|
|||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
%module example
|
||||
%module swigexample
|
||||
%{
|
||||
#include "example.h"
|
||||
%}
|
||||
|
|
@ -143,10 +143,10 @@ $ mkoctfile example_wrap.cpp example.c
|
|||
</p>
|
||||
|
||||
<p>
|
||||
mkoctfile will produce "example.oct", which contains the compiled extension module. Loading it into Octave is then a matter of invoking
|
||||
mkoctfile will produce "swigexample.oct", which contains the compiled extension module. Loading it into Octave is then a matter of invoking
|
||||
</p>
|
||||
|
||||
<div class="targetlang"><pre>octave:1> example</pre></div>
|
||||
<div class="targetlang"><pre>octave:1> swigexample</pre></div>
|
||||
|
||||
<H3><a name="Octave_nn6"></a>30.2.3 Using your module</H3>
|
||||
|
||||
|
|
@ -157,13 +157,13 @@ Assuming all goes well, you will be able to do this:
|
|||
</p>
|
||||
|
||||
<div class="targetlang"><pre>$ octave -q
|
||||
octave:1> example
|
||||
octave:2> example.gcd(4,6)
|
||||
octave:1> swigexample
|
||||
octave:2> swigexample.gcd(4,6)
|
||||
ans = 2
|
||||
octave:3> example.cvar.Foo
|
||||
octave:3> swigexample.cvar.Foo
|
||||
ans = 3
|
||||
octave:4> example.cvar.Foo=4;
|
||||
octave:5> example.cvar.Foo
|
||||
octave:4> swigexample.cvar.Foo=4;
|
||||
octave:5> swigexample.cvar.Foo
|
||||
ans = 4 </pre></div>
|
||||
|
||||
<H2><a name="Octave_nn7"></a>30.3 A tour of basic C/C++ wrapping</H2>
|
||||
|
|
@ -173,11 +173,11 @@ ans = 4 </pre></div>
|
|||
|
||||
|
||||
<p>
|
||||
The SWIG module directive specifies the name of the Octave module. If you specify "module example", then in Octave everything in the module will be accessible under "example", as in the above example. When choosing a module name, make sure you don't use the same name as a built-in Octave command or standard module name.
|
||||
The SWIG module directive specifies the name of the Octave module. If you specify "module swigexample", then in Octave everything in the module will be accessible under "swigexample", as in the above example. When choosing a module name, make sure you don't use the same name as a built-in Octave command or standard module name.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
When Octave is asked to invoke <tt>example</tt>, it will try to find the ".m" or ".oct" file that defines the function "example". You therefore need to make sure that "example.oct" is in Octave's search path, which can be specified with the environment variable "OCTAVE_PATH".
|
||||
When Octave is asked to invoke <tt>swigexample</tt>, it will try to find the ".m" or ".oct" file that defines the function "swigexample". You therefore need to make sure that "swigexample.oct" is in Octave's search path, which can be specified with the environment variable "OCTAVE_PATH".
|
||||
</p>
|
||||
|
||||
<p>
|
||||
|
|
@ -185,7 +185,7 @@ To load an Octave module, simply type its name:
|
|||
</p>
|
||||
|
||||
<div class="targetlang"><pre>
|
||||
octave:1> example;
|
||||
octave:1> swigexample;
|
||||
octave:2> gcd(4,6)
|
||||
ans = 2
|
||||
octave:3> cvar.Foo
|
||||
|
|
@ -202,15 +202,15 @@ If the module is also used in the base context, however, it must first be loaded
|
|||
|
||||
<div class="targetlang"><pre>
|
||||
octave:1> function l = my_lcm(a,b)
|
||||
> example
|
||||
> l = abs(a*b)/example.gcd(a,b);
|
||||
> swigexample
|
||||
> l = abs(a*b)/swigexample.gcd(a,b);
|
||||
> endfunction
|
||||
octave:2> my_lcm(4,6)
|
||||
ans = 12
|
||||
octave:3> example.gcd(4,6)
|
||||
octave:3> swigexample.gcd(4,6)
|
||||
error: can't perform indexing operations for <unknown type> type
|
||||
octave:3> example;
|
||||
octave:4> example.gcd(4,6)
|
||||
octave:3> swigexample;
|
||||
octave:4> swigexample.gcd(4,6)
|
||||
ans = 2
|
||||
</pre></div>
|
||||
|
||||
|
|
@ -221,14 +221,14 @@ ans = 2
|
|||
Global functions are wrapped as new Octave built-in functions. For example,
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>%module example
|
||||
<div class="code"><pre>%module swigexample
|
||||
int fact(int n); </pre></div>
|
||||
|
||||
<p>
|
||||
creates a built-in function <tt>example.fact(n)</tt> that works exactly like you think it does:
|
||||
creates a built-in function <tt>swigexample.fact(n)</tt> that works exactly like you think it does:
|
||||
</p>
|
||||
|
||||
<div class="targetlang"><pre>octave:1> example.fact(4)
|
||||
<div class="targetlang"><pre>octave:1> swigexample.fact(4)
|
||||
24 </pre></div>
|
||||
|
||||
<H3><a name="Octave_nn10"></a>30.3.3 Global variables</H3>
|
||||
|
|
@ -238,7 +238,7 @@ int fact(int n); </pre></div>
|
|||
Global variables are a little special in Octave. Given a global variable:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>%module example
|
||||
<div class="code"><pre>%module swigexample
|
||||
extern double Foo;
|
||||
</pre></div>
|
||||
|
||||
|
|
@ -246,20 +246,20 @@ extern double Foo;
|
|||
To expose variables, SWIG actually generates two functions, to get and set the value. In this case, Foo_set and Foo_set would be generated. SWIG then automatically calls these functions when you get and set the variable-- in the former case creating a local copy in the interpreter of the C variables, and in the latter case copying an interpreter variables onto the C variable.
|
||||
</p>
|
||||
|
||||
<div class="targetlang"><pre>octave:1> example;
|
||||
octave:2> c=example.cvar.Foo
|
||||
<div class="targetlang"><pre>octave:1> swigexample;
|
||||
octave:2> c=swigexample.cvar.Foo
|
||||
c = 3
|
||||
octave:3> example.cvar.Foo=4;
|
||||
octave:3> swigexample.cvar.Foo=4;
|
||||
octave:4> c
|
||||
c = 3
|
||||
octave:5> example.cvar.Foo
|
||||
octave:5> swigexample.cvar.Foo
|
||||
ans = 4</pre></div>
|
||||
|
||||
<p>
|
||||
If a variable is marked with the %immutable directive then any attempts to set this variable will cause an Octave error. Given a global variable:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>%module example
|
||||
<div class="code"><pre>%module swigexample
|
||||
%immutable;
|
||||
extern double Foo;
|
||||
%mutable;
|
||||
|
|
@ -269,8 +269,8 @@ extern double Foo;
|
|||
SWIG will allow the reading of <tt>Foo</tt> but when a set attempt is made, an error function will be called.
|
||||
</p>
|
||||
|
||||
<div class="targetlang"><pre>octave:1> example
|
||||
octave:2> example.Foo=4
|
||||
<div class="targetlang"><pre>octave:1> swigexample
|
||||
octave:2> swigexample.Foo=4
|
||||
error: attempt to set immutable member variable
|
||||
error: assignment failed, or no method for `swig_type = scalar'
|
||||
error: evaluating assignment expression near line 2, column 12 </pre></div>
|
||||
|
|
@ -279,9 +279,9 @@ error: evaluating assignment expression near line 2, column 12 </pre></div>
|
|||
It is possible to add new functions or variables to the module. This also allows the user to rename/remove existing functions and constants (but not linked variables, mutable or immutable). Therefore users are recommended to be careful when doing so.
|
||||
</p>
|
||||
|
||||
<div class="targetlang"><pre>octave:1> example;
|
||||
octave:2> example.PI=3.142;
|
||||
octave:3> example.PI
|
||||
<div class="targetlang"><pre>octave:1> swigexample;
|
||||
octave:2> swigexample.PI=3.142;
|
||||
octave:3> swigexample.PI
|
||||
ans = 3.1420 </pre></div>
|
||||
|
||||
<H3><a name="Octave_nn11"></a>30.3.4 Constants and enums</H3>
|
||||
|
|
@ -291,7 +291,7 @@ ans = 3.1420 </pre></div>
|
|||
Because Octave doesn't really have the concept of constants, C/C++ constants are not really constant in Octave. They are actually just a copy of the value into the Octave interpreter. Therefore they can be changed just as any other value. For example given some constants:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>%module example
|
||||
<div class="code"><pre>%module swigexample
|
||||
%constant int ICONST=42;
|
||||
#define SCONST "Hello World"
|
||||
enum Days{SUNDAY,MONDAY,TUESDAY,WEDNESDAY,THURSDAY,FRIDAY,SATURDAY};
|
||||
|
|
@ -301,9 +301,9 @@ enum Days{SUNDAY,MONDAY,TUESDAY,WEDNESDAY,THURSDAY,FRIDAY,SATURDAY};
|
|||
This is 'effectively' converted into the following Octave code:
|
||||
</p>
|
||||
|
||||
<div class="targetlang"><pre>example.ICONST=42
|
||||
example.SCONST="Hello World"
|
||||
example.SUNDAY=0
|
||||
<div class="targetlang"><pre>swigexample.ICONST=42
|
||||
swigexample.SCONST="Hello World"
|
||||
swigexample.SUNDAY=0
|
||||
.... </pre></div>
|
||||
|
||||
<H3><a name="Octave_nn12"></a>30.3.5 Pointers</H3>
|
||||
|
|
@ -314,7 +314,7 @@ example.SUNDAY=0
|
|||
C/C++ pointers are fully supported by SWIG. Furthermore, SWIG has no problem working with incomplete type information. Given a wrapping of the <file.h> interface:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>%module example
|
||||
<div class="code"><pre>%module swigexample
|
||||
FILE *fopen(const char *filename, const char *mode);
|
||||
int fputs(const char *, FILE *);
|
||||
int fclose(FILE *);
|
||||
|
|
@ -325,18 +325,18 @@ When wrapped, you will be able to use the functions in a natural way from Octave
|
|||
</p>
|
||||
|
||||
<div class="targetlang"><pre>
|
||||
octave:1> example;
|
||||
octave:2> f=example.fopen("w","junk");
|
||||
octave:3> example.fputs("Hello world",f);
|
||||
octave:4> example.fclose(f);
|
||||
octave:1> swigexample;
|
||||
octave:2> f=swigexample.fopen("w","junk");
|
||||
octave:3> swigexample.fputs("Hello world",f);
|
||||
octave:4> swigexample.fclose(f);
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
Simply printing the value of a wrapped C++ type will print it's typename. E.g.,
|
||||
</p>
|
||||
|
||||
<div class="targetlang"><pre>octave:1> example;
|
||||
octave:2> f=example.fopen("junk","w");
|
||||
<div class="targetlang"><pre>octave:1> swigexample;
|
||||
octave:2> f=swigexample.fopen("junk","w");
|
||||
octave:3> f
|
||||
f =
|
||||
|
||||
|
|
@ -348,8 +348,8 @@ f =
|
|||
As the user of the pointer, you are responsible for freeing it, or closing any resources associated with it (just as you would in a C program). This does not apply so strictly to classes and structs (see below).
|
||||
</p>
|
||||
|
||||
<div class="targetlang"><pre>octave:1> example;
|
||||
octave:2> f=example.fopen("not there","r");
|
||||
<div class="targetlang"><pre>octave:1> swigexample;
|
||||
octave:2> f=swigexample.fopen("not there","r");
|
||||
error: value on right hand side of assignment is undefined
|
||||
error: evaluating assignment expression near line 2, column 2 </pre></div>
|
||||
|
||||
|
|
@ -371,8 +371,8 @@ For each wrapped structure and class, a <tt>swig_ref</tt> will be exposed that h
|
|||
</p>
|
||||
|
||||
<div class="targetlang">
|
||||
<pre>octave:1> example;
|
||||
octave:2> p=example.Point();
|
||||
<pre>octave:1> swigexample;
|
||||
octave:2> p=swigexample.Point();
|
||||
octave:3> p.x=3;
|
||||
octave:4> p.y=5;
|
||||
octave:5> p.x, p.y
|
||||
|
|
@ -406,9 +406,9 @@ public:
|
|||
can be used from Octave like this
|
||||
</p>
|
||||
<div class="targetlang">
|
||||
<pre>octave:1> example;
|
||||
octave:2> p1=example.Point(3,5);
|
||||
octave:3> p2=example.Point(1,2);
|
||||
<pre>octave:1> swigexample;
|
||||
octave:2> p1=swigexample.Point(3,5);
|
||||
octave:3> p2=swigexample.Point(1,2);
|
||||
octave:4> p1.distance(p2)
|
||||
ans = 3.6056
|
||||
</pre></div>
|
||||
|
|
@ -649,7 +649,7 @@ C++ class and function templates are fully supported as in other modules, in tha
|
|||
For example, function templates can be instantiated as follows:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>%module example
|
||||
<div class="code"><pre>%module swigexample
|
||||
%inline {
|
||||
template<class __scalar>
|
||||
__scalar mul(__scalar a,__scalar b) {
|
||||
|
|
@ -677,7 +677,7 @@ ans = 22 + 46i
|
|||
Similarly, class templates can be instantiated as in the following example,
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>%module example
|
||||
<div class="code"><pre>%module swigexample
|
||||
%include <std_complex.i>
|
||||
%include <std_string.i>
|
||||
%inline {
|
||||
|
|
|
|||
|
|
@ -12,13 +12,23 @@
|
|||
<ul>
|
||||
<li><a href="#Preface_nn2">Introduction</a>
|
||||
<li><a href="#Preface_nn4">SWIG Versions</a>
|
||||
<li><a href="#Preface_license">SWIG License</a>
|
||||
<li><a href="#Preface_nn5">SWIG resources</a>
|
||||
<li><a href="#Preface_nn6">Prerequisites</a>
|
||||
<li><a href="#Preface_nn7">Organization of this manual</a>
|
||||
<li><a href="#Preface_nn8">How to avoid reading the manual</a>
|
||||
<li><a href="#Preface_nn9">Backwards compatibility</a>
|
||||
<li><a href="#Preface_release_notes">Release notes</a>
|
||||
<li><a href="#Preface_nn10">Credits</a>
|
||||
<li><a href="#Preface_nn11">Bug reports</a>
|
||||
<li><a href="#Preface_installation">Installation</a>
|
||||
<ul>
|
||||
<li><a href="#Preface_windows_installation">Windows installation</a>
|
||||
<li><a href="#Preface_unix_installation">Unix installation</a>
|
||||
<li><a href="#Preface_osx_installation">Macintosh OS X installation</a>
|
||||
<li><a href="#Preface_testing">Testing</a>
|
||||
<li><a href="#Preface_examples">Examples</a>
|
||||
</ul>
|
||||
</ul>
|
||||
</div>
|
||||
<!-- INDEX -->
|
||||
|
|
@ -57,13 +67,26 @@ In the late 1990's, the most stable version of SWIG was release
|
|||
over a period of 10 years starting from the year 2000. The final version in the 1.3.x
|
||||
series was 1.3.40, but in truth the 1.3.x series had been stable for many years.
|
||||
An official stable version was released along with the decision to make SWIG
|
||||
license changes and this gave rise to version 2.0.0 in 2010. The license was clarified
|
||||
license changes and this gave rise to version 2.0.0 in 2010.
|
||||
</p>
|
||||
|
||||
<H2><a name="Preface_license"></a>1.3 SWIG License</H2>
|
||||
|
||||
|
||||
<p>
|
||||
The LICENSE file shipped with SWIG in the top level directory contains the SWIG license.
|
||||
For further insight into the license including the license of SWIG's output code, please visit
|
||||
the SWIG legal page - <a href="http://www.swig.org/legal.html">http://www.swig.org/legal.html</a>.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The license was clarified in version 2.0.0
|
||||
so that the code that SWIG generated could be distributed
|
||||
under license terms of the user's choice/requirements and at the same time the SWIG
|
||||
source was placed under the GNU General Public License version 3.
|
||||
</p>
|
||||
|
||||
<H2><a name="Preface_nn5"></a>1.3 SWIG resources</H2>
|
||||
<H2><a name="Preface_nn5"></a>1.4 SWIG resources</H2>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -102,7 +125,8 @@ about this can be obtained at:
|
|||
</pre></div>
|
||||
|
||||
|
||||
<H2><a name="Preface_nn6"></a>1.4 Prerequisites</H2>
|
||||
|
||||
<H2><a name="Preface_nn6"></a>1.5 Prerequisites</H2>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -127,7 +151,7 @@ However, this isn't meant to be a tutorial on C++ programming. For many
|
|||
of the gory details, you will almost certainly want to consult a good C++ reference. If you don't program
|
||||
in C++, you may just want to skip those parts of the manual.
|
||||
|
||||
<H2><a name="Preface_nn7"></a>1.5 Organization of this manual</H2>
|
||||
<H2><a name="Preface_nn7"></a>1.6 Organization of this manual</H2>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -139,7 +163,7 @@ can probably skip to that chapter and find almost everything you need
|
|||
to know.
|
||||
</p>
|
||||
|
||||
<H2><a name="Preface_nn8"></a>1.6 How to avoid reading the manual</H2>
|
||||
<H2><a name="Preface_nn8"></a>1.7 How to avoid reading the manual</H2>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -151,7 +175,7 @@ The SWIG distribution also comes with a large directory of
|
|||
examples that illustrate different topics.
|
||||
</p>
|
||||
|
||||
<H2><a name="Preface_nn9"></a>1.7 Backwards compatibility</H2>
|
||||
<H2><a name="Preface_nn9"></a>1.8 Backwards compatibility</H2>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -162,8 +186,8 @@ this isn't always possible as the
|
|||
primary goal over time is to make SWIG
|
||||
better---a process that would simply be impossible if the developers
|
||||
are constantly bogged down with backwards compatibility issues.
|
||||
Potential incompatibilities are clearly marked in the detailed release notes
|
||||
(CHANGES files).
|
||||
Potential incompatibilities are clearly marked in the detailed
|
||||
<a href="#Preface_release_notes">release notes</a>.
|
||||
</p>
|
||||
|
||||
|
||||
|
|
@ -187,7 +211,16 @@ Note: The version symbol is not defined in the generated SWIG
|
|||
wrapper file. The SWIG preprocessor has defined SWIG_VERSION since SWIG-1.3.11.
|
||||
</p>
|
||||
|
||||
<H2><a name="Preface_nn10"></a>1.8 Credits</H2>
|
||||
<H2><a name="Preface_release_notes"></a>1.9 Release notes</H2>
|
||||
|
||||
|
||||
<p>
|
||||
The CHANGES.current, CHANGES and RELEASENOTES files shipped with SWIG in the top level directory
|
||||
contain, respectively, detailed release notes for the current version,
|
||||
detailed release notes for previous releases and summary release notes from SWIG-1.3.22 onwards.
|
||||
</p>
|
||||
|
||||
<H2><a name="Preface_nn10"></a>1.10 Credits</H2>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -200,7 +233,7 @@ who have made contributions at all levels over time. Contributors
|
|||
are mentioned either in the COPYRIGHT file or CHANGES files shipped with SWIG or in submitted bugs.
|
||||
</p>
|
||||
|
||||
<H2><a name="Preface_nn11"></a>1.9 Bug reports</H2>
|
||||
<H2><a name="Preface_nn11"></a>1.11 Bug reports</H2>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -215,5 +248,204 @@ used, and any important pieces of the SWIG generated wrapper code. We
|
|||
can only fix bugs if we know about them.
|
||||
</p>
|
||||
|
||||
<H2><a name="Preface_installation"></a>1.12 Installation</H2>
|
||||
|
||||
|
||||
<H3><a name="Preface_windows_installation"></a>1.12.1 Windows installation</H3>
|
||||
|
||||
|
||||
<p>
|
||||
Please see the dedicated <a href="Windows.html">Windows chapter</a> for instructions on installing
|
||||
SWIG on Windows and running the examples. The Windows distribution is
|
||||
called swigwin and includes a prebuilt SWIG executable, swig.exe, included in
|
||||
the top level directory. Otherwise it is exactly the same as
|
||||
the main SWIG distribution. There is no need to download anything else.
|
||||
</p>
|
||||
|
||||
<H3><a name="Preface_unix_installation"></a>1.12.2 Unix installation</H3>
|
||||
|
||||
|
||||
<p>
|
||||
You must use <a href="http://www.gnu.org/software/make/">GNU make</a> to build and install SWIG.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
<a href="http://www.pcre.org/">PCRE</a>
|
||||
needs to be installed on your system to build SWIG, in particular
|
||||
pcre-config must be available. If you have PCRE headers and libraries but not
|
||||
pcre-config itself or, alternatively, wish to override the compiler or linker
|
||||
flags returned by pcre-config, you may set PCRE_LIBS and PCRE_CFLAGS variables
|
||||
to be used instead. And if you don't have PCRE at all, the configure script
|
||||
will provide instructions for obtaining it.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
To build and install SWIG, simply type the following:
|
||||
</p>
|
||||
|
||||
<div class="shell"><pre>
|
||||
$ ./configure
|
||||
$ make
|
||||
$ make install
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
By default SWIG installs itself in /usr/local. If you need to install SWIG in
|
||||
a different location or in your home directory, use the <tt>--prefix</tt> option
|
||||
to <tt>./configure</tt>. For example:
|
||||
</p>
|
||||
|
||||
<div class="shell"><pre>
|
||||
$ ./configure --prefix=/home/yourname/projects
|
||||
$ make
|
||||
$ make install
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
Note: the directory given to <tt>--prefix</tt> must be an absolute pathname. Do <b>not</b> use
|
||||
the ~ shell-escape to refer to your home directory. SWIG won't work properly
|
||||
if you do this.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The INSTALL file shipped in the top level directory details more about using configure. Also try
|
||||
</p>
|
||||
|
||||
<div class="shell"><pre>
|
||||
$ ./configure --help.
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
The configure script will attempt to locate various packages on your machine
|
||||
including Tcl, Perl5, Python and all the other target languages that SWIG
|
||||
supports. Don't panic if you get 'not found' messages -- SWIG does not need these
|
||||
packages to compile or run. The configure script is actually looking for
|
||||
these packages so that you can try out the SWIG examples contained
|
||||
in the 'Examples' directory without having to hack Makefiles.
|
||||
Note that the <tt>--without-xxx</tt> options, where xxx is a target language, have
|
||||
minimal effect. All they do is reduce the amount of testing done with
|
||||
'make check'. The SWIG executable and library files installed cannot currently
|
||||
be configured with a subset of target languages.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
SWIG used to include a set of runtime libraries for some languages for working
|
||||
with multiple modules. These are no longer built during the installation stage.
|
||||
However, users can build them just like any wrapper module as described in
|
||||
the <a href="Modules.html">Modules chapter</a>.
|
||||
The CHANGES file shipped with SWIG in the top level directory
|
||||
also lists some examples which build the runtime library.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Note:
|
||||
</p>
|
||||
|
||||
<ul>
|
||||
<li>
|
||||
If you checked the code out via Git, you will have to run <tt>./autogen.sh</tt>
|
||||
before <tt>./configure</tt>. In addition, a full build of SWIG requires
|
||||
a number of packages to be installed. Full instructions at
|
||||
<a href="http://www.swig.org/svn.html">SWIG bleeding edge</a>.
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<H3><a name="Preface_osx_installation"></a>1.12.3 Macintosh OS X installation</H3>
|
||||
|
||||
|
||||
<p>
|
||||
SWIG is known to work on various flavors of OS X. Follow the Unix installation
|
||||
instructions above. However, as of this writing, there is still great deal of
|
||||
inconsistency with how shared libaries are handled by various scripting languages
|
||||
on OS X.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Users of OS X should be aware that Darwin handles shared libraries and linking in
|
||||
a radically different way than most Unix systems. In order to test SWIG and run
|
||||
the examples, SWIG configures itself to use flat namespaces and to allow undefined
|
||||
symbols (<tt>-flat_namespace -undefined suppress</tt>). This mostly closely follows the Unix
|
||||
model and makes it more likely that the SWIG examples will work with whatever
|
||||
installation of software you might have. However, this is generally not the recommended
|
||||
technique for building larger extension modules. Instead, you should utilize
|
||||
Darwin's two-level namespaces. Some details about this can be found here
|
||||
|
||||
<a href="http://developer.apple.com/documentation/ReleaseNotes/DeveloperTools/TwoLevelNamespaces.html">http://developer.apple.com/documentation/ReleaseNotes/DeveloperTools/TwoLevelNamespaces.html</a>.
|
||||
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Needless to say, you might have to experiment a bit to get things working at first.
|
||||
</p>
|
||||
|
||||
<H3><a name="Preface_testing"></a>1.12.4 Testing</H3>
|
||||
|
||||
|
||||
<p>
|
||||
If you want to test SWIG after building it, a check can be performed on Unix operating systems.
|
||||
Type the following:
|
||||
</p>
|
||||
|
||||
<div class="shell"><pre>
|
||||
$ make -k check
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
This step can be performed either before or after installation.
|
||||
The check requires at least one of the target languages to be
|
||||
installed. If it fails, it may mean that you have an uninstalled
|
||||
language module or that the file 'Examples/Makefile' has been
|
||||
incorrectly configured. It may also fail due to compiler issues such
|
||||
as a broken C++ compiler. Even if the check fails, there is a
|
||||
pretty good chance SWIG still works correctly --- you will just have to
|
||||
mess around with one of the examples and some makefiles to get it to work.
|
||||
Some tests may also fail due to missing dependency packages, eg PCRE
|
||||
or Boost, but this will require careful analysis of the configure output
|
||||
done during configuration.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The test suite executed by the check is designed to stress-test
|
||||
many parts of the implementation including obscure corner cases. If some
|
||||
of these tests fail or generate warning messages, there is no reason for
|
||||
alarm --- the test may be related to some new SWIG feature or a difficult bug
|
||||
that we're trying to resolve. Chances are that SWIG will work just fine
|
||||
for you. Note that if you have more than one CPU/core, then you can use
|
||||
parallel make to speed up the check as it does take quite some time to run,
|
||||
for example:
|
||||
</p>
|
||||
|
||||
<div class="shell"><pre>
|
||||
$ make -j2 -k check
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
Also, SWIG's support for C++ is sufficiently advanced that certain
|
||||
tests may fail on older C++ compilers (for instance if your compiler
|
||||
does not support member templates). These errors are harmless if you
|
||||
don't intend to use these features in your own programs.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Note: The test-suite currently contains over 500 tests. If you
|
||||
have many different target languages installed and a slow machine, it
|
||||
might take more than an hour to run the test-suite.
|
||||
</p>
|
||||
|
||||
<H3><a name="Preface_examples"></a>1.12.5 Examples</H3>
|
||||
|
||||
|
||||
<p>
|
||||
The Examples directory contains a variety of examples of using SWIG
|
||||
and it has some browsable documentation. Simply point your browser to
|
||||
the file "Example/index.html".
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The Examples directory also includes Visual C++ project 6 (.dsp) files for
|
||||
building some of the examples on Windows. Later versions of Visual Studio
|
||||
will convert these old style project files into a current solution file.
|
||||
</p>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
|
|
|
|||
|
|
@ -795,7 +795,9 @@ If you need to build it on your own, the following notes are provided:
|
|||
You will need to create a DLL that can be loaded into the interpreter.
|
||||
This section briefly describes the use of SWIG with Microsoft Visual
|
||||
C++. As a starting point, many of SWIG's examples include project
|
||||
files. You might want to take a quick look at these in addition to
|
||||
files (.dsp files) for Visual C++ 6. These can be opened by more
|
||||
recent versions of Visual Studio.
|
||||
You might want to take a quick look at these examples in addition to
|
||||
reading this section.
|
||||
</p>
|
||||
|
||||
|
|
@ -868,6 +870,24 @@ set of Win32 debug or thread libraries. You will have to fiddle around with
|
|||
the build options of project to try and track this down.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
A 'Debug' build of the wrappers requires a debug build of the Python interpreter.
|
||||
This normally requires building the Python interpreter from source, which is not a
|
||||
job for the feint-hearted. Alternatively you can use the 'Release' build of the
|
||||
Python interpreter with a 'Debug' build of your wrappers by defining the <tt>SWIG_PYTHON_INTERPRETER_NO_DEBUG</tt>
|
||||
symbol under the preprocessor options. Or you can ensure this macro is defined at the beginning
|
||||
of the wrapper code using the following in your interface file, where <tt>_MSC_VER</tt> ensures it is
|
||||
only used by the Visual Studio compiler:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
%begin %{
|
||||
#ifdef _MSC_VER
|
||||
#define SWIG_PYTHON_INTERPRETER_NO_DEBUG
|
||||
#endif
|
||||
%}
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
Some users have reported success in building extension modules using Cygwin
|
||||
and other compilers. However, the problem of building usable DLLs with these
|
||||
|
|
@ -3294,6 +3314,53 @@ what can be done without having to rely on any of the more advanced
|
|||
customization features.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
There is also <tt>%pythonbegin</tt> which is another directive very similar to <tt>%pythoncode</tt>,
|
||||
but generates the given Python code at the beginning of the <tt>.py</tt> file.
|
||||
This directive works in the same way as <tt>%pythoncode</tt>, except the code is copied
|
||||
just after the SWIG banner (comment) at the top of the file, before any real code.
|
||||
This provides an opportunity to add your own description in a comment near the top of the file as well
|
||||
as Python imports that have to appear at the top of the file, such as "<tt>from __future__ import</tt>"
|
||||
statements.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The following shows example usage for Python 2.6 to use <tt>print</tt> as it can in Python 3, that is, as a function instead of a statement:
|
||||
</p>
|
||||
|
||||
<div class="code">
|
||||
<pre>
|
||||
%pythonbegin %{
|
||||
# This module provides wrappers to the Whizz Bang library
|
||||
%}
|
||||
|
||||
%pythonbegin %{
|
||||
from __future__ import print_function
|
||||
print("Loading", "Whizz", "Bang", sep=' ... ')
|
||||
%}
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
<p>
|
||||
which can be seen when viewing the first few lines of the generated <tt>.py</tt> file:
|
||||
</p>
|
||||
|
||||
<div class="code">
|
||||
<pre>
|
||||
# This file was automatically generated by SWIG (http://www.swig.org).
|
||||
# Version 2.0.11
|
||||
#
|
||||
# Do not make changes to this file unless you know what you are doing--modify
|
||||
# the SWIG interface file instead.
|
||||
|
||||
# This module provides wrappers to the Whizz Bang library
|
||||
|
||||
from __future__ import print_function
|
||||
print("Loading", "Whizz", "Bang", sep=' ... ')
|
||||
|
||||
</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
|
||||
|
|
|
|||
|
|
@ -1,9 +1,9 @@
|
|||
This directory contains the HTML for the SWIG users manual.
|
||||
|
||||
All of this HTML is hand-written. However, section numbering, indices,
|
||||
and the table of contents is generated automatically by the 'maketoc.py'
|
||||
and the table of contents are generated automatically by the 'maketoc.py'
|
||||
script. The Makefile has further information on how the various alternative
|
||||
forms of the documentation is generated from the hand-written HTML.
|
||||
forms of the documentation are generated from the hand-written HTML.
|
||||
|
||||
There are 4 types of boxes that code or whatever can be inside:
|
||||
- <div class="shell">...</div>
|
||||
|
|
|
|||
8701
Doc/Manual/Ruby.html
8701
Doc/Manual/Ruby.html
File diff suppressed because it is too large
Load diff
|
|
@ -258,7 +258,7 @@ this option the default output directory is the path to the input file.
|
|||
If <tt>-o</tt> and
|
||||
<tt>-outcurrentdir</tt> are used together, <tt>-outcurrentdir</tt> is effectively ignored
|
||||
as the output directory for the language files is the same directory as the
|
||||
generated C/C++ file if not overidden with <tt>-outdir</tt>.
|
||||
generated C/C++ file if not overridden with <tt>-outdir</tt>.
|
||||
</p>
|
||||
|
||||
<H3><a name="SWIG_nn5"></a>5.1.3 Comments</H3>
|
||||
|
|
@ -2699,7 +2699,7 @@ the following declaration :</p>
|
|||
<div class="code"><pre>
|
||||
/* file : vector.h */
|
||||
...
|
||||
typedef struct {
|
||||
typedef struct Vector {
|
||||
double x,y,z;
|
||||
} Vector;
|
||||
|
||||
|
|
@ -2772,7 +2772,7 @@ of the Vector structure. For example:</p>
|
|||
#include "vector.h"
|
||||
%}
|
||||
|
||||
typedef struct {
|
||||
typedef struct Vector {
|
||||
double x,y,z;
|
||||
%extend {
|
||||
Vector(double x, double y, double z) { ... }
|
||||
|
|
@ -2783,7 +2783,7 @@ typedef struct {
|
|||
</pre></div>
|
||||
|
||||
<p>
|
||||
Finally, <tt>%extend</tt> can be used to access externally written
|
||||
Note that <tt>%extend</tt> can be used to access externally written
|
||||
functions provided they follow the naming convention used in this
|
||||
example :</p>
|
||||
|
||||
|
|
@ -2814,7 +2814,7 @@ double Vector_magnitude(Vector *v) {
|
|||
#include "vector.h"
|
||||
%}
|
||||
|
||||
typedef struct {
|
||||
typedef struct Vector {
|
||||
double x,y,z;
|
||||
%extend {
|
||||
Vector(int,int,int); // This calls new_Vector()
|
||||
|
|
@ -2826,6 +2826,37 @@ typedef struct {
|
|||
</pre>
|
||||
</div>
|
||||
|
||||
<p>
|
||||
The name used for %extend should be the name of the struct and not the name of any typedef to the struct.
|
||||
For example:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
typedef struct Integer {
|
||||
int value;
|
||||
} Int;
|
||||
%extend Integer { ... } /* Correct name */
|
||||
%extend Int { ... } /* Incorrect name */
|
||||
|
||||
struct Float {
|
||||
float value;
|
||||
};
|
||||
typedef struct Float FloatValue;
|
||||
%extend Float { ... } /* Correct name */
|
||||
%extend FloatValue { ... } /* Incorrect name */
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
There is one exception to this rule and that is when the struct is anonymously named such as:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
typedef struct {
|
||||
double value;
|
||||
} Double;
|
||||
%extend Double { ... } /* Okay */
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
A little known feature of the <tt>%extend</tt> directive is that
|
||||
it can also be used to add synthesized attributes or to modify the
|
||||
|
|
@ -2862,7 +2893,7 @@ For example, consider this interface:
|
|||
|
||||
<div class="code">
|
||||
<pre>
|
||||
typedef struct {
|
||||
typedef struct Person {
|
||||
char name[50];
|
||||
...
|
||||
} Person;
|
||||
|
|
@ -2876,7 +2907,7 @@ the interface as follows to ensure this occurs whenever a name is read or writte
|
|||
|
||||
<div class="code">
|
||||
<pre>
|
||||
typedef struct {
|
||||
typedef struct Person {
|
||||
%extend {
|
||||
char name[50];
|
||||
}
|
||||
|
|
|
|||
|
|
@ -4433,7 +4433,7 @@ around some other class. For example:
|
|||
template<class T> class SmartPtr {
|
||||
T *pointee;
|
||||
public:
|
||||
...
|
||||
SmartPtr(T *p) : pointee(p) { ... }
|
||||
T *operator->() {
|
||||
return pointee;
|
||||
}
|
||||
|
|
@ -4453,7 +4453,7 @@ typedef SmartPtr<Foo_Impl> Foo;
|
|||
|
||||
// Create smart pointer Foo
|
||||
Foo make_Foo() {
|
||||
return SmartPtr(new Foo_Impl());
|
||||
return SmartPtr<Foo_Impl>(new Foo_Impl());
|
||||
}
|
||||
|
||||
// Do something with smart pointer Foo
|
||||
|
|
@ -4461,6 +4461,9 @@ void do_something(Foo f) {
|
|||
printf("x = %d\n", f->x);
|
||||
f->bar();
|
||||
}
|
||||
|
||||
// Call the wrapped smart pointer proxy class in the target language 'Foo'
|
||||
%template(Foo) SmartPtr<Foo_Impl>;
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
|
|
|
|||
|
|
@ -1,12 +1,12 @@
|
|||
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||||
<html>
|
||||
<head>
|
||||
<title>SWIG-2.0 Documentation</title>
|
||||
<title>SWIG-3.0 Documentation</title>
|
||||
</head>
|
||||
<body bgcolor="#ffffff">
|
||||
<H1><a name="Sections"></a>SWIG-2.0 Documentation</H1>
|
||||
<H1><a name="Sections"></a>SWIG-3.0 Documentation</H1>
|
||||
|
||||
Last update : SWIG-2.0.10 (in progress)
|
||||
Last update : SWIG-3.0.0 (in progress)
|
||||
|
||||
<H2>Sections</H2>
|
||||
|
||||
|
|
|
|||
|
|
@ -773,7 +773,7 @@ Here are some examples of valid typemap specifications:
|
|||
}
|
||||
|
||||
/* Typemap with modifiers */
|
||||
%typemap(in,doc="integer") int "$1 = gh_scm2int($input);";
|
||||
%typemap(in,doc="integer") int "$1 = scm_to_int($input);";
|
||||
|
||||
/* Typemap applied to patterns of multiple arguments */
|
||||
%typemap(in) (char *str, int len),
|
||||
|
|
|
|||
|
|
@ -398,7 +398,7 @@ int execlp(const char *path, const char *arg, ...);
|
|||
</div>
|
||||
|
||||
<p>
|
||||
Note that <tt>str3</tt> is the name of the last argument, as we have used <tt>%vargars</tt> with 3.
|
||||
Note that <tt>str3</tt> is the name of the last argument, as we have used <tt>%varargs</tt> with 3.
|
||||
Now <tt>execlp("a", "b", "c", "d", "e")</tt> will result in an error as one too many arguments has been passed,
|
||||
as now only 2 additional 'str' arguments can be passed with the 3rd one always using the specified default <tt>NULL</tt>.
|
||||
</p>
|
||||
|
|
@ -509,10 +509,10 @@ like this:
|
|||
|
||||
<div class="code">
|
||||
<pre>
|
||||
%typemap(in) (...)(char *args[10]) {
|
||||
%typemap(in) (...)(char *vargs[10]) {
|
||||
int i;
|
||||
int argc;
|
||||
for (i = 0; i < 10; i++) args[i] = 0;
|
||||
for (i = 0; i < 10; i++) vargs[i] = 0;
|
||||
argc = PyTuple_Size(varargs);
|
||||
if (argc > 10) {
|
||||
PyErr_SetString(PyExc_ValueError, "Too many arguments");
|
||||
|
|
@ -528,7 +528,7 @@ like this:
|
|||
return NULL;
|
||||
}
|
||||
pystr = PyUnicode_AsUTF8String(pyobj);
|
||||
str = PyBytes_AsString(pystr);
|
||||
str = strdup(PyBytes_AsString(pystr));
|
||||
Py_XDECREF(pystr);
|
||||
%#else
|
||||
if (!PyString_Check(pyobj)) {
|
||||
|
|
@ -537,22 +537,34 @@ like this:
|
|||
}
|
||||
str = PyString_AsString(pyobj);
|
||||
%#endif
|
||||
args[i] = str;
|
||||
vargs[i] = str;
|
||||
}
|
||||
$1 = (void *) args;
|
||||
$1 = (void *)vargs;
|
||||
}
|
||||
|
||||
%typemap(freearg) (...) {
|
||||
%#if PY_VERSION_HEX>=0x03000000
|
||||
int i;
|
||||
for (i = 0; i < 10; i++) {
|
||||
free(vargs$argnum[i]);
|
||||
}
|
||||
%#endif
|
||||
}
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
<p>
|
||||
In this typemap, the special variable <tt>varargs</tt> is a tuple
|
||||
In the 'in' typemap, the special variable <tt>varargs</tt> is a tuple
|
||||
holding all of the extra arguments passed (this is specific to the
|
||||
Python module). The typemap then pulls this apart and sticks the
|
||||
values into the array of strings <tt>args</tt>. Then, the array is
|
||||
assigned to <tt>$1</tt> (recall that this is the <tt>void *</tt>
|
||||
variable corresponding to <tt>(...)</tt>). However, this assignment
|
||||
is only half of the picture----clearly this alone is not enough to
|
||||
make the function work. To patch everything up, you have to rewrite the
|
||||
make the function work. The 'freearg' typemap cleans up memory
|
||||
allocated in the 'in' typemap; this code is generated to be called
|
||||
after the <tt>execlp</tt> function is called. To patch everything
|
||||
up, you have to rewrite the
|
||||
underlying action code using the <tt>%feature</tt> directive like
|
||||
this:
|
||||
</p>
|
||||
|
|
@ -560,9 +572,9 @@ this:
|
|||
<div class="code">
|
||||
<pre>
|
||||
%feature("action") execlp {
|
||||
char *args = (char **) arg3;
|
||||
result = execlp(arg1, arg2, args[0], args[1], args[2], args[3], args[4],
|
||||
args[5],args[6],args[7],args[8],args[9], NULL);
|
||||
char **vargs = (char **) arg3;
|
||||
result = execlp(arg1, arg2, vargs[0], vargs[1], vargs[2], vargs[3], vargs[4],
|
||||
vargs[5], vargs[6], vargs[7], vargs[8], vargs[9], NULL);
|
||||
}
|
||||
|
||||
int execlp(const char *path, const char *arg, ...);
|
||||
|
|
|
|||
|
|
@ -423,7 +423,8 @@ example.i(4) : Syntax error in input.
|
|||
<li>322. Redundant redeclaration of '<em>name</em>'.
|
||||
<li>323. Recursive scope inheritance of '<em>name</em>'.
|
||||
<li>324. Named nested template instantiations not supported. Processing as if no name was given to %template().
|
||||
<li>325. Nested class not currently supported (<em>name</em> ignored).
|
||||
<li>325. Nested <em>kind</em> not currently supported (<em>name</em> ignored).
|
||||
<li>326. Deprecated %extend name used - the <em>kind</em> name '<em>name</em>' should be used instead of the typedef name '<em>name</em>'.
|
||||
<li>350. operator new ignored.
|
||||
<li>351. operator delete ignored.
|
||||
<li>352. operator+ ignored.
|
||||
|
|
@ -527,6 +528,8 @@ example.i(4) : Syntax error in input.
|
|||
<li>519. %template() contains no name. Template method ignored: <em>declaration</em>
|
||||
<li>520. <em>Base/Derived</em> class '<em>classname1</em>' of '<em>classname2</em>' is not similarly marked as a smart pointer.
|
||||
<li>521. Illegal destructor name <em>name</em>. Ignored.
|
||||
<li>522. Use of an illegal constructor name '<em>name</em>' in %extend is deprecated, the constructor name should be '<em>name</em>'.
|
||||
<li>523. Use of an illegal destructor name '<em>name</em>' in %extend is deprecated, the destructor name should be '<em>name</em>'.
|
||||
</ul>
|
||||
|
||||
<H3><a name="Warnings_nn15"></a>14.9.6 Language module specific (700-899) </H3>
|
||||
|
|
|
|||
|
|
@ -147,7 +147,7 @@ PERL5_LIB: D:\nsPerl5.004_04\lib\CORE\perl.lib<br>
|
|||
|
||||
|
||||
<p>
|
||||
<b><tt>PYTHON_INCLUDE</tt></b> : Set this to the directory that contains python.h<br>
|
||||
<b><tt>PYTHON_INCLUDE</tt></b> : Set this to the directory that contains Python.h<br>
|
||||
<b><tt>PYTHON_LIB</tt></b> : Set this to the python library including path for linking<p>
|
||||
Example using Python 2.1.1:<br>
|
||||
<tt>
|
||||
|
|
|
|||
|
|
@ -1,25 +1,66 @@
|
|||
#
|
||||
# Patch managed by http://www.holgerschurig.de/patcher.html
|
||||
#
|
||||
# This patch is against htmldoc 1.8.24, and it hacks in support for
|
||||
# This patch is against htmldoc 1.8.27, and it hacks in support for
|
||||
# correctly indenting the <div class=""> sections in the SWIG manual.
|
||||
# This patch should only be used until the 1.9 branch of htmldoc
|
||||
# stabalizes, since the 1.9 branch includes true CSS1 support.
|
||||
# stabilizes, since the 1.9 branch includes true CSS1 support.
|
||||
#
|
||||
# This patch only affects the PDF generation, an unpatched htmldoc
|
||||
# creates the one-page html documentation just fine.
|
||||
#
|
||||
--- htmldoc-1.8.24/htmldoc/ps-pdf.cxx~margin-left
|
||||
+++ htmldoc-1.8.24/htmldoc/ps-pdf.cxx
|
||||
@@ -158,6 +158,7 @@
|
||||
diff -Naur htmldoc-1.8.27/htmldoc/htmldoc.cxx htmldoc-1.8.27-margin-left/htmldoc/htmldoc.cxx
|
||||
--- htmldoc-1.8.27/htmldoc/htmldoc.cxx 2006-03-30 14:01:20.000000000 +0100
|
||||
+++ htmldoc-1.8.27-margin-left/htmldoc/htmldoc.cxx 2013-05-11 10:11:47.428435647 +0100
|
||||
@@ -65,6 +65,8 @@
|
||||
const char *__XOS2RedirRoot(const char *);
|
||||
}
|
||||
#endif
|
||||
+
|
||||
+extern void parse_style(char *);
|
||||
|
||||
|
||||
/*
|
||||
@@ -1115,6 +1117,7 @@
|
||||
else if (compare_strings(argv[i], "--version", 6) == 0)
|
||||
{
|
||||
puts(SVERSION);
|
||||
+ puts("Patched with margin-left.patch");
|
||||
return (0);
|
||||
}
|
||||
else if (compare_strings(argv[i], "--webpage", 3) == 0)
|
||||
@@ -2403,6 +2406,10 @@
|
||||
}
|
||||
else if (strcmp(temp, "--cookies") == 0)
|
||||
file_cookies(temp2);
|
||||
+ else if (strcmp(temp, "--stylesheet") == 0)
|
||||
+ {
|
||||
+ parse_style(temp2);
|
||||
+ }
|
||||
}
|
||||
}
|
||||
|
||||
diff -Naur htmldoc-1.8.27/htmldoc/Makefile htmldoc-1.8.27-margin-left/htmldoc/Makefile
|
||||
--- htmldoc-1.8.27/htmldoc/Makefile 2005-10-28 21:32:59.000000000 +0100
|
||||
+++ htmldoc-1.8.27-margin-left/htmldoc/Makefile 2013-05-11 09:39:04.392367869 +0100
|
||||
@@ -36,7 +36,7 @@
|
||||
OBJS = gui.o file.o html.o htmldoc.o htmllib.o htmlsep.o \
|
||||
http.o http-addr.o http-addrlist.o http-support.o image.o \
|
||||
iso8859.o license.o md5.o progress.o ps-pdf.o rc4.o \
|
||||
- snprintf.o string.o toc.o util.o
|
||||
+ snprintf.o string.o toc.o util.o style.o
|
||||
|
||||
|
||||
#
|
||||
diff -Naur htmldoc-1.8.27/htmldoc/ps-pdf.cxx htmldoc-1.8.27-margin-left/htmldoc/ps-pdf.cxx
|
||||
--- htmldoc-1.8.27/htmldoc/ps-pdf.cxx 2006-08-01 17:58:50.000000000 +0100
|
||||
+++ htmldoc-1.8.27-margin-left/htmldoc/ps-pdf.cxx 2013-05-11 09:37:40.096364957 +0100
|
||||
@@ -160,6 +160,7 @@
|
||||
# undef page_t
|
||||
#endif // __hpux
|
||||
|
||||
+extern int lookup_div_class(uchar *);
|
||||
|
||||
/*
|
||||
* Constants...
|
||||
@@ -4188,9 +4189,24 @@
|
||||
* Output options...
|
||||
@@ -4230,9 +4231,24 @@
|
||||
para->child = para->last_child = NULL;
|
||||
}
|
||||
|
||||
|
|
@ -45,30 +86,9 @@
|
|||
if (para->child != NULL)
|
||||
{
|
||||
parse_paragraph(para, *left, *right, *bottom, *top, x, y, page, *needspace);
|
||||
--- htmldoc-1.8.24/htmldoc/htmldoc.cxx~margin-left
|
||||
+++ htmldoc-1.8.24/htmldoc/htmldoc.cxx
|
||||
@@ -62,6 +62,8 @@
|
||||
const char *__XOS2RedirRoot(const char *);
|
||||
}
|
||||
#endif
|
||||
+
|
||||
+extern void parse_style(char *);
|
||||
|
||||
|
||||
/*
|
||||
@@ -2140,6 +2142,10 @@
|
||||
}
|
||||
else if (strcmp(temp, "--cookies") == 0)
|
||||
file_cookies(temp2);
|
||||
+ else if (strcmp(temp, "--stylesheet") == 0)
|
||||
+ {
|
||||
+ parse_style(temp2);
|
||||
+ }
|
||||
}
|
||||
}
|
||||
|
||||
--- /dev/null
|
||||
+++ htmldoc-1.8.24/htmldoc/style.cxx
|
||||
diff -Naur htmldoc-1.8.27/htmldoc/style.cxx htmldoc-1.8.27-margin-left/htmldoc/style.cxx
|
||||
--- htmldoc-1.8.27/htmldoc/style.cxx 1970-01-01 01:00:00.000000000 +0100
|
||||
+++ htmldoc-1.8.27-margin-left/htmldoc/style.cxx 2013-05-11 09:37:40.096364957 +0100
|
||||
@@ -0,0 +1,185 @@
|
||||
+/* Extreamly simple parsing routines for CSS style sheets.
|
||||
+ * We only parse div.class { } sections, and only look
|
||||
|
|
@ -255,15 +275,3 @@
|
|||
+
|
||||
+ fclose(f);
|
||||
+}
|
||||
--- htmldoc-1.8.24/htmldoc/Makefile~margin-left
|
||||
+++ htmldoc-1.8.24/htmldoc/Makefile
|
||||
@@ -35,7 +35,7 @@
|
||||
|
||||
OBJS = gui.o file.o html.o htmldoc.o htmllib.o htmlsep.o http.o \
|
||||
http-addr.o http-support.o image.o iso8859.o license.o md5.o \
|
||||
- progress.o ps-pdf.o rc4.o snprintf.o string.o toc.o util.o
|
||||
+ progress.o ps-pdf.o rc4.o snprintf.o string.o toc.o util.o style.o
|
||||
|
||||
|
||||
#
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue