/trunk/Doc/Manual/Pike.html
HTML | 245 lines | 186 code | 57 blank | 2 comment | 0 complexity | 1615c1434c17c14789ad92e843f47f5b MD5 | raw file
Possible License(s): LGPL-2.1, Cube, GPL-3.0, 0BSD, GPL-2.0
- <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
- <html>
- <head>
- <title>SWIG and Pike</title>
- <link rel="stylesheet" type="text/css" href="style.css">
- </head>
- <body bgcolor="#ffffff">
- <H1><a name="Pike"></a>33 SWIG and Pike</H1>
- <!-- INDEX -->
- <div class="sectiontoc">
- <ul>
- <li><a href="#Pike_nn2">Preliminaries</a>
- <ul>
- <li><a href="#Pike_nn3">Running SWIG</a>
- <li><a href="#Pike_nn4">Getting the right header files</a>
- <li><a href="#Pike_nn5">Using your module</a>
- </ul>
- <li><a href="#Pike_nn6">Basic C/C++ Mapping</a>
- <ul>
- <li><a href="#Pike_nn7">Modules</a>
- <li><a href="#Pike_nn8">Functions</a>
- <li><a href="#Pike_nn9">Global variables</a>
- <li><a href="#Pike_nn10">Constants and enumerated types</a>
- <li><a href="#Pike_nn11">Constructors and Destructors</a>
- <li><a href="#Pike_nn12">Static Members</a>
- </ul>
- </ul>
- </div>
- <!-- INDEX -->
- <p>
- This chapter describes SWIG support for Pike. As of this writing, the
- SWIG Pike module is still under development and is not considered
- ready for prime time. The Pike module is being developed against the
- Pike 7.4.10 release and may not be compatible with previous versions
- of Pike.
- </p>
- <p>
- This chapter covers most SWIG features, but certain low-level details
- are covered in less depth than in earlier chapters. At the very
- least, make sure you read the "<a href="SWIG.html#SWIG">SWIG Basics</a>"
- chapter.<br>
- </p>
- <H2><a name="Pike_nn2"></a>33.1 Preliminaries</H2>
- <H3><a name="Pike_nn3"></a>33.1.1 Running SWIG</H3>
- <p>
- Suppose that you defined a SWIG module such as the following:
- </p>
- <div class="code">
- <pre>%module example<br><br>%{<br>#include "example.h"<br>%}<br><br>int fact(int n);<br></pre>
- </div>
- <p>
- To build a C extension module for Pike, run SWIG using the <tt>-pike</tt> option :
- </p>
- <div class="code">
- <pre>$ <b>swig -pike example.i</b><br></pre>
- </div>
- <p>
- If you're building a C++ extension, be sure to add the <tt>-c++</tt> option:
- </p>
- <div class="code">
- <pre>$ <b>swig -c++ -pike example.i</b><br></pre>
- </div>
- <p>
- This creates a single source file named <tt>example_wrap.c</tt> (or <tt>example_wrap.cxx</tt>, if you
- ran SWIG with the <tt>-c++</tt> option).
- The SWIG-generated source file contains the low-level wrappers that need
- to be compiled and linked with the rest of your C/C++ application to
- create an extension module.
- </p>
- <p>
- The name of the wrapper file is derived from the name of the input
- file. For example, if the input file is <tt>example.i</tt>, the name
- of the wrapper file is <tt>example_wrap.c</tt>. To change this, you
- can use the <tt>-o</tt> option:
- </p>
- <div class="code">
- <pre>$ <b>swig -pike -o pseudonym.c example.i</b><br></pre>
- </div>
- <H3><a name="Pike_nn4"></a>33.1.2 Getting the right header files</H3>
- <p>
- In order to compile the C/C++ wrappers, the compiler needs to know the
- path to the Pike header files. These files are usually contained in a
- directory such as
- </p>
- <div class="code">
- <pre>/usr/local/pike/7.4.10/include/pike<br></pre>
- </div>
- <p>
- There doesn't seem to be any way to get Pike itself to reveal the
- location of these files, so you may need to hunt around for them.
- You're looking for files with the names <tt>global.h</tt>, <tt>program.h</tt>
- and so on.
- </p>
- <H3><a name="Pike_nn5"></a>33.1.3 Using your module</H3>
- <p>
- To use your module, simply use Pike's <tt>import</tt> statement:
- </p>
- <div class="code"><pre>
- $ <b>pike</b>
- Pike v7.4 release 10 running Hilfe v3.5 (Incremental Pike Frontend)
- > <b>import example;</b>
- > <b>fact(4);</b>
- (1) Result: 24
- </pre></div>
- <H2><a name="Pike_nn6"></a>33.2 Basic C/C++ Mapping</H2>
- <H3><a name="Pike_nn7"></a>33.2.1 Modules</H3>
- <p>
- All of the code for a given SWIG module is wrapped into a single Pike
- module. Since the name of the shared library that implements your
- module ultimately determines the module's name (as far as Pike is
- concerned), SWIG's <tt>%module</tt> directive doesn't really have any
- significance.
- </p>
- <H3><a name="Pike_nn8"></a>33.2.2 Functions</H3>
- <p>
- Global functions are wrapped as new Pike built-in functions. For
- example,
- </p>
- <div class="code"><pre>
- %module example
- int fact(int n);
- </pre></div>
- <p>
- creates a new built-in function <tt>example.fact(n)</tt> that works
- exactly as you'd expect it to:
- </p>
- <div class="code"><pre>
- > <b>import example;</b>
- > <b>fact(4);</b>
- (1) Result: 24
- </pre></div>
- <H3><a name="Pike_nn9"></a>33.2.3 Global variables</H3>
- <p>
- Global variables are currently wrapped as a pair of functions, one to get
- the current value of the variable and another to set it. For example, the
- declaration
- </p>
- <div class="code"><pre>
- %module example
- double Foo;
- </pre></div>
- <p>
- will result in two functions, <tt>Foo_get()</tt> and <tt>Foo_set()</tt>:
- </p>
- <div class="code"><pre>
- > <b>import example;</b>
- > <b>Foo_get();</b>
- (1) Result: 3.000000
- > <b>Foo_set(3.14159);</b>
- (2) Result: 0
- > <b>Foo_get();</b>
- (3) Result: 3.141590
- </pre></div>
- <H3><a name="Pike_nn10"></a>33.2.4 Constants and enumerated types</H3>
- <p>
- Enumerated types in C/C++ declarations are wrapped as Pike constants,
- not as Pike enums.
- </p>
- <H3><a name="Pike_nn11"></a>33.2.5 Constructors and Destructors</H3>
- <p>
- Constructors are wrapped as <tt>create()</tt> methods, and destructors are
- wrapped as <tt>destroy()</tt> methods, for Pike classes.
- </p>
- <H3><a name="Pike_nn12"></a>33.2.6 Static Members</H3>
- <p>
- Since Pike doesn't support static methods or data for Pike classes, static
- member functions in your C++ classes are wrapped as regular functions and
- static member variables are wrapped as pairs of functions (one to get the
- value of the static member variable, and another to set it). The names of
- these functions are prepended with the name of the class.
- For example, given this C++ class declaration:
- </p>
- <div class="code"><pre>
- class Shape
- {
- public:
- static void print();
- static int nshapes;
- };
- </pre></div>
- <p>
- SWIG will generate a <tt>Shape_print()</tt> method that invokes the static
- <tt>Shape::print()</tt> member function, as well as a pair of methods,
- <tt>Shape_nshapes_get()</tt> and <tt>Shape_nshapes_set()</tt>, to get and set
- the value of <tt>Shape::nshapes</tt>.
- </p>
- </body>
- </html>