PageRenderTime 25ms CodeModel.GetById 11ms app.highlight 8ms RepoModel.GetById 2ms app.codeStats 0ms

/trunk/Doc/Manual/Pike.html

#
HTML | 245 lines | 186 code | 57 blank | 2 comment | 0 complexity | 1615c1434c17c14789ad92e843f47f5b MD5 | raw file
  1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
  2<html>
  3<head>
  4<title>SWIG and Pike</title>
  5<link rel="stylesheet" type="text/css" href="style.css">
  6</head>
  7
  8<body bgcolor="#ffffff">
  9<H1><a name="Pike"></a>33 SWIG and Pike</H1>
 10<!-- INDEX -->
 11<div class="sectiontoc">
 12<ul>
 13<li><a href="#Pike_nn2">Preliminaries</a>
 14<ul>
 15<li><a href="#Pike_nn3">Running SWIG</a>
 16<li><a href="#Pike_nn4">Getting the right header files</a>
 17<li><a href="#Pike_nn5">Using your module</a>
 18</ul>
 19<li><a href="#Pike_nn6">Basic C/C++ Mapping</a>
 20<ul>
 21<li><a href="#Pike_nn7">Modules</a>
 22<li><a href="#Pike_nn8">Functions</a>
 23<li><a href="#Pike_nn9">Global variables</a>
 24<li><a href="#Pike_nn10">Constants and enumerated types</a>
 25<li><a href="#Pike_nn11">Constructors and Destructors</a>
 26<li><a href="#Pike_nn12">Static Members</a>
 27</ul>
 28</ul>
 29</div>
 30<!-- INDEX -->
 31
 32
 33
 34<p>
 35This chapter describes SWIG support for Pike. As of this writing, the
 36SWIG  Pike module is still under development and is not considered
 37ready for prime  time. The Pike module is being developed against the
 38Pike 7.4.10 release  and may not be compatible with previous versions
 39of Pike.
 40</p>
 41
 42<p>
 43This chapter covers most SWIG features, but certain low-level details
 44are  covered in less depth than in earlier chapters.  At the very
 45least, make sure you read the "<a href="SWIG.html#SWIG">SWIG Basics</a>"
 46chapter.<br>
 47</p>
 48
 49<H2><a name="Pike_nn2"></a>33.1 Preliminaries</H2>
 50
 51
 52<H3><a name="Pike_nn3"></a>33.1.1 Running SWIG</H3>
 53
 54
 55<p>
 56Suppose that you defined a SWIG module such as the following:
 57</p>
 58
 59<div class="code">
 60  <pre>%module example<br><br>%{<br>#include "example.h"<br>%}<br><br>int fact(int n);<br></pre>
 61</div>
 62
 63<p>
 64To build a C extension module for Pike, run SWIG using the <tt>-pike</tt> option :
 65</p>
 66
 67<div class="code">
 68  <pre>$ <b>swig -pike example.i</b><br></pre>
 69</div>
 70
 71<p>
 72If you're building a C++ extension, be sure to add the <tt>-c++</tt> option:
 73</p>
 74
 75<div class="code">
 76  <pre>$ <b>swig -c++ -pike example.i</b><br></pre>
 77</div>
 78
 79<p>
 80This creates a single source file named <tt>example_wrap.c</tt> (or <tt>example_wrap.cxx</tt>, if you
 81ran SWIG with the <tt>-c++</tt> option).
 82The SWIG-generated source file contains the low-level wrappers that need
 83to be compiled and linked with the rest of your C/C++ application to
 84create an extension module.
 85</p>
 86
 87<p>
 88The name of the wrapper file is derived from the name of the input
 89file.  For example, if the input file is <tt>example.i</tt>, the name
 90of the wrapper file is <tt>example_wrap.c</tt>. To change this, you
 91can use the <tt>-o</tt> option:
 92</p>
 93
 94<div class="code">
 95  <pre>$ <b>swig -pike -o pseudonym.c example.i</b><br></pre>
 96</div>
 97<H3><a name="Pike_nn4"></a>33.1.2 Getting the right header files</H3>
 98
 99
100<p>
101In order to compile the C/C++ wrappers, the compiler needs to know the
102path to the Pike header files. These files are usually contained in a
103directory such as
104</p>
105
106<div class="code">
107  <pre>/usr/local/pike/7.4.10/include/pike<br></pre>
108</div>
109
110<p>
111There doesn't seem to be any way to get Pike itself to reveal the
112location of these files, so you may need to hunt around for them.
113You're looking for files with the names <tt>global.h</tt>, <tt>program.h</tt>
114and so on.
115</p>
116
117<H3><a name="Pike_nn5"></a>33.1.3 Using your module</H3>
118
119
120<p>
121To use your module, simply use Pike's <tt>import</tt> statement:
122</p>
123
124<div class="code"><pre>
125$ <b>pike</b>
126Pike v7.4 release 10 running Hilfe v3.5 (Incremental Pike Frontend)
127&gt; <b>import example;</b>
128&gt; <b>fact(4);</b>
129(1) Result: 24
130</pre></div>
131
132<H2><a name="Pike_nn6"></a>33.2 Basic C/C++ Mapping</H2>
133
134
135<H3><a name="Pike_nn7"></a>33.2.1 Modules</H3>
136
137
138<p>
139All of the code for a given SWIG module is wrapped into a single Pike
140module. Since the name of the shared library that implements your
141module ultimately determines the module's name (as far as Pike is
142concerned), SWIG's <tt>%module</tt> directive doesn't really have any
143significance.
144</p>
145
146<H3><a name="Pike_nn8"></a>33.2.2 Functions</H3>
147
148
149<p>
150Global functions are wrapped as new Pike built-in functions. For
151example,
152</p>
153
154<div class="code"><pre>
155%module example
156
157int fact(int n);
158</pre></div>
159
160<p>
161creates a new built-in function <tt>example.fact(n)</tt> that works
162exactly as you'd expect it to:
163</p>
164
165<div class="code"><pre>
166&gt; <b>import example;</b>
167&gt; <b>fact(4);</b>
168(1) Result: 24
169</pre></div>
170
171<H3><a name="Pike_nn9"></a>33.2.3 Global variables</H3>
172
173
174<p>
175Global variables are currently wrapped as a pair of functions, one to get
176the current value of the variable and another to set it. For example, the
177declaration
178</p>
179
180<div class="code"><pre>
181%module example
182
183double Foo;
184</pre></div>
185
186<p>
187will result in two functions, <tt>Foo_get()</tt> and <tt>Foo_set()</tt>:
188</p>
189
190<div class="code"><pre>
191&gt; <b>import example;</b>
192&gt; <b>Foo_get();</b>
193(1) Result: 3.000000
194&gt; <b>Foo_set(3.14159);</b>
195(2) Result: 0
196&gt; <b>Foo_get();</b>
197(3) Result: 3.141590
198</pre></div>
199
200<H3><a name="Pike_nn10"></a>33.2.4 Constants and enumerated types</H3>
201
202
203<p>
204Enumerated types in C/C++ declarations are wrapped as Pike constants,
205not as Pike enums.
206</p>
207
208<H3><a name="Pike_nn11"></a>33.2.5 Constructors and Destructors</H3>
209
210
211<p>
212Constructors are wrapped as <tt>create()</tt> methods, and destructors are
213wrapped as <tt>destroy()</tt> methods, for Pike classes.
214</p>
215
216<H3><a name="Pike_nn12"></a>33.2.6 Static Members</H3>
217
218
219<p>
220Since Pike doesn't support static methods or data for Pike classes, static
221member functions in your C++ classes are wrapped as regular functions and
222static member variables are wrapped as pairs of functions (one to get the
223value of the static member variable, and another to set it). The names of
224these functions are prepended with the name of the class.
225For example, given this C++ class declaration:
226</p>
227
228<div class="code"><pre>
229class Shape
230{
231public:
232    static void print();
233    static int nshapes;
234};
235</pre></div>
236
237<p>
238SWIG will generate a <tt>Shape_print()</tt> method that invokes the static
239<tt>Shape::print()</tt> member function, as well as a pair of methods,
240<tt>Shape_nshapes_get()</tt> and <tt>Shape_nshapes_set()</tt>, to get and set
241the value of <tt>Shape::nshapes</tt>.
242</p>
243
244</body>
245</html>