Doc/Manual/Pike.html

   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>30 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>
  35 This chapter describes SWIG support for Pike. As of this writing, the
  36 SWIG  Pike module is still under development and is not considered
  37 ready for prime  time. The Pike module is being developed against the
  38 Pike 7.4.10 release  and may not be compatible with previous versions
  39 of Pike.
  40 </p>
  41
  42 <p>
  43 This chapter covers most SWIG features, but certain low-level details
  44 are  covered in less depth than in earlier chapters.  At the very
  45 least, make sure you read the "<a href="SWIG.html#SWIG">SWIG Basics</a>"
  46 chapter.<br>
  47 </p>
  48
  49 <H2><a name="Pike_nn2"></a>30.1 Preliminaries</H2>
  50
  51
  52 <H3><a name="Pike_nn3"></a>30.1.1 Running SWIG</H3>
  53
  54
  55 <p>
  56 Suppose 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>
  64 To 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>
  72 If 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>
  80 This creates a single source file named <tt>example_wrap.c</tt> (or <tt>example_wrap.cxx</tt>, if you
  81 ran SWIG with the <tt>-c++</tt> option).
  82 The SWIG-generated source file contains the low-level wrappers that need
  83 to be compiled and linked with the rest of your C/C++ application to
  84 create an extension module.
  85 </p>
  86
  87 <p>
  88 The name of the wrapper file is derived from the name of the input
  89 file.  For example, if the input file is <tt>example.i</tt>, the name
  90 of the wrapper file is <tt>example_wrap.c</tt>. To change this, you
  91 can 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>30.1.2 Getting the right header files</H3>
  98
  99
 100 <p>
 101 In order to compile the C/C++ wrappers, the compiler needs to know the
 102 path to the Pike header files. These files are usually contained in a
 103 directory 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>
 111 There doesn't seem to be any way to get Pike itself to reveal the
 112 location of these files, so you may need to hunt around for them.
 113 You're looking for files with the names <tt>global.h</tt>, <tt>program.h</tt>
 114 and so on.
 115 </p>
 116
 117 <H3><a name="Pike_nn5"></a>30.1.3 Using your module</H3>
 118
 119
 120 <p>
 121 To use your module, simply use Pike's <tt>import</tt> statement:
 122 </p>
 123
 124 <div class="code"><pre>
 125 $ <b>pike</b>
 126 Pike 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>30.2 Basic C/C++ Mapping</H2>
 133
 134
 135 <H3><a name="Pike_nn7"></a>30.2.1 Modules</H3>
 136
 137
 138 <p>
 139 All of the code for a given SWIG module is wrapped into a single Pike
 140 module. Since the name of the shared library that implements your
 141 module ultimately determines the module's name (as far as Pike is
 142 concerned), SWIG's <tt>%module</tt> directive doesn't really have any
 143 significance.
 144 </p>
 145
 146 <H3><a name="Pike_nn8"></a>30.2.2 Functions</H3>
 147
 148
 149 <p>
 150 Global functions are wrapped as new Pike built-in functions. For
 151 example,
 152 </p>
 153
 154 <div class="code"><pre>
 155 %module example
 156
 157 int fact(int n);
 158 </pre></div>
 159
 160 <p>
 161 creates a new built-in function <tt>example.fact(n)</tt> that works
 162 exactly 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>30.2.3 Global variables</H3>
 172
 173
 174 <p>
 175 Global variables are currently wrapped as a pair of of functions, one to get
 176 the current value of the variable and another to set it. For example, the
 177 declaration
 178 </p>
 179
 180 <div class="code"><pre>
 181 %module example
 182
 183 double Foo;
 184 </pre></div>
 185
 186 <p>
 187 will 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>30.2.4 Constants and enumerated types</H3>
 201
 202
 203 <p>
 204 Enumerated types in C/C++ declarations are wrapped as Pike constants,
 205 not as Pike enums.
 206 </p>
 207
 208 <H3><a name="Pike_nn11"></a>30.2.5 Constructors and Destructors</H3>
 209
 210
 211 <p>
 212 Constructors are wrapped as <tt>create()</tt> methods, and destructors are
 213 wrapped as <tt>destroy()</tt> methods, for Pike classes.
 214 </p>
 215
 216 <H3><a name="Pike_nn12"></a>30.2.6 Static Members</H3>
 217
 218
 219 <p>
 220 Since Pike doesn't support static methods or data for Pike classes, static
 221 member functions in your C++ classes are wrapped as regular functions and
 222 static member variables are wrapped as pairs of functions (one to get the
 223 value of the static member variable, and another to set it). The names of
 224 these functions are prepended with the name of the class.
 225 For example, given this C++ class declaration:
 226 </p>
 227
 228 <div class="code"><pre>
 229 class Shape
 230 {
 231 public:
 232     static void print();
 233     static int nshapes;
 234 };
 235 </pre></div>
 236
 237 <p>
 238 SWIG 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
 241 the value of <tt>Shape::nshapes</tt>.
 242 </p>
 243
 244 </body>
 245 </html>