Update examples to talk about a version of Perl which we actually still
support. Use $ for the shell prompt character, since that matches what most users will see. Compile code for shared use with -fPIC, since that's required for most architectures, and a good idea even on x86. Fix Sun C++ example to use CC not g++ for invoking the compiler. Drop space before colon in prose. git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk@12959 626c5289-ae23-0410-ae9c-e8d60b6d4f22
This commit is contained in:
Olly Betts
parent
7e6638ab61
commit
7d6da8d319
1 changed files with 71 additions and 73 deletions
|
|
@ -113,7 +113,7 @@ options are found near the end of the chapter.
|
|||
|
||||
<p>
|
||||
To build a Perl5 module, run SWIG using the <tt>-perl</tt> option as
|
||||
follows :
|
||||
follows:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
|
|
@ -137,7 +137,7 @@ To build the module, you will need to compile the file
|
|||
|
||||
|
||||
<p>
|
||||
In order to compile, SWIG extensions need the following Perl5 header files :</p>
|
||||
In order to compile, SWIG extensions need the following Perl5 header files:</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
#include "Extern.h"
|
||||
|
|
@ -149,19 +149,19 @@ In order to compile, SWIG extensions need the following Perl5 header files :</p>
|
|||
These are typically located in a directory like this</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
/usr/lib/perl5/5.00503/i386-linux/CORE
|
||||
/usr/lib/perl/5.14/CORE
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
The SWIG configuration script automatically tries to locate this directory so
|
||||
that it can compile examples. However, if you need to find out where the directory is
|
||||
loaded, an easy way to find out is to run Perl itself.
|
||||
located, an easy way to find out is to ask Perl itself:
|
||||
</p>
|
||||
|
||||
<div class="code">
|
||||
<pre>
|
||||
% perl -e 'use Config; print $Config{archlib};'
|
||||
/usr/lib/perl5/5.00503/i386-linux
|
||||
$ perl -e 'use Config; print "$Config{archlib}\n";'
|
||||
/usr/lib/perl/5.14
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
|
|
@ -176,9 +176,9 @@ using commands like this (shown for Linux):
|
|||
|
||||
<div class="code"><pre>
|
||||
$ swig -perl example.i
|
||||
% gcc example.c
|
||||
% gcc -c example_wrap.c -I/usr/lib/perl5/5.00503/i386-linux/CORE -Dbool=char
|
||||
% gcc -shared example.o example_wrap.o -o example.so
|
||||
$ gcc -fPIC example.c
|
||||
$ gcc -fPIC -c example_wrap.c -I/usr/lib/perl/5.14/CORE -Dbool=char
|
||||
$ gcc -shared example.o example_wrap.o -o example.so
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
|
|
@ -204,7 +204,7 @@ the target should be named `<tt>example.so</tt>',
|
|||
<p>
|
||||
It is also possible to use Perl to build dynamically loadable modules
|
||||
for you using the MakeMaker utility. To do this, write a Perl
|
||||
script such as the following :</p>
|
||||
script such as the following:</p>
|
||||
|
||||
<div class="targetlang"><pre>
|
||||
# File : Makefile.PL
|
||||
|
|
@ -218,12 +218,12 @@ WriteMakefile(
|
|||
</pre></div>
|
||||
|
||||
<p>
|
||||
Now, to build a module, simply follow these steps :</p>
|
||||
Now, to build a module, simply follow these steps:</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
% perl Makefile.PL
|
||||
% make
|
||||
% make install
|
||||
$ perl Makefile.PL
|
||||
$ make
|
||||
$ make install
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
|
|
@ -239,10 +239,10 @@ and Randal Schwartz.</p>
|
|||
If you machine does not support dynamic loading or if you've tried to
|
||||
use it without success, you can build a new version of the Perl
|
||||
interpreter with your SWIG extensions added to it. To build a static
|
||||
extension, you first need to invoke SWIG as follows :</p>
|
||||
extension, you first need to invoke SWIG as follows:</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
% swig -perl -static example.i
|
||||
$ swig -perl -static example.i
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
|
|
@ -253,7 +253,7 @@ By default SWIG includes code for dynamic loading, but the
|
|||
Next, you will need to supply a <tt>main()</tt> function that
|
||||
initializes your extension and starts the Perl interpreter. While,
|
||||
this may sound daunting, SWIG can do this for you automatically as
|
||||
follows :</p>
|
||||
follows:</p>
|
||||
|
||||
<div class="targetlang"><pre>
|
||||
%module example
|
||||
|
|
@ -268,10 +268,10 @@ extern int fact(int);
|
|||
</pre></div>
|
||||
|
||||
<p>
|
||||
The same thing can be accomplished by running SWIG as follows :</p>
|
||||
The same thing can be accomplished by running SWIG as follows:</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
% swig -perl -static -lperlmain.i example.i
|
||||
$ swig -perl -static -lperlmain.i example.i
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
|
|
@ -290,7 +290,7 @@ for a dynamic module, but change the link line to something like this:
|
|||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
% gcc example.o example_wrap.o -L/usr/lib/perl5/5.00503/i386-linux/CORE \
|
||||
$ gcc example.o example_wrap.o -L/usr/lib/perl/5.14/CORE \
|
||||
-lperl -lsocket -lnsl -lm -o myperl
|
||||
</pre></div>
|
||||
|
||||
|
|
@ -323,9 +323,7 @@ A common error received by first-time users is the following:
|
|||
<div class="targetlang">
|
||||
<pre>
|
||||
use example;
|
||||
Can't locate example.pm in @INC (@INC contains: /usr/lib/perl5/5.00503/i386-lin
|
||||
ux /usr/lib/perl5/5.00503 /usr/lib/perl5/site_perl/5.005/i386-linux /usr/lib/pe
|
||||
rl5/site_perl/5.005 .) at - line 1.
|
||||
Can't locate example.pm in @INC (@INC contains: /etc/perl /usr/local/lib/perl/5.14.2 /usr/local/share/perl/5.14.2 /usr/lib/perl5 /usr/share/perl5 /usr/lib/perl/5.14 /usr/share/perl/5.14 /usr/local/lib/site_perl .) at - line 1.
|
||||
BEGIN failed--compilation aborted at - line 1.
|
||||
</pre>
|
||||
</div>
|
||||
|
|
@ -363,7 +361,7 @@ Another common error is the following:
|
|||
<pre>
|
||||
use example;
|
||||
Can't load './example.so' for module example: ./example.so:
|
||||
undefined symbol: Foo at /usr/lib/perl5/5.00503/i386-linux/DynaLoader.pm line 169.
|
||||
undefined symbol: Foo at /usr/lib/perl/5.14/i386-linux/DynaLoader.pm line 169.
|
||||
|
||||
at - line 1
|
||||
BEGIN failed--compilation aborted at - line 1.
|
||||
|
|
@ -409,7 +407,7 @@ error when you try to use your module:
|
|||
<pre>
|
||||
use example;
|
||||
Can't load './example.so' for module example: libfoo.so: cannot open shared object file:
|
||||
No such file or directory at /usr/lib/perl5/5.00503/i386-linux/DynaLoader.pm line 169.
|
||||
No such file or directory at /usr/lib/perl/5.14/i386-linux/DynaLoader.pm line 169.
|
||||
|
||||
at - line 1
|
||||
BEGIN failed--compilation aborted at - line 1.
|
||||
|
|
@ -472,10 +470,10 @@ compiler. For example:
|
|||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
% swig -c++ -perl example.i
|
||||
% g++ -c example.cxx
|
||||
% g++ -c example_wrap.cxx -I/usr/lib/perl5/5.00503/i386-linux/CORE
|
||||
% <b>g++ -shared example.o example_wrap.o -o example.so</b>
|
||||
$ swig -c++ -perl example.i
|
||||
$ g++ -fPIC -c example.cxx
|
||||
$ g++ -fPIC -c example_wrap.cxx -I/usr/lib/perl/5.14/i386-linux/CORE
|
||||
$ <b>g++ -shared example.o example_wrap.o -o example.so</b>
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
|
|
@ -485,10 +483,10 @@ Solaris, you often need to add an extra library <tt>-lCrun</tt> like this:
|
|||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
% swig -c++ -perl example.i
|
||||
% g++ -c example.cxx
|
||||
% g++ -c example_wrap.cxx -I/usr/lib/perl5/5.00503/i386-linux/CORE
|
||||
% g++ -shared example.o example_wrap.o -o example.so <b>-lCrun</b>
|
||||
$ swig -c++ -perl example.i
|
||||
$ CC -c example.cxx
|
||||
$ CC -c example_wrap.cxx -I/usr/lib/perl/5.14/i386-linux/CORE
|
||||
$ CC -shared example.o example_wrap.o -o example.so <b>-lCrun</b>
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
|
|
@ -503,7 +501,7 @@ it needs to be. So you should compile the wrapper like:
|
|||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
% g++ -c example_wrap.cxx -I/usr/lib/perl/5.8.0/CORE -D_GNU_SOURCE
|
||||
$ g++ -fPIC -c example_wrap.cxx -I/usr/lib/perl/5.8.0/CORE -D_GNU_SOURCE
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
|
|
@ -511,7 +509,7 @@ it needs to be. So you should compile the wrapper like:
|
|||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
% perl -e 'use Config; print $Config{ccflags};'
|
||||
$ perl -e 'use Config; print "$Config{ccflags}\n";'
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
|
|
@ -519,8 +517,8 @@ So you could also compile the wrapper like
|
|||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
% g++ -c example_wrap.cxx -I/usr/lib/perl/5.8.0/CORE \
|
||||
`perl -e 'use Config; print $Config{ccflags}'`
|
||||
$ g++ -fPIC -c example_wrap.cxx -I/usr/lib/perl/5.8.0/CORE \
|
||||
`perl -MConfig -e 'print $Config{ccflags}'`
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
|
|
@ -568,8 +566,8 @@ can behave strangely when working with multiple modules.
|
|||
|
||||
<p>
|
||||
It should be noted that you may get a lot of error messages
|
||||
about the `<tt>bool</tt>' datatype when compiling a C++ Perl module. If
|
||||
you experience this problem, you can try the following :</p>
|
||||
about the '<tt>bool</tt>' datatype when compiling a C++ Perl module. If
|
||||
you experience this problem, you can try the following:</p>
|
||||
|
||||
<ul>
|
||||
<li>Use <tt>-DHAS_BOOL</tt> when compiling the SWIG wrapper code
|
||||
|
|
@ -643,7 +641,7 @@ although the procedure may be similar with other compilers.
|
|||
<p>
|
||||
If you are developing your application within Microsoft developer
|
||||
studio, SWIG can be invoked as a custom build option. The process
|
||||
roughly requires these steps :</p>
|
||||
roughly requires these steps:</p>
|
||||
|
||||
<ul>
|
||||
<li>Open up a new workspace and use the AppWizard to select a DLL
|
||||
|
|
@ -651,7 +649,7 @@ project.
|
|||
|
||||
<li>Add both the SWIG interface file (the .i file), any supporting C
|
||||
files, and the name of the wrapper file that will be created by SWIG
|
||||
(ie. <tt>example_wrap.c</tt>). Note : If using C++, choose a
|
||||
(ie. <tt>example_wrap.c</tt>). Note: If using C++, choose a
|
||||
different suffix for the wrapper file such as
|
||||
<tt>example_wrap.cxx</tt>. Don't worry if the wrapper file doesn't
|
||||
exist yet--Developer studio will keep a reference to it around.
|
||||
|
|
@ -689,7 +687,7 @@ Now, assuming you made it this far, SWIG will be automatically invoked when
|
|||
you build your project. Any changes made to the interface file will
|
||||
result in SWIG being automatically invoked to produce a new version of
|
||||
the wrapper file. To run your new Perl extension, simply run Perl and
|
||||
use the use command as normal. For example :
|
||||
use the use command as normal. For example:
|
||||
</p>
|
||||
|
||||
<div class="targetlang"><pre>
|
||||
|
|
@ -758,7 +756,7 @@ double Spam;
|
|||
</pre></div>
|
||||
|
||||
<p>
|
||||
is accessed as follows :</p>
|
||||
is accessed as follows:</p>
|
||||
|
||||
<div class="targetlang"><pre>
|
||||
use example;
|
||||
|
|
@ -858,7 +856,7 @@ print example::FOO,"\n";
|
|||
SWIG represents pointers as blessed references. A blessed reference
|
||||
is the same as a Perl reference except that it has additional
|
||||
information attached to it indicating what kind of reference it
|
||||
is. That is, if you have a C declaration like this :</p>
|
||||
is. That is, if you have a C declaration like this:</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
Matrix *new_Matrix(int n, int m);
|
||||
|
|
@ -880,7 +878,7 @@ generated.</p>
|
|||
|
||||
<p>
|
||||
To check to see if a value is the NULL pointer, use the
|
||||
<tt>defined()</tt> command :</p>
|
||||
<tt>defined()</tt> command:</p>
|
||||
|
||||
<div class="targetlang"><pre>
|
||||
if (defined($ptr)) {
|
||||
|
|
@ -904,7 +902,7 @@ In general, <tt>$a</tt> and <tt>$b</tt> will be different--since they
|
|||
are different references. Thus, it is a mistake to check the equality
|
||||
of <tt>$a</tt> and <tt>$b</tt> to check the equality of two C
|
||||
pointers. The correct method to check equality of C pointers is to
|
||||
dereference them as follows :
|
||||
dereference them as follows:
|
||||
</p>
|
||||
|
||||
<div class="targetlang"><pre>
|
||||
|
|
@ -1099,7 +1097,7 @@ void Bar_f_set(Bar *b, Foo *val) {
|
|||
|
||||
<p>
|
||||
C++ classes are wrapped by building a set of low level accessor functions.
|
||||
Consider the following class :
|
||||
Consider the following class:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
|
|
@ -1117,7 +1115,7 @@ static void print(List *l);
|
|||
</pre></div>
|
||||
|
||||
<p>
|
||||
When wrapped by SWIG, the following functions are created :
|
||||
When wrapped by SWIG, the following functions are created:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
|
|
@ -1272,11 +1270,11 @@ The following C++ operators are currently supported by the Perl module:
|
|||
<p>
|
||||
When you create a SWIG extension, everything gets placed into
|
||||
a single Perl module. The name of the module is determined by the
|
||||
<tt>%module</tt> directive. To use the module, do the following :
|
||||
<tt>%module</tt> directive. To use the module, do the following:
|
||||
</p>
|
||||
|
||||
<div class="targetlang"><pre>
|
||||
% perl5
|
||||
$ perl5
|
||||
use example; # load the example module
|
||||
print example::fact(4),"\n" # Call a function in it
|
||||
24
|
||||
|
|
@ -1342,17 +1340,17 @@ nested namespace simply provide the fully qualified name in your
|
|||
<!--
|
||||
<p>
|
||||
This can be changed by giving SWIG the -package
|
||||
option :
|
||||
option:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
% swig -perl -package Foo example.i
|
||||
$ swig -perl -package Foo example.i
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
In this case, you still create a module called `<tt>example</tt>' exactly as before, but
|
||||
all of the functions in that module will be installed into the package
|
||||
`<tt>Foo</tt>.' For example :
|
||||
`<tt>Foo</tt>.' For example:
|
||||
</p>
|
||||
|
||||
<div class="targetlang"><pre>
|
||||
|
|
@ -1588,7 +1586,7 @@ The SWIG <tt>%exception</tt> directive can be used to create a
|
|||
user-definable exception handler for converting exceptions in your
|
||||
C/C++ program into Perl exceptions. The chapter on customization features
|
||||
contains more details, but suppose you have a C++ class like the
|
||||
following :
|
||||
following:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
|
|
@ -1796,7 +1794,7 @@ The <tt>$input</tt> variable is the input object (usually a <tt>SV *</tt>).
|
|||
</p>
|
||||
|
||||
<p>
|
||||
When this example is used in Perl5, it will operate as follows :
|
||||
When this example is used in Perl5, it will operate as follows:
|
||||
</p>
|
||||
|
||||
<div class="targetlang"><pre>
|
||||
|
|
@ -1805,7 +1803,7 @@ $n = example::fact(6);
|
|||
print "$n\n";
|
||||
...
|
||||
|
||||
Output :
|
||||
Output:
|
||||
Received an integer : 6
|
||||
720
|
||||
</pre></div>
|
||||
|
|
@ -2200,7 +2198,7 @@ char **get_args() {
|
|||
|
||||
<p>
|
||||
When this module is compiled, the wrapped C functions can be used in a
|
||||
Perl script as follows :
|
||||
Perl script as follows:
|
||||
</p>
|
||||
|
||||
<div class="targetlang"><pre>
|
||||
|
|
@ -2227,7 +2225,7 @@ number of output values.
|
|||
<p>
|
||||
The total number of return values should not exceed the number of
|
||||
input values unless you explicitly extend the argument stack. This
|
||||
can be done using the <tt>EXTEND()</tt> macro as in :
|
||||
can be done using the <tt>EXTEND()</tt> macro as in:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
|
|
@ -2286,7 +2284,7 @@ int multout(double a, double b, double *OUTPUT, double *OUTPUT);
|
|||
<p>
|
||||
When this function is called, the output arguments are appended to the stack used
|
||||
to return results. This shows up an array in Perl.
|
||||
For example :
|
||||
For example:
|
||||
</p>
|
||||
|
||||
<div class="targetlang"><pre>
|
||||
|
|
@ -2299,7 +2297,7 @@ print "multout(7,13) = @r\n";
|
|||
|
||||
|
||||
<p>
|
||||
Consider the following data structure :
|
||||
Consider the following data structure:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
|
|
@ -2364,7 +2362,7 @@ to copy the converted array into a C data structure.
|
|||
<p>
|
||||
A frequent confusion on the SWIG mailing list is errors caused by the
|
||||
mixing of Perl references and C pointers. For example, suppose you
|
||||
have a C function that modifies its arguments like this :
|
||||
have a C function that modifies its arguments like this:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
|
|
@ -2374,7 +2372,7 @@ void add(double a, double b, double *c) {
|
|||
</pre></div>
|
||||
|
||||
<p>
|
||||
A common misinterpretation of this function is the following Perl script :
|
||||
A common misinterpretation of this function is the following Perl script:
|
||||
</p>
|
||||
|
||||
<div class="targetlang"><pre>
|
||||
|
|
@ -2411,7 +2409,7 @@ To make this work with a reference, you can use a typemap such as this:
|
|||
</pre></div>
|
||||
|
||||
<p>
|
||||
Now, if you place this before the add function, you can do this :
|
||||
Now, if you place this before the add function, you can do this:
|
||||
</p>
|
||||
|
||||
<div class="targetlang"><pre>
|
||||
|
|
@ -2544,7 +2542,7 @@ high level wrappers. The wrappers, in turn, interact with the low-level procedu
|
|||
|
||||
|
||||
<p>
|
||||
Suppose you have the following SWIG interface file :
|
||||
Suppose you have the following SWIG interface file:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
|
|
@ -2672,7 +2670,7 @@ $v->DESTROY();
|
|||
<p>
|
||||
In order for proxy classes to work properly, it is necessary for Perl
|
||||
to manage some mechanism of object ownership. Here's the crux of the
|
||||
problem---suppose you had a function like this :
|
||||
problem---suppose you had a function like this:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
|
|
@ -2685,7 +2683,7 @@ Vector *Vector_get(Vector *v, int index) {
|
|||
This function takes a Vector pointer and returns a pointer to another
|
||||
Vector. Such a function might be used to manage arrays or lists of
|
||||
vectors (in C). Now contrast this function with the constructor for a
|
||||
Vector object :
|
||||
Vector object:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
|
|
@ -2757,7 +2755,7 @@ sophisticated languages.
|
|||
|
||||
|
||||
<p>
|
||||
Suppose that we have a new object that looks like this :
|
||||
Suppose that we have a new object that looks like this:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
|
|
@ -2774,7 +2772,7 @@ struct Particle {
|
|||
In this case, the members of the structure are complex objects that
|
||||
have already been encapsulated in a Perl proxy class. To handle
|
||||
these correctly, we use the <tt>%BLESSEDMEMBERS</tt> hash which would
|
||||
look like this (along with some supporting code) :
|
||||
look like this (along with some supporting code):
|
||||
</p>
|
||||
|
||||
<div class="targetlang"><pre>
|
||||
|
|
@ -2796,7 +2794,7 @@ unmodified.
|
|||
</p>
|
||||
|
||||
<p>
|
||||
This implementation allows us to operate on nested structures as follows :
|
||||
This implementation allows us to operate on nested structures as follows:
|
||||
</p>
|
||||
|
||||
<div class="targetlang"><pre>
|
||||
|
|
@ -2811,7 +2809,7 @@ $p->{f}->{x} = 0.0;
|
|||
|
||||
<p>
|
||||
When functions take arguments involving a complex object, it is
|
||||
sometimes necessary to write a proxy function. For example :
|
||||
sometimes necessary to write a proxy function. For example:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
|
|
@ -2822,7 +2820,7 @@ double dot_product(Vector *v1, Vector *v2);
|
|||
Since Vector is an object already wrapped into a proxy class, we need
|
||||
to modify this function to accept arguments that are given in the form
|
||||
of tied hash tables. This is done by creating a Perl function like
|
||||
this :
|
||||
this:
|
||||
</p>
|
||||
|
||||
<div class="targetlang"><pre>
|
||||
|
|
@ -2846,7 +2844,7 @@ identical manner.
|
|||
<p>
|
||||
Simple C++ inheritance is handled using the Perl <tt>@ISA</tt> array
|
||||
in each class package. For example, if you have the following
|
||||
interface file :
|
||||
interface file:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
|
|
@ -2881,7 +2879,7 @@ public:
|
|||
</pre></div>
|
||||
|
||||
<p>
|
||||
The resulting, Perl wrapper class will create the following code :
|
||||
The resulting, Perl wrapper class will create the following code:
|
||||
</p>
|
||||
|
||||
<div class="targetlang"><pre>
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue